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

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