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 Flora License, Version 1.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://floralicense.org/license/
  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 // INTERNAL INCLUDES
  21 #include <dali/dali.h>
  22
  23 namespace Dali DALI_IMPORT_API
  24 {
  25
  26 namespace Toolkit
  27 {
  28
  29 namespace Internal DALI_INTERNAL
  30 {
  31 class Builder;
  32 }
  33
  34 /**
  35  * Builder
  36  * This class provides the ability to load an actor tree from a string representation.
  37  *
  38  * The following example is hello world in JSON.
  39  *
  40  * @code
  41  *
  42  *  {
  43  *    "styles":
  44  *    {
  45  *      "default-text":
  46  *      {
  47  *        "type":"TextActor",
  48  *        "font":"",
  49  *        "parent-origin":[0.5,0.5,0],
  50  *        "scale": [50,50,1]
  51  *      }
  52  *    },
  53  *    "stage":
  54  *    [
  55  *      {
  56  *        "type":"default-text",
  57  *        "text":"Hello World",
  58  *        "position":[0,0,0]
  59  *      },
  60  *    ]
  61  *  }
  62  *
  63  *
  64  *
  65  * @endcode
  66  *
  67  * The following is how to load the json data.
  68  *
  69  * @code
  70  *
  71  * Builder builder = Builder::New();
  72  *
  73  * std::string json_data(ReadFile("layout.json"));
  74  *
  75  * builder.LoadFromString(json_data);
  76  *
  77  * // 1) load all actors in the "stage" section to the root layer
  78  * builder.AddActors( Stage::GetCurrent().GetRootLayer() );
  79  *
  80  * // or 2) create an actor from the library "styles" section
  81  * TextActor actor = TextActor::DownCast( builder.CreateFromStyle( "default-text" ) );
  82  *
  83  * @endcode
  84  */
  85  class Builder : public BaseHandle
  86  {
  87  public:
  88    /**
  89     * Create an Builder handle; this can be initialised with Builder::New()
  90     * Calling member functions with an uninitialised handle is not allowed.
  91     */
  92   Builder();
  93
  94   /**
  95    * Creates an Builder object.
  96    * @return A handle to the Builder control.
  97    */
  98   static Builder New();
  99
 100   /**
 101    * Virtual destructor.
 102    */
 103   virtual ~Builder();
 104
 105   /**
 106    * UI string data format
 107    */
 108   enum UIFormat
 109   {
 110     JSON,                 ///< String is JSON
 111   };
 112
 113   /**
 114    * Loads a string representation of an actor tree into memory.
 115    * The Actor is not automatically added to the stage.
 116    * This function will raise an exception for parse and logical structure errors.
 117    * @pre The Builder has been initialized.
 118    * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
 119    * @param data A string represenation of an Actor tree
 120    * @param format The string representation format ie JSON
 121    */
 122   void LoadFromString( const std::string& data, UIFormat format = JSON );
 123
 124   /**
 125    * Creates an animation from the set of known animations
 126    * e.g.
 127    *   Animation a = builder.CreateAnimation( "wobble");
 128    *
 129    * @pre The Builder has been initialized.
 130    * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
 131    * @pre The animationName exists in the animations section of the data representation
 132    * @param animationName The animation name to create
 133    * @returns The base handle of the created object
 134    */
 135   Animation CreateAnimation( const std::string& animationName );
 136
 137   /**
 138    * Creates an object (e.g. an actor) from the set of known styles
 139    * e.g.
 140    *   mActor.Add( Actor::DownCast(builder.CreateFromStyle( "default-text")) );
 141    *
 142    * @pre The Builder has been initialized.
 143    * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
 144    * @pre The styleName has been loaded from the styles section of the data representation
 145    *      and contains 'type' property used to create the object.
 146    * @param styleName The set of styles/properties to set on the handle object.
 147    * @returns The base handle of the created object
 148    */
 149   BaseHandle CreateFromStyle( const std::string& styleName );
 150
 151   /**
 152    * Apply a style (a collection of properties) to an actor.
 153    * @pre The Builder has been initialized.
 154    * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
 155    * @param styleName The name of the set of style properties to set on the handle object.
 156    * @param handle Then handle of the object on which to set the properties.
 157    */
 158   void ApplyStyle( const std::string& styleName, Handle& handle );
 159
 160   /**
 161    * Add the actor tree in the "stage" section to the actor toActor.
 162    * ie if the representation has a 'stage' section that contains a tree of
 163    * actors then
 164    *    builder.AddActors( Stage::GetCurrent().GetRootLayer() );
 165    * will create and add the actors to the stage root layer.
 166    * @param toActor The actor to add the created actors to
 167    */
 168   void AddActors( Actor toActor );
 169
 170   /**
 171    * Adds actors in the sectionName to the actor toActor.
 172    * ie if the representation has a sectionName section that contains a tree of
 173    * actors then
 174    *    builder.AddActors( sectionName, Stage::GetCurrent().GetRootLayer() );
 175    * will create and add the actors to the stage root layer.
 176    * @param sectionName The section name to search for the actor tree
 177    * @param toActor The actor to add the created actors to
 178    */
 179   void AddActors( const std::string &sectionName, Actor toActor );
 180
 181   /**
 182    * @deprecated Font as a separate asset is no longer supported
 183    * Get's a Font asset previously created at load time
 184    * An empty handle is returned otherwise.
 185    * @pre The Builder has been initialized.
 186    * @param name The name given to a Font in the loaded representation
 187    * @return A handle to a Font if found, otherwise empty.
 188    */
 189   Font GetFont( const std::string &name ) const;
 190
 191   /**
 192    * Get's a TextStyle asset previously created at load time
 193    * @pre The Builder has been initialized.
 194    * @param name The name given to a TextStyle in the loaded representation
 195    * @return a Created TextStyle if found, otherwise return a TextStyle created by Default constructor
 196    */
 197   TextStyle GetTextStyle( const std::string &name ) const;
 198
 199   /**
 200    * @deprecated Images as a separate asset is no longer supported
 201    * Get's an Image asset previously created at load time
 202    * An empty handle is returned otherwise.
 203    * @pre The Builder has been initialized.
 204    * @param name The name given to an Image in the loaded representation
 205    * @return A handle to an Image if found, otherwise empty
 206    */
 207   Image GetImage( const std::string &name ) const;
 208
 209   /**
 210    * @deprecated Actors no longer held by builder
 211    * Get's an Actor previously created at load time
 212    * An empty handle is returned otherwise.
 213    * @pre The Builder has been initialized.
 214    * @param name The name given to an Actor in the loaded representation
 215    * @return A handle to an Actor if found, otherwise empty
 216    */
 217   Actor GetActor( const std::string &name ) const;
 218
 219   /**
 220    * @deprecated Animations no longer held by builder
 221    * Get's an Animation previously created at load time
 222    * An empty handle is returned otherwise.
 223    * @pre The Builder has been initialized.
 224    * @param name The name given to an Animation in the loaded representation
 225    * @return A handle to an Animation if found, otherwise empty
 226    */
 227   Animation GetAnimation( const std::string &name ) const;
 228
 229   /**
 230    * Create a render task set.
 231    * @pre The Builder has been initialized.
 232    * @param name The library name of the render task set.
 233    */
 234   void CreateRenderTask( const std::string &name );
 235
 236   /**
 237    * Get or create ShaderEffect from the ShaderEffect instance library.
 238    * An empty handle is returned otherwise.
 239    * @pre The Builder has been initialized.
 240    * @param name The name of a ShaderEffect in the loaded representation
 241    * @return A handle to a ShaderEffect if found, otherwise empty
 242    */
 243   ShaderEffect GetShaderEffect( const std::string &name );
 244
 245   /**
 246    * Get or create FrameBufferImage from the FrameBufferImage instance library.
 247    * An empty handle is returned otherwise.
 248    * @pre The Builder has been initialized.
 249    * @param name The name of a FrameBufferImage in the loaded representation
 250    * @return A handle to a FrameBufferImage if found, otherwise empty
 251    */
 252   FrameBufferImage GetFrameBufferImage( const std::string &name );
 253
 254   /**
 255    * @deprecated. Builder no longer holds actor handles/references
 256    * Provides a list of the top level actors previously created at load time
 257    * @return A container of Actors found at the top level of the loaded representation
 258    */
 259   ActorContainer GetTopLevelActors( void ) const;
 260
 261 private:
 262   Builder(Internal::Builder *impl);
 263
 264 }; // class Builder
 265
 266 } // namespace Toolkit
 267
 268 } // namespace Dali
 269
 270 #endif // __DALI_TOOLKIT_UIBUILDER_H__