Remove/Move experimental features
[platform/core/uifw/dali-toolkit.git] / dali-toolkit / devel-api / builder / builder.h
1 #ifndef __DALI_TOOLKIT_UIBUILDER_H__
2 #define __DALI_TOOLKIT_UIBUILDER_H__
3
4 /*
5  * Copyright (c) 2016 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 namespace Dali
29 {
30
31 namespace Toolkit
32 {
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_IMPORT_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    *   Property::Map map;
167    *   map["IMAGE_DIRECTORY"] = "/usr/share/images";
168    *   builder.AddConstants( map );
169    *
170    * @pre The Builder has been initialized.
171    * @param map The user defined constants used in template expansions.
172    */
173   void AddConstants( const Property::Map& map );
174
175   /**
176    * @brief Adds or modifies a user defined constant to all future style template or animation expansions
177    *
178    * e.g.
179    * @code
180    * builder.AddConstant( "IMAGE_DIRECTORY", "/usr/share/images" );
181    * @endcode
182    *
183    * @pre The Builder has been initialized.
184    * @param key The constant name to add or update
185    * @param value The new value for the constant.
186    */
187   void AddConstant( const std::string& key, const Property::Value& value );
188
189   /**
190    * @brief Gets all currently defined constants.
191    *
192    * e.g.
193    * @code
194    * Property::Map map = builder.GetConstants(); // get copy of current constants
195    * map["IMAGE_DIRECTORY"] = "/usr/share/images";  // make modification
196    * builder.AddConstants( map );                   // write back changes
197    * @endcode
198    *
199    * @pre The Builder has been initialized.
200    * @return A reference to the currently defined constants.
201    */
202   const Property::Map& GetConstants() const;
203
204   /**
205    * @brief Gets a currently defined constant, or returns Property::INVALID
206    *
207    * e.g.
208    * @code
209    * Property::Map map = builder.GetConstants(); // get copy of current constants
210    * map["IMAGE_DIRECTORY"] = "/usr/share/images";  // make modification
211    * builder.AddConstants( map );                   // write back changes
212    * @endcode
213    *
214    * @pre The Builder has been initialized.
215    * @param key The constant name to search for.
216    */
217   const Property::Value& GetConstant( const std::string& key ) const;
218
219   /**
220    * Creates an animation from the set of known animations
221    * e.g.
222    *   Animation a = builder.CreateAnimation( "wobble");
223    *
224    * @pre The Builder has been initialized.
225    * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
226    * @pre The animationName exists in the animations section of the data representation
227    * @param animationName The animation name to create
228    * @returns The base handle of the created object
229    */
230   Animation CreateAnimation( const std::string& animationName );
231
232   /**
233    * @brief Creates an animation from the set of known animations with user defined constants
234    *
235    * e.g.
236    *   Property::Map map;
237    *   map["ACTOR"] = actor.GetName();       // replaces '{ACTOR} in the template
238    *   Animation a = builder.CreateAnimation( "wobble");
239    *
240    * @pre The Builder has been initialized.
241    * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
242    * @pre The animationName exists in the animations section of the data representation
243    * @pre The map contains all the constant expansions in the style template
244    * @param animationName The animation name to create
245    * @param map The user defined constants used in style template expansion.
246    * @returns The base handle of the created object
247    */
248   Animation CreateAnimation( const std::string& animationName, const Property::Map& map );
249
250   /**
251    * @brief Creates an animation from the set of known animations.
252    *
253    * The animation is applied to a specific actor.
254    * e.g.
255    *   Actor myInstance = builder.Create( "templateActorTree" )
256    *   Animation a = builder.CreateAnimation( "wobble", myInstance );
257    *
258    * @pre The Builder has been initialized.
259    * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
260    * @pre The animationName exists in the animations section of the data representation
261    * @param animationName The animation name to create
262    * @param sourceActor The starting point in an actor tree, from which to look for property owners
263    * @returns The base handle of the created object
264    */
265   Animation CreateAnimation( const std::string& animationName, Dali::Actor sourceActor );
266
267   /**
268    * @brief Creates an animation from the set of known animations with user defined constants
269    *
270    * The animation is applied to a specific actor.
271    * e.g.
272    *   Property::Map map;
273    *   map["ACTOR"] = actor.GetName();       // replaces '{ACTOR} in the template
274    *   Actor myInstance = builder.Create( "templateActorTree" )
275    *   Animation a = builder.CreateAnimation( "wobble", myInstance);
276    *
277    * @pre The Builder has been initialized.
278    * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
279    * @pre The animationName exists in the animations section of the data representation
280    * @pre The map contains all the constant expansions in the style template
281    * @param animationName The animation name to create
282    * @param map The user defined constants used in style template expansion.
283    * @param sourceActor The starting point in an actor tree, from which to look for property owners
284    * @returns The base handle of the created object
285    */
286   Animation CreateAnimation( const std::string& animationName, const Property::Map& map, Dali::Actor sourceActor );
287
288   /**
289    * @brief Creates an object (e.g. an actor) from the set of known style templates
290    *
291    * e.g.
292    *   mActor.Add( Actor::DownCast(builder.Create( "defaultText")) );
293    *
294    * @pre The Builder has been initialized.
295    * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
296    * @pre The templateName exists in the templates section of the data representation
297    *      and contains 'type' property used to create the object.
298    * @param templateName The template to apply in creation.
299    * @returns The base handle of the created object
300    */
301   BaseHandle Create( const std::string& templateName );
302
303   /**
304    * @brief Creates an object from the style templates with user defined constants
305    *
306    * e.g.
307    *   Property::Map map;
308    *   map["IMAGE_DIR"] = "/usr/share/images"; // replaces '{IMAGE_DIR} in the template
309    *   mActor.Add( Actor::DownCast(builder.Create( "defaultImage",  map) ) );
310    *
311    * @pre The Builder has been initialized.
312    * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
313    * @pre The templateName exists in the templates section of the data representation
314    *      and contains 'type' property used to create the object.
315    * @param templateName The template used to create the object.
316    * @param map The user defined constants used in template expansion.
317    * @returns The base handle of the created object
318    */
319   BaseHandle Create( const std::string& templateName, const Property::Map& map );
320
321   /**
322    * @brief Creates an object (e.g. an actor) from given json snippet
323    *
324    * e.g.
325    *   Actor a = Actor::DownCast(builder.CreateFromJson( "{\"type\":\"TextActor\"}"));
326    *
327    * @pre The Builder has been initialized.
328    * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
329    * @param json The json snippet used to create the object.
330    * @returns The base handle of the created object if any
331    */
332   BaseHandle CreateFromJson( const std::string& json );
333
334   /**
335    * Apply a style (a collection of properties) to an actor.
336    * @pre The Builder has been initialized.
337    * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
338    * @param styleName The name of the set of style properties to set on the handle object.
339    * @param handle Then handle of the object on which to set the properties.
340    *
341    * @return Return true if the style was found
342    */
343   bool ApplyStyle( const std::string& styleName, Handle& handle );
344
345   /**
346    * Apply a style (a collection of properties) to an actor from the given json snippet
347    * @pre The Builder has been initialized.
348    * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
349    * @param handle Then handle of the object on which to set the properties.
350    * @param json The json snippet used to create the object.
351    *
352    * @return Return true if the json snippet was parsed
353    */
354   bool ApplyFromJson(  Handle& handle, const std::string& json );
355
356
357   /**
358    * Add the actor tree in the "stage" section to the actor toActor.
359    * ie if the representation has a 'stage' section that contains a tree of
360    * actors then
361    *    builder.AddActors( Stage::GetCurrent().GetRootLayer() );
362    * will create and add the actors to the stage root layer.
363    * @param toActor The actor to add the created actors to
364    */
365   void AddActors( Actor toActor );
366
367   /**
368    * Adds actors in the sectionName to the actor toActor.
369    * ie if the representation has a sectionName section that contains a tree of
370    * actors then
371    *    builder.AddActors( sectionName, Stage::GetCurrent().GetRootLayer() );
372    * will create and add the actors to the stage root layer.
373    * @param sectionName The section name to search for the actor tree
374    * @param toActor The actor to add the created actors to
375    */
376   void AddActors( const std::string &sectionName, Actor toActor );
377
378   /**
379    * Create a render task set.
380    * @pre The Builder has been initialized.
381    * @param name The library name of the render task set.
382    */
383   void CreateRenderTask( const std::string &name );
384
385   /**
386    * Get or create FrameBufferImage from the FrameBufferImage instance library.
387    * An empty handle is returned otherwise.
388    * @pre The Builder has been initialized.
389    * @param name The name of a FrameBufferImage in the loaded representation
390    * @return A handle to a FrameBufferImage if found, otherwise empty
391    */
392   FrameBufferImage GetFrameBufferImage( const std::string &name );
393
394   /**
395    * Get or create Path from the Path instance library.
396    * An empty handle is returned otherwise.
397    * @pre The Builder has been initialized.
398    * @param name The name of a Path in the loaded representation
399    * @return A handle to a Path if found, otherwise empty
400    */
401   Path GetPath( const std::string &name );
402
403   /**
404    * Get or create a PathConstrainer from the set of known PathConstrainers
405    * e.g.
406    *   PathConstrainer a = builder.GetPathConstrainer( "myPathConstrainer");
407    *
408    * @pre The Builder has been initialized.
409    * @pre The pathConstrainerName exists in the Constrainers section of the data representation
410    * @param pathConstrainerName The name of the PathConstrainer
411    * @returns A handle to a PathConstrainer if found, otherwise empty
412    */
413   PathConstrainer GetPathConstrainer( const std::string& pathConstrainerName );
414
415   /**
416    * Get or create a LinearConstrainer from the set of known LinearConstrainers
417    * e.g.
418    *   LinearConstrainer a = builder.GetLinearConstrainer( "myLinearConstrainer");
419    *
420    * @pre The Builder has been initialized.
421    * @pre The linearConstrainerName exists in the Constrainers section of the data representation
422    * @param linearConstrainerName The name of the LinearConstrainer
423    * @returns A handle to a LinearConstrainer if found, otherwise empty
424    */
425   LinearConstrainer GetLinearConstrainer( const std::string& linearConstrainerName );
426
427   // Signals
428
429   /**
430    * @brief Builder signal type
431    */
432   typedef Signal< void () > BuilderSignalType;
433
434   /**
435    * @brief Signal emitted when a quit action is requested by the builder.
436    */
437   BuilderSignalType& QuitSignal();
438
439 private:
440   explicit DALI_INTERNAL Builder(Internal::Builder *impl);
441
442 }; // class Builder
443
444 } // namespace Toolkit
445
446 } // namespace Dali
447
448 #endif // __DALI_TOOLKIT_UIBUILDER_H__