dali-toolkit/devel-api/builder/builder.h

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