#ifndef __DALI_TOOLKIT_UIBUILDER_H__
#define __DALI_TOOLKIT_UIBUILDER_H__
-//
-// Copyright (c) 2014 Samsung Electronics Co., Ltd.
-//
-// Licensed under the Flora License, Version 1.0 (the License);
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-// http://floralicense.org/license/
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an AS IS BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-//
-
-// INTERNAL INCLUDES
-#include <dali/dali.h>
-
-namespace Dali DALI_IMPORT_API
+/*
+ * Copyright (c) 2014 Samsung Electronics Co., Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+// 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
{
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
+ *
+ * - 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
*
- * // or 2) create an actor from the library "styles" section
- * TextActor actor = TextActor::DownCast( builder.CreateFromStyle( "default-text" ) );
+ * - 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:
/**
static Builder New();
/**
- * Virtual destructor.
+ * @brief Destructor
+ *
+ * This is non-virtual since derived Handle types must not contain data or virtual methods.
*/
- virtual ~Builder();
+ ~Builder();
/**
* UI string data format
* @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 builder.AddConstant( "IMAGE_DIRECTORY", "/usr/share/images" );
+ * @code
+ * builder.AddConstant( "IMAGE_DIRECTORY", "/usr/share/images" );
+ * @endcode
*
* @pre The Builder has been initialized.
* @param key The constant name to add or update
* @brief Gets all currently defined constants.
*
* e.g.
- * @code PropertyValueMap map = builder.GetConstants(); // get copy of current constants
- * map["IMAGE_DIRECTORY"] = "/usr/share/images"; // make modification
- * builder.AddConstants( map ); // write back changes
+ * @code
+ * 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
- * map["IMAGE_DIRECTORY"] = "/usr/share/images"; // make modification
- * builder.AddConstants( map ); // write back changes
+ * @code
+ * 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.
* @param key The constant name to search for.
* @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.
+ * 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.
+ * 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);
+ *
+ * @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 Property::Map& map, Dali::Actor sourceActor );
/**
* @brief Creates an object (e.g. an actor) from the set of known style templates
*
* e.g.
- * mActor.Add( Actor::DownCast(builder.CreateFromStyle( "default-text")) );
+ * 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 styleName has been loaded from the styles section of the data representation
+ * @pre The templateName exists in the templates 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.
+ * @param templateName The template to apply in creation.
* @returns The base handle of the created object
*/
- BaseHandle CreateFromStyle( const std::string& styleName );
+ BaseHandle Create( const std::string& templateName );
/**
* @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.CreateFromStyle( "default-image", map) ) );
+ * 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 styleName has been loaded from the styles section of the data representation
+ * @pre The templateName exists in the templates section of the data representation
* and contains 'type' property used to create the object.
- * @pre The map contains all the constant expansions in the style template
- * @param styleName The set of styles/properties to set on the handle object.
- * @param map The user defined constants used in style template expansion.
+ * @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 CreateFromStyle( const std::string& styleName, 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.
* @pre Preconditions have been met for creating dali objects ie Images, Actors etc
* @param styleName The name of the set of style properties to set on the handle object.
* @param handle Then handle of the object on which to set the properties.
+ *
+ * @return Return true if the style was found
+ */
+ 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
*/
- void ApplyStyle( const std::string& styleName, Handle& handle );
+ bool ApplyFromJson( Handle& handle, const std::string& json );
+
/**
* Add the actor tree in the "stage" section to the actor toActor.
void AddActors( const std::string §ionName, Actor toActor );
/**
- * @deprecated Font as a separate asset is no longer supported
- * Get's a Font asset previously created at load time
- * An empty handle is returned otherwise.
- * @pre The Builder has been initialized.
- * @param name The name given to a Font in the loaded representation
- * @return A handle to a Font if found, otherwise empty.
- */
- Font GetFont( const std::string &name ) const;
-
- /**
- * Get's a TextStyle asset previously created at load time
- * @pre The Builder has been initialized.
- * @param name The name given to a TextStyle in the loaded representation
- * @return a Created TextStyle if found, otherwise return a TextStyle created by Default constructor
- */
- TextStyle GetTextStyle( const std::string &name ) const;
-
- /**
- * @deprecated Images as a separate asset is no longer supported
- * Get's an Image asset previously created at load time
- * An empty handle is returned otherwise.
- * @pre The Builder has been initialized.
- * @param name The name given to an Image in the loaded representation
- * @return A handle to an Image if found, otherwise empty
- */
- Image GetImage( const std::string &name ) const;
-
- /**
- * @deprecated Actors no longer held by builder
- * Get's an Actor previously created at load time
- * An empty handle is returned otherwise.
- * @pre The Builder has been initialized.
- * @param name The name given to an Actor in the loaded representation
- * @return A handle to an Actor if found, otherwise empty
- */
- Actor GetActor( const std::string &name ) const;
-
- /**
- * @deprecated Animations no longer held by builder
- * Get's an Animation previously created at load time
- * An empty handle is returned otherwise.
- * @pre The Builder has been initialized.
- * @param name The name given to an Animation in the loaded representation
- * @return A handle to an Animation if found, otherwise empty
- */
- Animation GetAnimation( const std::string &name ) const;
-
- /**
* Create a render task set.
* @pre The Builder has been initialized.
* @param name The library name of the render task set.
FrameBufferImage GetFrameBufferImage( const std::string &name );
/**
- * @deprecated. Builder no longer holds actor handles/references
- * Provides a list of the top level actors previously created at load time
- * @return A container of Actors found at the top level of the loaded representation
+ * 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 Signal< void () > BuilderSignalType;
+
+ /**
+ * @brief Signal emitted when a quit action is requested by the builder.
*/
- ActorContainer GetTopLevelActors( void ) const;
+ BuilderSignalType& QuitSignal();
private:
- Builder(Internal::Builder *impl);
+ explicit DALI_INTERNAL Builder(Internal::Builder *impl);
}; // class Builder
projects / platform / core / uifw / dali-toolkit.git / blobdiff