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

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