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