*
*/
-// INTERNAL INCLUDES
-#include <dali/dali.h>
+// EXTERNAL INCLUDES
+#include <dali/public-api/actors/actor.h>
+#include <dali/public-api/animation/animation.h>
+#include <dali/public-api/images/frame-buffer-image.h>
+#include <dali/public-api/shader-effects/shader-effect.h>
-namespace Dali DALI_IMPORT_API
+namespace Dali
{
namespace Toolkit
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.
+ * This class provides the ability to load and style an actor tree from a string representation.
*
- * The following example is hello world in JSON.
+ * The following is an example in JSON.
*
* @code
*
* {
- * "styles":
+ * "templates": // are named instantiable actor trees
* {
* "default-text":
* {
* "scale": [50,50,1]
* }
* },
+ * "styles": // are named property sets applied to actor trees
+ * {
+ * "my-style":
+ * {
+ * "size": [10,10,1] // root properties applied to a given root actor
+ * "actors": // properties applied to actors found by name from root
+ * {
+ * "ok": // properties for an actor named "ok"
+ * {
+ * "scale":[5,5,1],
+ * },
+ * "cancel":
+ * {
+ * "scale":[50,50,1],
+ * }
+ * },
+ * },
+ * },
* "stage":
* [
* {
* ]
* }
*
- *
- *
* @endcode
*
- * The following is how to load the json data.
- *
+ * The following shows a method to load the json file.
* @code
- *
* Builder builder = Builder::New();
- *
* std::string json_data(ReadFile("layout.json"));
- *
* builder.LoadFromString(json_data);
- *
- * // 1) load all actors in the "stage" section to the root layer
+ * @endcode
+ * Examples
+ * - Load all actors in the "stage" section to the root layer
+ * @code
* builder.AddActors( Stage::GetCurrent().GetRootLayer() );
+ * @endcode
*
- * // or 2) create an actor from the library "templates" section
+ * - Create an actor tree from the "templates" section
+ * @code
* TextActor actor = TextActor::DownCast( builder.Create( "default-text" ) );
+ * @endcode
*
+ * - Style an actor tree from the "styles" section
+ * @code
+ * builder.ApplyStyle( "my-style", actor );
+ * @endcode
+ *
+ * - Create an actor tree from json
+ * @code
+ * TextActor actor = TextActor::DownCast( builder.CreateFromJson("{\"type\":\"TextActor\",\"font\":\"\",\"scale\":[50,50,1]}") );
* @endcode
+ *
+ * - Apply a style to an actor tree from json
+ * @code
+ * builder.ApplyFromJson( textActor, ("{\"scale\":[5,5,1]}") );
+ * @endcode
+ *
*/
- class Builder : public BaseHandle
+
+class DALI_IMPORT_API Builder : public BaseHandle
{
public:
/**
* @brief Adds user defined constants to all future style template or animation expansions
*
* e.g.
- * PropertyValueMap map;
+ * Property::Map 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 );
+ void AddConstants( const Property::Map& map );
/**
* @brief Adds or modifies a user defined constant to all future style template or animation expansions
*
* e.g.
* @code
- * PropertyValueMap map = builder.GetConstants(); // get copy of current constants
+ * Property::Map map = builder.GetConstants(); // get copy of current constants
* map["IMAGE_DIRECTORY"] = "/usr/share/images"; // make modification
* builder.AddConstants( map ); // write back changes
* @endcode
* @pre The Builder has been initialized.
* @return A reference to the currently defined constants.
*/
- const PropertyValueMap& GetConstants() const;
+ const Property::Map& GetConstants() const;
/**
* @brief Gets a currently defined constant, or returns Property::INVALID
*
* e.g.
* @code
- * PropertyValueMap map = builder.GetConstants(); // get copy of current constants
+ * Property::Map map = builder.GetConstants(); // get copy of current constants
* map["IMAGE_DIRECTORY"] = "/usr/share/images"; // make modification
* builder.AddConstants( map ); // write back changes
* @endcode
* @brief Creates an animation from the set of known animations with user defined constants
*
* e.g.
- * PropertyValueMap map;
+ * Property::Map map;
* map["ACTOR"] = actor.GetName(); // replaces '{ACTOR} in the template
* Animation a = builder.CreateAnimation( "wobble");
*
* @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 );
+ Animation CreateAnimation( const std::string& animationName, const Property::Map& map );
/**
* @brief Creates an animation from the set of known animations.
*
* The animation is applied to a specific actor.
* e.g.
- * PropertyValueMap map;
+ * Property::Map map;
* map["ACTOR"] = actor.GetName(); // replaces '{ACTOR} in the template
* Actor myInstance = builder.Create( "template-actor-tree" )
* Animation a = builder.CreateAnimation( "wobble", myInstance);
* @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 );
+ Animation CreateAnimation( const std::string& animationName, const Property::Map& map, Dali::Actor sourceActor );
/**
* @brief Creates an object (e.g. an actor) from the set of known style templates
* @brief Creates an object from the style templates with user defined constants
*
* e.g.
- * PropertyValueMap map;
+ * Property::Map map;
* map["IMAGE_DIR"] = "/usr/share/images"; // replaces '{IMAGE_DIR} in the template
* mActor.Add( Actor::DownCast(builder.Create( "default-image", map) ) );
*
* @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 );
+ BaseHandle Create( const std::string& templateName, const Property::Map& map );
+
+ /**
+ * @brief Creates an object (e.g. an actor) from given json snippet
+ *
+ * e.g.
+ * Actor a = Actor::DownCast(builder.CreateFromJson( "{\"type\":\"TextActor\"}"));
+ *
+ * @pre The Builder has been initialized.
+ * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
+ * @param json The json snippet used to create the object.
+ * @returns The base handle of the created object if any
+ */
+ BaseHandle CreateFromJson( const std::string& json );
/**
* Apply a style (a collection of properties) to an actor.
bool ApplyStyle( const std::string& styleName, Handle& handle );
/**
+ * Apply a style (a collection of properties) to an actor from the given json snippet
+ * @pre The Builder has been initialized.
+ * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
+ * @param handle Then handle of the object on which to set the properties.
+ * @param json The json snippet used to create the object.
+ *
+ * @return Return true if the json snippet was parsed
+ */
+ bool ApplyFromJson( Handle& handle, const std::string& json );
+
+
+ /**
* Add the actor tree in the "stage" section to the actor toActor.
* ie if the representation has a 'stage' section that contains a tree of
* actors then
*/
FrameBufferImage GetFrameBufferImage( const std::string &name );
+ /**
+ * Get or create Path from the Path instance library.
+ * An empty handle is returned otherwise.
+ * @pre The Builder has been initialized.
+ * @param name The name of a Path in the loaded representation
+ * @return A handle to a Path if found, otherwise empty
+ */
+ Path GetPath( const std::string &name );
+
+ // Signals
+
+ /**
+ * @brief Builder signal type
+ */
+ typedef SignalV2< void () > Signal;
+
+ /**
+ * @brief Signal emitted when a quit action is requested by the builder.
+ */
+ Signal& QuitSignal();
+
private:
- Builder(Internal::Builder *impl);
+ explicit DALI_INTERNAL Builder(Internal::Builder *impl);
}; // class Builder