APL-CORE: December 2021 Release of APL 1.9 compilant core engine (1.9.0)

For more details on this release refer to CHANGELOG.md

To learn about APL see: https://developer.amazon.com/docs/alexa-presentation-language/understand-apl.html

Author: durjo-amz

CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [1.9.0]
+
+This release adds support for version 1.9 of the APL specification.
+
+### Added
+
+- Added new flag to disallow video player.
+- Added new gesture, Tap.
+- Added support for animating bound values and vector graphic parameters.
+- Added support for source http headers on images, vector graphics and video tracks.
+- Allow config change objects to contain custom environment property values.
+
+### Changed
+
+- Alpha feature: APL Extension logic is no longer interleaved with APL
+- Bug fixes.
+- Build improvements.
+
 ## [1.8.1]
 
 ### Changed
@@ -28,6 +46,12 @@ This release adds support for version 1.8 of the APL specification.
 - Bug fixes
 - Build improvements
 
+## [1.7.2]
+
+### Changed
+
+- Bug fixes
+
 ## [1.7.1]
 
 ### Changed
@@ -61,6 +85,12 @@ This release adds support for version 1.7 of the APL specification.
 - Other bug fixes
 - Build improvements
 
+## [1.6.3]
+
+### Changed
+
+- Bug fixes
+
 ## [1.6.2]
 
 ### Changed

aplcore/CMakeLists.txt

@@ -115,11 +115,15 @@ target_link_libraries(apl
             libyoga)
 
 # include the alexa extensions library
-if (BUILD_ALEXAEXTENSIONS)
+if (ENABLE_ALEXAEXTENSIONS)
+    if (NOT BUILD_ALEXAEXTENSIONS)
+        # Check to see if it's available from the system.
+        find_package(alexaext REQUIRED)
+    endif (NOT BUILD_ALEXAEXTENSIONS)
     target_link_libraries(apl
         PUBLIC
             alexa::extensions)
-endif(BUILD_ALEXAEXTENSIONS)
+endif(ENABLE_ALEXAEXTENSIONS)
 
 # Log dependencies for Android
 

aplcore/aplcoreConfig.cmake.in

@@ -13,6 +13,12 @@ else()
 
 endif()
 
+set(USE_INTERNAL_ALEXAEXT @BUILD_ALEXAEXTENSIONS@)
+
+if(NOT USE_INTERNAL_ALEXAEXT)
+    find_package(alexaext REQUIRED)
+endif()
+
 include("${CMAKE_CURRENT_LIST_DIR}/aplcoreTargets.cmake")
 
 set_target_properties(apl::core

aplcore/include/apl/animation/animatedproperty.h

@@ -19,6 +19,7 @@
 #include "apl/common.h"
 #include "apl/component/componentproperties.h"
 #include "apl/primitives/transform.h"
+#include "apl/utils/make_unique.h"
 #include "apl/utils/noncopyable.h"
 
 namespace apl {
@@ -34,31 +35,36 @@ class AnimatedProperty : public NonCopyable {
                                                     const Object& object);
 
     virtual void update(const CoreComponentPtr& component, float alpha) = 0;
-
-    virtual PropertyKey key() const = 0;
+    virtual std::string key() const = 0;
 };
 
 class AnimatedDouble : public AnimatedProperty {
 public:
-    AnimatedDouble(PropertyKey key, double from, double to);
-    AnimatedDouble(PropertyKey key, const CoreComponentPtr& component, double to);
+    static std::unique_ptr<AnimatedDouble> create(PropertyKey key, std::string property, double from, double to) {
+        return std::make_unique<AnimatedDouble>(key, std::move(property), from, to);
+    }
 
-    void update(const CoreComponentPtr& component, float alpha) override;
+    AnimatedDouble(PropertyKey key, std::string property, double from, double to)
+        : mKey(key), mProperty(std::move(property)), mFrom(from), mTo(to) {}
 
-    PropertyKey key() const override { return mKey; }
+private:
+    void update(const CoreComponentPtr& component, float alpha) override;
+    std::string key() const override { return mProperty; }
 
 private:
     PropertyKey mKey;  // The component property we're animating
+    std::string mProperty;
     double mFrom;  // The from value
     double mTo;    // The to value
 };
 
 class AnimatedTransform : public AnimatedProperty {
 public:
-    AnimatedTransform(const std::shared_ptr<InterpolatedTransformation>& transformation);
+    explicit AnimatedTransform(std::shared_ptr<InterpolatedTransformation> transformation);
+
     void update(const CoreComponentPtr& component, float alpha) override;
+    std::string key() const override { return "transform"; }
 
-    PropertyKey key() const override { return kPropertyTransform; }
 private:
     std::shared_ptr<InterpolatedTransformation> mTransformation;
 };

aplcore/include/apl/apl_config.h.in

@@ -13,6 +13,15 @@
  * permissions and limitations under the License.
  */
 
+#ifndef _APL_GENERATED_CONFIG_H
+#define _APL_GENERATED_CONFIG_H
+
 /* Build time configuration options */
 
 #cmakedefine USER_DATA_RELEASE_CALLBACKS
+
+#ifndef ALEXAEXTENSIONS
+#cmakedefine ALEXAEXTENSIONS
+#endif //ALEXAEXTENSIONS
+
+#endif //_APL_GENERATED_CONFIG_H

aplcore/include/apl/component/component.h

@@ -289,10 +289,16 @@ class Component : public Counter<Component>,
     virtual bool updateGraphic(const GraphicContentPtr& json);
 
     /**
-      * Updates state of resource associated with extension component
-      * @param state resource state enum.
-      */
-    virtual void updateResourceState(const ExtensionComponentResourceState& state);
+     * Updates state of resource associated with extension component. The extension
+     * is notified of the change.
+     *
+     * @param state resource state enum.
+     * @param errorCode Error code used when the state is kResourceError
+     * @param error Error message used when the state is kResourceError
+     */
+    virtual void updateResourceState(const ExtensionComponentResourceState& state,
+                             int errorCode = 0,
+                             const std::string& error = "");
 
     /*
     * @return The number of children displayed.

aplcore/include/apl/component/componentproperties.h

@@ -612,6 +612,8 @@ enum PropertyKey {
     kPropertyResourceOnFatalError,
     // The state of the rendered resource of an extension component
     kPropertyResourceState,
+    /// The type of the system resource for an extension component
+    kPropertyResourceType,
     /// ContainerComponent child absolute right position
     kPropertyRight,
     /// Component accessibility role

aplcore/include/apl/component/corecomponent.h

@@ -39,6 +39,8 @@ class Pointer;
 struct PointerEvent;
 class StickyChildrenTree;
 
+using ConstComponentPropIterator = std::map<PropertyKey, ComponentPropDef>::const_iterator;
+
 extern const std::string VISUAL_CONTEXT_TYPE_MIXED;
 extern const std::string VISUAL_CONTEXT_TYPE_GRAPHIC;
 extern const std::string VISUAL_CONTEXT_TYPE_TEXT;
@@ -224,11 +226,29 @@ class CoreComponent : public Component,
     bool hasProperty(PropertyKey key) const { return mAssigned.count(key) != 0; }
 
     /**
-     * The opposite of setProperty(), this method retrieves the property value.
+     * Return the value and writeable state of a component property.  This is the opposite of the
+     * setProperty(const std::string& key, const Object& value) method.  It checks for (a) intrinsic
+     * component properties [such as "width"], (b) data-bindings accessible to the component, and
+     * (c) internal component properties that are exposed (currently just the parameters passed
+     * to a vector graphic).  This method is used by animators to read the current value of a
+     * property and to verify that the property can be written with setProperty().
+     * @param key The name of the property
+     * @return The current value of the property and true if the property is writeable.  If the
+     *         property does not exist, returns null and false.
+     */
+    std::pair<Object, bool> getPropertyAndWriteableState(const std::string& key) const;
+
+    /**
+     * Return the value of a component property.  This is the opposite of the
+     * setProperty(const std::string& key, const Object& value) method.  It checks for (a) intrinsic
+     * component properties [such as "width"], (b) data-bindings accessible to the component, and
+     * (c) internal component properties that are exposed (currently just the parameters passed
+     * to a vector graphic). This method is used by the "preserve" property to save existing
+     * property values.
      * @param key The property or data-binding to retrieve
      * @return The value or null if the property does not exist
      */
-    Object getProperty(const std::string& key);
+    Object getProperty(const std::string& key) { return getPropertyAndWriteableState(key).first; }
 
     /**
      * Mark a property as being changed.  This only applies to properties set to
@@ -657,7 +677,16 @@ class CoreComponent : public Component,
     CoreComponentPtr findStateOwner();
 
     /**
-     * Check if component attached to yoga hierarchy.
+     * Check if this component is attached to a yoga hierarchy.
+     *
+     * Note that depending on the components used, an APL document may be laid
+     * out using multiple independent yoga trees, which can introduce
+     * discontinuities in the overall hierarchy. For example, a component may
+     * choose to treat each child as a top-level yoga node for layout purposes
+     * (e.g. Pager). This has the effect that a child may not be "attached" to
+     * its parent component (i.e. isAttached() will return false).
+     *
+     * @return true if the component's yoga node has a parent
      */
     bool isAttached() const;
 
@@ -949,6 +978,26 @@ class CoreComponent : public Component,
      */
     void fixVisualHash(bool useDirtyFlag);
 
+    /**
+     * Set an internal property that is component-specific and not part of the component definition.
+     * This should be overridden in a subclass that supports internal properties.
+     * @param key The name of the property.
+     * @param value The value to set it to.
+     * @return True if the property was found and changed.
+     */
+    virtual bool setPropertyInternal(const std::string& key, const Object& value) { return false; }
+
+    /**
+     * Retrieve an internal property that is component-specific and not part of the component
+     * definition.  This should be overridden in a subclass that supports internal properties.
+     * @param key The name of the property
+     * @return A Object-Boolean pair.  Returns true and the value of the property if it exists and
+     *         can be read.  Returns { NULL, false } if the property is not found.
+     */
+    virtual std::pair<Object, bool> getPropertyInternal(const std::string& key) const {
+        return { Object::NULL_OBJECT(), false };
+    }
+
 private:
     friend streamer& operator<<(streamer&, const Component&);
 
@@ -971,10 +1020,10 @@ class CoreComponent : public Component,
 
     void updateInheritedState();
 
-    bool setPropertyInternal(const ComponentPropDefSet& propDefSet,
-                             PropertyKey key, const Object& value);
+    std::pair<bool, ConstComponentPropIterator> find(PropertyKey key) const;
 
-    virtual bool setPropertyInternal(const std::string& key, const Object& value) { return false; }
+    bool setPropertyInternal(ConstComponentPropIterator it, const Object& value);
+    std::pair<Object, bool> getPropertyInternal(ConstComponentPropIterator it) const;
 
     bool markPropertyInternal(const ComponentPropDefSet& propDefSet, PropertyKey key);
 

aplcore/include/apl/component/imagecomponent.h

@@ -40,7 +40,7 @@ class ImageComponent : public CoreComponent,
     std::string getVisualContextType() const override;
 
     /// Media component trait overrides
-    std::vector<std::string> getSources() override;
+    std::vector<URLRequest> getSources() override;
     EventMediaType mediaType() const override { return kEventMediaTypeImage; }
     void onFail(const MediaObjectPtr&) override;
     void onLoad() override;

aplcore/include/apl/component/mediacomponenttrait.h

@@ -61,7 +61,7 @@ class MediaComponentTrait : public ComponentTrait {
     /**
      * @return vector of source URI's required by component.  Note that order matters.
      */
-    virtual std::vector<std::string> getSources() = 0;
+    virtual std::vector<URLRequest> getSources() = 0;
 
     /**
      * Override this method in your subclass if you need a callback when a pending media object is returned.

aplcore/include/apl/component/vectorgraphiccomponent.h

@@ -48,9 +48,10 @@ class VectorGraphicComponent : public TouchableComponent,
 protected:
     std::string getVisualContextType() const override;
     bool setPropertyInternal(const std::string& key, const Object& value) override;
+    std::pair<Object, bool> getPropertyInternal(const std::string& key) const override;
 
     // Media component trait overrides
-    std::vector<std::string> getSources() override;
+    std::vector<URLRequest> getSources() override;
     EventMediaType mediaType() const override { return kEventMediaTypeVectorGraphic; }
     void onFail(const MediaObjectPtr&) override;
     void onLoad() override;

aplcore/include/apl/content/aplversion.h

@@ -33,6 +33,7 @@ class APLVersion {
         kAPLVersion16 = 0x1U << 6, /// Support version 1.6
         kAPLVersion17 = 0x1U << 7, /// Support version 1.7
         kAPLVersion18 = 0x1U << 8, /// Support version 1.8
+        kAPLVersion19 = 0x1U << 9, /// Support version 1.9
         kAPLVersion10to11 = kAPLVersion10 | kAPLVersion11, /// Convenience ranges from 1.0 to latest,
         kAPLVersion10to12 = kAPLVersion10to11 | kAPLVersion12,
         kAPLVersion10to13 = kAPLVersion10to12 | kAPLVersion13,
@@ -41,9 +42,10 @@ class APLVersion {
         kAPLVersion10to16 = kAPLVersion10to15 | kAPLVersion16,
         kAPLVersion10to17 = kAPLVersion10to16 | kAPLVersion17,
         kAPLVersion10to18 = kAPLVersion10to17 | kAPLVersion18,
-        kAPLVersionLatest = kAPLVersion10to18, /// Support the most recent engine version
-        kAPLVersionDefault = kAPLVersion10to18, /// Default value
-        kAPLVersionReported = kAPLVersion18, /// Default reported version
+        kAPLVersion10to19 = kAPLVersion10to18 | kAPLVersion19,
+        kAPLVersionLatest = kAPLVersion10to19, /// Support the most recent engine version
+        kAPLVersionDefault = kAPLVersion10to19, /// Default value
+        kAPLVersionReported = kAPLVersion19, /// Default reported version
         kAPLVersionAny = 0xffffffff, /// Support any versions in the list
     };