class Builder;
}
+typedef std::map<std::string, Property::Value> PropertyValueMap;
+
/**
* Builder
* This class provides the ability to load an actor tree from a string representation.
* // 1) load all actors in the "stage" section to the root layer
* builder.AddActors( Stage::GetCurrent().GetRootLayer() );
*
- * // or 2) create an actor from the library "styles" section
- * TextActor actor = TextActor::DownCast( builder.CreateFromStyle( "default-text" ) );
+ * // or 2) create an actor from the library "templates" section
+ * TextActor actor = TextActor::DownCast( builder.Create( "default-text" ) );
*
* @endcode
*/
void LoadFromString( const std::string& data, UIFormat format = JSON );
/**
+ * @brief Adds user defined constants to all future style template or animation expansions
+ *
+ * e.g.
+ * PropertyValueMap map;
+ * map["IMAGE_DIRECTORY"] = "/usr/share/images";
+ * builder.AddConstants( map );
+ *
+ * @pre The Builder has been initialized.
+ * @param map The user defined constants used in template expansions.
+ */
+ void AddConstants( const PropertyValueMap& map );
+
+ /**
+ * @brief Adds or modifies a user defined constant to all future style template or animation expansions
+ *
+ * e.g.
+ * builder.AddConstant( "IMAGE_DIRECTORY", "/usr/share/images" );
+ *
+ * @pre The Builder has been initialized.
+ * @param key The constant name to add or update
+ * @param value The new value for the constant.
+ */
+ void AddConstant( const std::string& key, const Property::Value& value );
+
+ /**
+ * @brief Gets all currently defined constants.
+ *
+ * e.g.
+ * PropertyValueMap map = builder.GetConstants(); // get copy of current constants
+ * map["IMAGE_DIRECTORY"] = "/usr/share/images"; // make modification
+ * builder.AddConstants( map ); // write back changes
+ *
+ * @pre The Builder has been initialized.
+ * @return A reference to the currently defined constants.
+ */
+ const PropertyValueMap& GetConstants() const;
+
+ /**
+ * @brief Gets a currently defined constant, or returns Property::INVALID
+ *
+ * e.g.
+ * PropertyValueMap map = builder.GetConstants(); // get copy of current constants
+ * map["IMAGE_DIRECTORY"] = "/usr/share/images"; // make modification
+ * builder.AddConstants( map ); // write back changes
+ *
+ * @pre The Builder has been initialized.
+ * @param key The constant name to search for.
+ */
+ const Property::Value& GetConstant( const std::string& key ) const;
+
+ /**
* Creates an animation from the set of known animations
* e.g.
* Animation a = builder.CreateAnimation( "wobble");
Animation CreateAnimation( const std::string& animationName );
/**
- * Creates an object (e.g. an actor) from the set of known styles
+ * @brief Creates an animation from the set of known animations with user defined constants
+ *
* e.g.
- * mActor.Add( Actor::DownCast(builder.CreateFromStyle( "default-text")) );
+ * PropertyValueMap map;
+ * map["ACTOR"] = actor.GetName(); // replaces '{ACTOR} in the template
+ * Animation a = builder.CreateAnimation( "wobble");
*
* @pre The Builder has been initialized.
* @pre Preconditions have been met for creating dali objects ie Images, Actors etc
- * @pre The styleName has been loaded from the styles section of the data representation
- * and contains 'type' property used to create the object.
- * @param styleName The set of styles/properties to set on the handle object.
+ * @pre The animationName exists in the animations section of the data representation
+ * @pre The map contains all the constant expansions in the style template
+ * @param animationName The animation name to create
+ * @param map The user defined constants used in style template expansion.
+ * @returns The base handle of the created object
+ */
+ Animation CreateAnimation( const std::string& animationName, const PropertyValueMap& map );
+
+ /**
+ * @brief Creates an animation from the set of known animations.
+ *
+ * The animation is applied to a specific actor.
+ * e.g.
+ * Actor myInstance = builder.Create( "template-actor-tree" )
+ * Animation a = builder.CreateAnimation( "wobble", myInstance );
+ *
+ * @pre The Builder has been initialized.
+ * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
+ * @pre The animationName exists in the animations section of the data representation
+ * @param animationName The animation name to create
+ * @param sourceActor The starting point in an actor tree, from which to look for property owners
* @returns The base handle of the created object
*/
+ Animation CreateAnimation( const std::string& animationName, Dali::Actor sourceActor );
+
+ /**
+ * @brief Creates an animation from the set of known animations with user defined constants
+ *
+ * The animation is applied to a specific actor.
+ * e.g.
+ * PropertyValueMap map;
+ * map["ACTOR"] = actor.GetName(); // replaces '{ACTOR} in the template
+ * Actor myInstance = builder.Create( "template-actor-tree" )
+ * Animation a = builder.CreateAnimation( "wobble", myInstance);
+ *
+ * @pre The Builder has been initialized.
+ * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
+ * @pre The animationName exists in the animations section of the data representation
+ * @pre The map contains all the constant expansions in the style template
+ * @param animationName The animation name to create
+ * @param map The user defined constants used in style template expansion.
+ * @param sourceActor The starting point in an actor tree, from which to look for property owners
+ * @returns The base handle of the created object
+ */
+ Animation CreateAnimation( const std::string& animationName, const PropertyValueMap& map, Dali::Actor sourceActor );
+
+ /**
+ * @deprecated Use Create()
+ */
BaseHandle CreateFromStyle( const std::string& styleName );
/**
+ * @deprecated Use Create()
+ */
+ BaseHandle CreateFromStyle( const std::string& styleName, const PropertyValueMap& map );
+
+ /**
+ * @brief Creates an object (e.g. an actor) from the set of known style templates
+ *
+ * e.g.
+ * mActor.Add( Actor::DownCast(builder.Create( "default-text")) );
+ *
+ * @pre The Builder has been initialized.
+ * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
+ * @pre The templateName exists in the templates section of the data representation
+ * and contains 'type' property used to create the object.
+ * @param templateName The template to apply in creation.
+ * @returns The base handle of the created object
+ */
+ BaseHandle Create( const std::string& templateName );
+
+ /**
+ * @brief Creates an object from the style templates with user defined constants
+ *
+ * e.g.
+ * PropertyValueMap map;
+ * map["IMAGE_DIR"] = "/usr/share/images"; // replaces '{IMAGE_DIR} in the template
+ * mActor.Add( Actor::DownCast(builder.Create( "default-image", map) ) );
+ *
+ * @pre The Builder has been initialized.
+ * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
+ * @pre The templateName exists in the templates section of the data representation
+ * and contains 'type' property used to create the object.
+ * @param templateName The template used to create the object.
+ * @param map The user defined constants used in template expansion.
+ * @returns The base handle of the created object
+ */
+ BaseHandle Create( const std::string& templateName, const PropertyValueMap& map );
+
+ /**
* Apply a style (a collection of properties) to an actor.
* @pre The Builder has been initialized.
* @pre Preconditions have been met for creating dali objects ie Images, Actors etc