X-Git-Url: http://review.tizen.org/git/?p=platform%2Fcore%2Fuifw%2Fdali-toolkit.git;a=blobdiff_plain;f=dali-toolkit%2Fpublic-api%2Fbuilder%2Fbuilder.h;h=2d6709332c46b32bfeccd91c27e0524896b2c97c;hp=8df26191117bc5eac6464721e3eb7a16adface60;hb=6bd46a2944d89638f1c1a1c609f72c9348db6abb;hpb=e2eda444afbe82e9591fe198eef339227f90a616 diff --git a/dali-toolkit/public-api/builder/builder.h b/dali-toolkit/public-api/builder/builder.h index 8df2619..2d67093 100644 --- a/dali-toolkit/public-api/builder/builder.h +++ b/dali-toolkit/public-api/builder/builder.h @@ -31,6 +31,8 @@ namespace Internal DALI_INTERNAL class Builder; } +typedef std::map PropertyValueMap; + /** * Builder * This class provides the ability to load an actor tree from a string representation. @@ -77,8 +79,8 @@ class Builder; * // 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 */ @@ -122,6 +124,57 @@ class Builder; 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"); @@ -135,20 +188,105 @@ class Builder; 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