Shortcut check for markup in a string, before attempting to parse and split the strin...
[platform/core/uifw/dali-toolkit.git] / 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__