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