base/dali-toolkit/public-api/builder/builder.h

   1 #ifndef __DALI_TOOLKIT_UIBUILDER_H__
   2 #define __DALI_TOOLKIT_UIBUILDER_H__
   3
   4 //
   5 // Copyright (c) 2014 Samsung Electronics Co., Ltd.
   6 //
   7 // Licensed under the Flora License, Version 1.0 (the License);
   8 // you may not use this file except in compliance with the License.
   9 // You may obtain a copy of the License at
  10 //
  11 //     http://floralicense.org/license/
  12 //
  13 // Unless required by applicable law or agreed to in writing, software
  14 // distributed under the License is distributed on an AS IS BASIS,
  15 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16 // See the License for the specific language governing permissions and
  17 // limitations under the License.
  18 //
  19
  20 // INTERNAL INCLUDES
  21 #include <dali/dali.h>
  22
  23 namespace Dali DALI_IMPORT_API
  24 {
  25
  26 namespace Toolkit
  27 {
  28
  29 namespace Internal DALI_INTERNAL
  30 {
  31 class Builder;
  32 }
  33
  34 typedef std::map<std::string, Property::Value> PropertyValueMap;
  35
  36 /**
  37  * Builder
  38  * This class provides the ability to load an actor tree from a string representation.
  39  *
  40  * The following example is hello world in JSON.
  41  *
  42  * @code
  43  *
  44  *  {
  45  *    "styles":
  46  *    {
  47  *      "default-text":
  48  *      {
  49  *        "type":"TextActor",
  50  *        "font":"",
  51  *        "parent-origin":[0.5,0.5,0],
  52  *        "scale": [50,50,1]
  53  *      }
  54  *    },
  55  *    "stage":
  56  *    [
  57  *      {
  58  *        "type":"default-text",
  59  *        "text":"Hello World",
  60  *        "position":[0,0,0]
  61  *      },
  62  *    ]
  63  *  }
  64  *
  65  *
  66  *
  67  * @endcode
  68  *
  69  * The following is how to load the json data.
  70  *
  71  * @code
  72  *
  73  * Builder builder = Builder::New();
  74  *
  75  * std::string json_data(ReadFile("layout.json"));
  76  *
  77  * builder.LoadFromString(json_data);
  78  *
  79  * // 1) load all actors in the "stage" section to the root layer
  80  * builder.AddActors( Stage::GetCurrent().GetRootLayer() );
  81  *
  82  * // or 2) create an actor from the library "templates" section
  83  * TextActor actor = TextActor::DownCast( builder.Create( "default-text" ) );
  84  *
  85  * @endcode
  86  */
  87  class Builder : public BaseHandle
  88  {
  89  public:
  90    /**
  91     * Create an Builder handle; this can be initialised with Builder::New()
  92     * Calling member functions with an uninitialised handle is not allowed.
  93     */
  94   Builder();
  95
  96   /**
  97    * Creates an Builder object.
  98    * @return A handle to the Builder control.
  99    */
 100   static Builder New();
 101
 102   /**
 103    * Virtual destructor.
 104    */
 105   virtual ~Builder();
 106
 107   /**
 108    * UI string data format
 109    */
 110   enum UIFormat
 111   {
 112     JSON,                 ///< String is JSON
 113   };
 114
 115   /**
 116    * Loads a string representation of an actor tree into memory.
 117    * The Actor is not automatically added to the stage.
 118    * This function will raise an exception for parse and logical structure errors.
 119    * @pre The Builder has been initialized.
 120    * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
 121    * @param data A string represenation of an Actor tree
 122    * @param format The string representation format ie JSON
 123    */
 124   void LoadFromString( const std::string& data, UIFormat format = JSON );
 125
 126   /**
 127    * @brief Adds user defined constants to all future style template or animation expansions
 128    *
 129    * e.g.
 130    *   PropertyValueMap map;
 131    *   map["IMAGE_DIRECTORY"] = "/usr/share/images";
 132    *   builder.AddConstants( map );
 133    *
 134    * @pre The Builder has been initialized.
 135    * @param map The user defined constants used in template expansions.
 136    */
 137   void AddConstants( const PropertyValueMap& map );
 138
 139   /**
 140    * @brief Adds or modifies a user defined constant to all future style template or animation expansions
 141    *
 142    * e.g.
 143    * @code
 144    * builder.AddConstant( "IMAGE_DIRECTORY", "/usr/share/images" );
 145    * @endcode
 146    *
 147    * @pre The Builder has been initialized.
 148    * @param key The constant name to add or update
 149    * @param value The new value for the constant.
 150    */
 151   void AddConstant( const std::string& key, const Property::Value& value );
 152
 153   /**
 154    * @brief Gets all currently defined constants.
 155    *
 156    * e.g.
 157    * @code
 158    * PropertyValueMap map = builder.GetConstants(); // get copy of current constants
 159    * map["IMAGE_DIRECTORY"] = "/usr/share/images";  // make modification
 160    * builder.AddConstants( map );                   // write back changes
 161    * @endcode
 162    *
 163    * @pre The Builder has been initialized.
 164    * @return A reference to the currently defined constants.
 165    */
 166   const PropertyValueMap& GetConstants() const;
 167
 168   /**
 169    * @brief Gets a currently defined constant, or returns Property::INVALID
 170    *
 171    * e.g.
 172    * @code
 173    * PropertyValueMap map = builder.GetConstants(); // get copy of current constants
 174    * map["IMAGE_DIRECTORY"] = "/usr/share/images";  // make modification
 175    * builder.AddConstants( map );                   // write back changes
 176    * @endcode
 177    *
 178    * @pre The Builder has been initialized.
 179    * @param key The constant name to search for.
 180    */
 181   const Property::Value& GetConstant( const std::string& key ) const;
 182
 183   /**
 184    * Creates an animation from the set of known animations
 185    * e.g.
 186    *   Animation a = builder.CreateAnimation( "wobble");
 187    *
 188    * @pre The Builder has been initialized.
 189    * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
 190    * @pre The animationName exists in the animations section of the data representation
 191    * @param animationName The animation name to create
 192    * @returns The base handle of the created object
 193    */
 194   Animation CreateAnimation( const std::string& animationName );
 195
 196   /**
 197    * @brief Creates an animation from the set of known animations with user defined constants
 198    *
 199    * e.g.
 200    *   PropertyValueMap map;
 201    *   map["ACTOR"] = actor.GetName();       // replaces '{ACTOR} in the template
 202    *   Animation a = builder.CreateAnimation( "wobble");
 203    *
 204    * @pre The Builder has been initialized.
 205    * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
 206    * @pre The animationName exists in the animations section of the data representation
 207    * @pre The map contains all the constant expansions in the style template
 208    * @param animationName The animation name to create
 209    * @param map The user defined constants used in style template expansion.
 210    * @returns The base handle of the created object
 211    */
 212   Animation CreateAnimation( const std::string& animationName, const PropertyValueMap& map );
 213
 214   /**
 215    * @brief Creates an animation from the set of known animations.
 216    *
 217    * The animation is applied to a specific actor.
 218    * e.g.
 219    *   Actor myInstance = builder.Create( "template-actor-tree" )
 220    *   Animation a = builder.CreateAnimation( "wobble", myInstance );
 221    *
 222    * @pre The Builder has been initialized.
 223    * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
 224    * @pre The animationName exists in the animations section of the data representation
 225    * @param animationName The animation name to create
 226    * @param sourceActor The starting point in an actor tree, from which to look for property owners
 227    * @returns The base handle of the created object
 228    */
 229   Animation CreateAnimation( const std::string& animationName, Dali::Actor sourceActor );
 230
 231   /**
 232    * @brief Creates an animation from the set of known animations with user defined constants
 233    *
 234    * The animation is applied to a specific actor.
 235    * e.g.
 236    *   PropertyValueMap map;
 237    *   map["ACTOR"] = actor.GetName();       // replaces '{ACTOR} in the template
 238    *   Actor myInstance = builder.Create( "template-actor-tree" )
 239    *   Animation a = builder.CreateAnimation( "wobble", myInstance);
 240    *
 241    * @pre The Builder has been initialized.
 242    * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
 243    * @pre The animationName exists in the animations section of the data representation
 244    * @pre The map contains all the constant expansions in the style template
 245    * @param animationName The animation name to create
 246    * @param map The user defined constants used in style template expansion.
 247    * @param sourceActor The starting point in an actor tree, from which to look for property owners
 248    * @returns The base handle of the created object
 249    */
 250   Animation CreateAnimation( const std::string& animationName, const PropertyValueMap& map, Dali::Actor sourceActor );
 251
 252   /**
 253    * @deprecated Use Create()
 254    */
 255   BaseHandle CreateFromStyle( const std::string& styleName );
 256
 257   /**
 258    * @deprecated Use Create()
 259    */
 260   BaseHandle CreateFromStyle( const std::string& styleName, const PropertyValueMap& map );
 261
 262   /**
 263    * @brief Creates an object (e.g. an actor) from the set of known style templates
 264    *
 265    * e.g.
 266    *   mActor.Add( Actor::DownCast(builder.Create( "default-text")) );
 267    *
 268    * @pre The Builder has been initialized.
 269    * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
 270    * @pre The templateName exists in the templates section of the data representation
 271    *      and contains 'type' property used to create the object.
 272    * @param templateName The template to apply in creation.
 273    * @returns The base handle of the created object
 274    */
 275   BaseHandle Create( const std::string& templateName );
 276
 277   /**
 278    * @brief Creates an object from the style templates with user defined constants
 279    *
 280    * e.g.
 281    *   PropertyValueMap map;
 282    *   map["IMAGE_DIR"] = "/usr/share/images"; // replaces '{IMAGE_DIR} in the template
 283    *   mActor.Add( Actor::DownCast(builder.Create( "default-image", map) ) );
 284    *
 285    * @pre The Builder has been initialized.
 286    * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
 287    * @pre The templateName exists in the templates section of the data representation
 288    *      and contains 'type' property used to create the object.
 289    * @param templateName The template used to create the object.
 290    * @param map The user defined constants used in template expansion.
 291    * @returns The base handle of the created object
 292    */
 293   BaseHandle Create( const std::string& templateName, const PropertyValueMap& map );
 294
 295   /**
 296    * Apply a style (a collection of properties) to an actor.
 297    * @pre The Builder has been initialized.
 298    * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
 299    * @param styleName The name of the set of style properties to set on the handle object.
 300    * @param handle Then handle of the object on which to set the properties.
 301    *
 302    * @return Return true if the style was found
 303    */
 304   bool ApplyStyle( const std::string& styleName, Handle& handle );
 305
 306   /**
 307    * Add the actor tree in the "stage" section to the actor toActor.
 308    * ie if the representation has a 'stage' section that contains a tree of
 309    * actors then
 310    *    builder.AddActors( Stage::GetCurrent().GetRootLayer() );
 311    * will create and add the actors to the stage root layer.
 312    * @param toActor The actor to add the created actors to
 313    */
 314   void AddActors( Actor toActor );
 315
 316   /**
 317    * Adds actors in the sectionName to the actor toActor.
 318    * ie if the representation has a sectionName section that contains a tree of
 319    * actors then
 320    *    builder.AddActors( sectionName, Stage::GetCurrent().GetRootLayer() );
 321    * will create and add the actors to the stage root layer.
 322    * @param sectionName The section name to search for the actor tree
 323    * @param toActor The actor to add the created actors to
 324    */
 325   void AddActors( const std::string &sectionName, Actor toActor );
 326
 327   /**
 328    * @deprecated Font as a separate asset is no longer supported
 329    * Get's a Font asset previously created at load time
 330    * An empty handle is returned otherwise.
 331    * @pre The Builder has been initialized.
 332    * @param name The name given to a Font in the loaded representation
 333    * @return A handle to a Font if found, otherwise empty.
 334    */
 335   Font GetFont( const std::string &name ) const;
 336
 337   /**
 338    * Get's a TextStyle asset previously created at load time
 339    * @pre The Builder has been initialized.
 340    * @param name The name given to a TextStyle in the loaded representation
 341    * @return a Created TextStyle if found, otherwise return a TextStyle created by Default constructor
 342    */
 343   TextStyle GetTextStyle( const std::string &name ) const;
 344
 345   /**
 346    * @deprecated Images as a separate asset is no longer supported
 347    * Get's an Image asset previously created at load time
 348    * An empty handle is returned otherwise.
 349    * @pre The Builder has been initialized.
 350    * @param name The name given to an Image in the loaded representation
 351    * @return A handle to an Image if found, otherwise empty
 352    */
 353   Image GetImage( const std::string &name ) const;
 354
 355   /**
 356    * @deprecated Actors no longer held by builder
 357    * Get's an Actor previously created at load time
 358    * An empty handle is returned otherwise.
 359    * @pre The Builder has been initialized.
 360    * @param name The name given to an Actor in the loaded representation
 361    * @return A handle to an Actor if found, otherwise empty
 362    */
 363   Actor GetActor( const std::string &name ) const;
 364
 365   /**
 366    * @deprecated Animations no longer held by builder
 367    * Get's an Animation previously created at load time
 368    * An empty handle is returned otherwise.
 369    * @pre The Builder has been initialized.
 370    * @param name The name given to an Animation in the loaded representation
 371    * @return A handle to an Animation if found, otherwise empty
 372    */
 373   Animation GetAnimation( const std::string &name ) const;
 374
 375   /**
 376    * Create a render task set.
 377    * @pre The Builder has been initialized.
 378    * @param name The library name of the render task set.
 379    */
 380   void CreateRenderTask( const std::string &name );
 381
 382   /**
 383    * Get or create ShaderEffect from the ShaderEffect instance library.
 384    * An empty handle is returned otherwise.
 385    * @pre The Builder has been initialized.
 386    * @param name The name of a ShaderEffect in the loaded representation
 387    * @return A handle to a ShaderEffect if found, otherwise empty
 388    */
 389   ShaderEffect GetShaderEffect( const std::string &name );
 390
 391   /**
 392    * Get or create FrameBufferImage from the FrameBufferImage instance library.
 393    * An empty handle is returned otherwise.
 394    * @pre The Builder has been initialized.
 395    * @param name The name of a FrameBufferImage in the loaded representation
 396    * @return A handle to a FrameBufferImage if found, otherwise empty
 397    */
 398   FrameBufferImage GetFrameBufferImage( const std::string &name );
 399
 400   /**
 401    * @deprecated. Builder no longer holds actor handles/references
 402    * Provides a list of the top level actors previously created at load time
 403    * @return A container of Actors found at the top level of the loaded representation
 404    */
 405   ActorContainer GetTopLevelActors( void ) const;
 406
 407 private:
 408   Builder(Internal::Builder *impl);
 409
 410 }; // class Builder
 411
 412 } // namespace Toolkit
 413
 414 } // namespace Dali
 415
 416 #endif // __DALI_TOOLKIT_UIBUILDER_H__