Fix for slider
[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 typedef std::map<std::string, Property::Value> PropertyValueMap;
35
36 /**
37  * Builder
38  * This class provides the ability to load an actor tree from a string representation.
39  *
40  * The following example is hello world in JSON.
41  *
42  * @code
43  *
44  *  {
45  *    "styles":
46  *    {
47  *      "default-text":
48  *      {
49  *        "type":"TextActor",
50  *        "font":"",
51  *        "parent-origin":[0.5,0.5,0],
52  *        "scale": [50,50,1]
53  *      }
54  *    },
55  *    "stage":
56  *    [
57  *      {
58  *        "type":"default-text",
59  *        "text":"Hello World",
60  *        "position":[0,0,0]
61  *      },
62  *    ]
63  *  }
64  *
65  *
66  *
67  * @endcode
68  *
69  * The following is how to load the json data.
70  *
71  * @code
72  *
73  * Builder builder = Builder::New();
74  *
75  * std::string json_data(ReadFile("layout.json"));
76  *
77  * builder.LoadFromString(json_data);
78  *
79  * // 1) load all actors in the "stage" section to the root layer
80  * builder.AddActors( Stage::GetCurrent().GetRootLayer() );
81  *
82  * // or 2) create an actor from the library "styles" section
83  * TextActor actor = TextActor::DownCast( builder.CreateFromStyle( "default-text" ) );
84  *
85  * @endcode
86  */
87  class Builder : public BaseHandle
88  {
89  public:
90    /**
91     * Create an Builder handle; this can be initialised with Builder::New()
92     * Calling member functions with an uninitialised handle is not allowed.
93     */
94   Builder();
95
96   /**
97    * Creates an Builder object.
98    * @return A handle to the Builder control.
99    */
100   static Builder New();
101
102   /**
103    * Virtual destructor.
104    */
105   virtual ~Builder();
106
107   /**
108    * UI string data format
109    */
110   enum UIFormat
111   {
112     JSON,                 ///< String is JSON
113   };
114
115   /**
116    * Loads a string representation of an actor tree into memory.
117    * The Actor is not automatically added to the stage.
118    * This function will raise an exception for parse and logical structure errors.
119    * @pre The Builder has been initialized.
120    * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
121    * @param data A string represenation of an Actor tree
122    * @param format The string representation format ie JSON
123    */
124   void LoadFromString( const std::string& data, UIFormat format = JSON );
125
126   /**
127    * @brief Adds user defined constants to all future style template or animation expansions
128    *
129    * e.g.
130    *   PropertyValueMap map;
131    *   map["IMAGE_DIRECTORY"] = "/usr/share/images";
132    *   builder.AddConstants( map );
133    *
134    * @pre The Builder has been initialized.
135    * @param map The user defined constants used in template expansions.
136    */
137   void AddConstants( const PropertyValueMap& map );
138
139   /**
140    * @brief Adds or modifies a user defined constant to all future style template or animation expansions
141    *
142    * e.g.
143    *  builder.AddConstant( "IMAGE_DIRECTORY", "/usr/share/images" );
144    *
145    * @pre The Builder has been initialized.
146    * @param key The constant name to add or update
147    * @param value The new value for the constant.
148    */
149   void AddConstant( const std::string& key, const Property::Value& value );
150
151   /**
152    * @brief Gets all currently defined constants.
153    *
154    * e.g.
155    *  PropertyValueMap map = builder.GetConstants(); // get copy of current constants
156    *  map["IMAGE_DIRECTORY"] = "/usr/share/images";  // make modification
157    *  builder.AddConstants( map );                   // write back changes
158    *
159    * @pre The Builder has been initialized.
160    * @return A reference to the currently defined constants.
161    */
162   const PropertyValueMap& GetConstants() const;
163
164   /**
165    * @brief Gets a currently defined constant, or returns Property::INVALID
166    *
167    * e.g.
168    *  PropertyValueMap map = builder.GetConstants(); // get copy of current constants
169    *  map["IMAGE_DIRECTORY"] = "/usr/share/images";  // make modification
170    *  builder.AddConstants( map );                   // write back changes
171    *
172    * @pre The Builder has been initialized.
173    * @param key The constant name to search for.
174    */
175   const Property::Value& GetConstant( const std::string& key ) const;
176
177   /**
178    * Creates an animation from the set of known animations
179    * e.g.
180    *   Animation a = builder.CreateAnimation( "wobble");
181    *
182    * @pre The Builder has been initialized.
183    * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
184    * @pre The animationName exists in the animations section of the data representation
185    * @param animationName The animation name to create
186    * @returns The base handle of the created object
187    */
188   Animation CreateAnimation( const std::string& animationName );
189
190   /**
191    * @brief Creates an animation from the set of known animations with user defined constants
192    *
193    * e.g.
194    *   PropertyValueMap map;
195    *   map["ACTOR"] = actor.GetName();       // replaces '{ACTOR} in the template
196    *   Animation a = builder.CreateAnimation( "wobble");
197    *
198    * @pre The Builder has been initialized.
199    * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
200    * @pre The animationName exists in the animations section of the data representation
201    * @pre The map contains all the constant expansions in the style template
202    * @param animationName The animation name to create
203    * @param map The user defined constants used in style template expansion.
204    * @returns The base handle of the created object
205    */
206   Animation CreateAnimation( const std::string& animationName, const PropertyValueMap& map );
207
208   /**
209    * @brief Creates an animation from the set of known animations.
210    *
211    * The animation is applied to a specific actor.
212    * e.g.
213    *   Actor myInstance = builder.CreateFromStyle( "template-actor-tree" )
214    *   Animation a = builder.CreateAnimation( "wobble", myInstance );
215    *
216    * @pre The Builder has been initialized.
217    * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
218    * @pre The animationName exists in the animations section of the data representation
219    * @param animationName The animation name to create
220    * @param sourceActor The starting point in an actor tree, from which to look for property owners
221    * @returns The base handle of the created object
222    */
223   Animation CreateAnimation( const std::string& animationName, Dali::Actor sourceActor );
224
225   /**
226    * @brief Creates an animation from the set of known animations with user defined constants
227    *
228    * The animation is applied to a specific actor.
229    * e.g.
230    *   PropertyValueMap map;
231    *   map["ACTOR"] = actor.GetName();       // replaces '{ACTOR} in the template
232    *   Actor myInstance = builder.CreateFromStyle( "template-actor-tree" )
233    *   Animation a = builder.CreateAnimation( "wobble", myInstance);
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    * @pre The map contains all the constant expansions in the style template
239    * @param animationName The animation name to create
240    * @param map The user defined constants used in style template expansion.
241    * @param sourceActor The starting point in an actor tree, from which to look for property owners
242    * @returns The base handle of the created object
243    */
244   Animation CreateAnimation( const std::string& animationName, const PropertyValueMap& map, Dali::Actor sourceActor );
245
246   /**
247    * @brief Creates an object (e.g. an actor) from the set of known style templates
248    *
249    * e.g.
250    *   mActor.Add( Actor::DownCast(builder.CreateFromStyle( "default-text")) );
251    *
252    * @pre The Builder has been initialized.
253    * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
254    * @pre The styleName has been loaded from the styles section of the data representation
255    *      and contains 'type' property used to create the object.
256    * @param styleName The set of styles/properties to set on the handle object.
257    * @returns The base handle of the created object
258    */
259   BaseHandle CreateFromStyle( const std::string& styleName );
260
261   /**
262    * @brief Creates an object from the style templates with user defined constants
263    *
264    * e.g.
265    *   PropertyValueMap map;
266    *   map["IMAGE_DIR"] = "/usr/share/images"; // replaces '{IMAGE_DIR} in the template
267    *   mActor.Add( Actor::DownCast(builder.CreateFromStyle( "default-image", map) ) );
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 styleName has been loaded from the styles section of the data representation
272    *      and contains 'type' property used to create the object.
273    * @pre The map contains all the constant expansions in the style template
274    * @param styleName The set of styles/properties to set on the handle object.
275    * @param map The user defined constants used in style template expansion.
276    * @returns The base handle of the created object
277    */
278   BaseHandle CreateFromStyle( const std::string& styleName, const PropertyValueMap& map );
279
280   /**
281    * Apply a style (a collection of properties) to an actor.
282    * @pre The Builder has been initialized.
283    * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
284    * @param styleName The name of the set of style properties to set on the handle object.
285    * @param handle Then handle of the object on which to set the properties.
286    */
287   void ApplyStyle( const std::string& styleName, Handle& handle );
288
289   /**
290    * Add the actor tree in the "stage" section to the actor toActor.
291    * ie if the representation has a 'stage' section that contains a tree of
292    * actors then
293    *    builder.AddActors( Stage::GetCurrent().GetRootLayer() );
294    * will create and add the actors to the stage root layer.
295    * @param toActor The actor to add the created actors to
296    */
297   void AddActors( Actor toActor );
298
299   /**
300    * Adds actors in the sectionName to the actor toActor.
301    * ie if the representation has a sectionName section that contains a tree of
302    * actors then
303    *    builder.AddActors( sectionName, Stage::GetCurrent().GetRootLayer() );
304    * will create and add the actors to the stage root layer.
305    * @param sectionName The section name to search for the actor tree
306    * @param toActor The actor to add the created actors to
307    */
308   void AddActors( const std::string &sectionName, Actor toActor );
309
310   /**
311    * @deprecated Font as a separate asset is no longer supported
312    * Get's a Font asset previously created at load time
313    * An empty handle is returned otherwise.
314    * @pre The Builder has been initialized.
315    * @param name The name given to a Font in the loaded representation
316    * @return A handle to a Font if found, otherwise empty.
317    */
318   Font GetFont( const std::string &name ) const;
319
320   /**
321    * Get's a TextStyle asset previously created at load time
322    * @pre The Builder has been initialized.
323    * @param name The name given to a TextStyle in the loaded representation
324    * @return a Created TextStyle if found, otherwise return a TextStyle created by Default constructor
325    */
326   TextStyle GetTextStyle( const std::string &name ) const;
327
328   /**
329    * @deprecated Images as a separate asset is no longer supported
330    * Get's an Image asset previously created at load time
331    * An empty handle is returned otherwise.
332    * @pre The Builder has been initialized.
333    * @param name The name given to an Image in the loaded representation
334    * @return A handle to an Image if found, otherwise empty
335    */
336   Image GetImage( const std::string &name ) const;
337
338   /**
339    * @deprecated Actors no longer held by builder
340    * Get's an Actor previously created at load time
341    * An empty handle is returned otherwise.
342    * @pre The Builder has been initialized.
343    * @param name The name given to an Actor in the loaded representation
344    * @return A handle to an Actor if found, otherwise empty
345    */
346   Actor GetActor( const std::string &name ) const;
347
348   /**
349    * @deprecated Animations no longer held by builder
350    * Get's an Animation previously created at load time
351    * An empty handle is returned otherwise.
352    * @pre The Builder has been initialized.
353    * @param name The name given to an Animation in the loaded representation
354    * @return A handle to an Animation if found, otherwise empty
355    */
356   Animation GetAnimation( const std::string &name ) const;
357
358   /**
359    * Create a render task set.
360    * @pre The Builder has been initialized.
361    * @param name The library name of the render task set.
362    */
363   void CreateRenderTask( const std::string &name );
364
365   /**
366    * Get or create ShaderEffect from the ShaderEffect instance library.
367    * An empty handle is returned otherwise.
368    * @pre The Builder has been initialized.
369    * @param name The name of a ShaderEffect in the loaded representation
370    * @return A handle to a ShaderEffect if found, otherwise empty
371    */
372   ShaderEffect GetShaderEffect( const std::string &name );
373
374   /**
375    * Get or create FrameBufferImage from the FrameBufferImage instance library.
376    * An empty handle is returned otherwise.
377    * @pre The Builder has been initialized.
378    * @param name The name of a FrameBufferImage in the loaded representation
379    * @return A handle to a FrameBufferImage if found, otherwise empty
380    */
381   FrameBufferImage GetFrameBufferImage( const std::string &name );
382
383   /**
384    * @deprecated. Builder no longer holds actor handles/references
385    * Provides a list of the top level actors previously created at load time
386    * @return A container of Actors found at the top level of the loaded representation
387    */
388   ActorContainer GetTopLevelActors( void ) const;
389
390 private:
391   Builder(Internal::Builder *impl);
392
393 }; // class Builder
394
395 } // namespace Toolkit
396
397 } // namespace Dali
398
399 #endif // __DALI_TOOLKIT_UIBUILDER_H__