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