1 #ifndef __DALI_TOOLKIT_UIBUILDER_H__
2 #define __DALI_TOOLKIT_UIBUILDER_H__
5 * Copyright (c) 2018 Samsung Electronics Co., Ltd.
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
11 * http://www.apache.org/licenses/LICENSE-2.0
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.
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>
29 #include <dali-toolkit/public-api/dali-toolkit-common.h>
37 namespace Internal DALI_INTERNAL
43 * This class provides the ability to load and style an actor tree from a string representation.
45 * The following is an example in JSON.
50 * "templates": // are named instantiable actor trees
56 * "parentOrigin":[0.5,0.5,0],
60 * "styles": // are named property sets applied to actor trees
64 * "size": [10,10,1] // root properties applied to a given root actor
65 * "actors": // properties applied to actors found by name from root
67 * "ok": // properties for an actor named "ok"
81 * "type":"defaultText",
82 * "text":"Hello World",
90 * The following shows a method to load the json file.
92 * Builder builder = Builder::New();
93 * std::string json_data(ReadFile("layout.json"));
94 * builder.LoadFromString(json_data);
97 * - Load all actors in the "stage" section to the root layer
99 * builder.AddActors( Stage::GetCurrent().GetRootLayer() );
102 * - Create an actor tree from the "templates" section
104 * TextActor actor = TextActor::DownCast( builder.Create( "defaultText" ) );
107 * - Style an actor tree from the "styles" section
109 * builder.ApplyStyle( "myStyle", actor );
112 * - Create an actor tree from json
114 * TextActor actor = TextActor::DownCast( builder.CreateFromJson("{\"type\":\"TextActor\",\"font\":\"\",\"scale\":[50,50,1]}") );
117 * - Apply a style to an actor tree from json
119 * builder.ApplyFromJson( textActor, ("{\"scale\":[5,5,1]}") );
124 class DALI_TOOLKIT_API Builder : public BaseHandle
128 * Create an Builder handle; this can be initialised with Builder::New()
129 * Calling member functions with an uninitialised handle is not allowed.
134 * Creates an Builder object.
135 * @return A handle to the Builder control.
137 static Builder New();
142 * This is non-virtual since derived Handle types must not contain data or virtual methods.
147 * UI string data format
151 JSON, ///< String is JSON
155 * Loads a string representation of an actor tree into memory.
156 * The Actor is not automatically added to the stage.
157 * This function will raise an exception for parse and logical structure errors.
158 * @pre The Builder has been initialized.
159 * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
160 * @param data A string represenation of an Actor tree
161 * @param format The string representation format ie JSON
163 void LoadFromString( const std::string& data, UIFormat format = JSON );
166 * @brief Adds user defined constants to all future style template or animation expansions
170 * map["IMAGE_DIRECTORY"] = "/usr/share/images";
171 * builder.AddConstants( map );
173 * @pre The Builder has been initialized.
174 * @param map The user defined constants used in template expansions.
176 void AddConstants( const Property::Map& map );
179 * @brief Adds or modifies a user defined constant to all future style template or animation expansions
183 * builder.AddConstant( "IMAGE_DIRECTORY", "/usr/share/images" );
186 * @pre The Builder has been initialized.
187 * @param key The constant name to add or update
188 * @param value The new value for the constant.
190 void AddConstant( const std::string& key, const Property::Value& value );
193 * @brief Gets all currently defined configurations.
195 * @pre The Builder has been initialized.
196 * @return A reference to the currently defined configurations.
198 const Property::Map& GetConfigurations() const;
201 * @brief Gets all currently defined constants.
205 * Property::Map map = builder.GetConstants(); // get copy of current constants
206 * map["IMAGE_DIRECTORY"] = "/usr/share/images"; // make modification
207 * builder.AddConstants( map ); // write back changes
210 * @pre The Builder has been initialized.
211 * @return A reference to the currently defined constants.
213 const Property::Map& GetConstants() const;
216 * @brief Gets a currently defined constant, or returns Property::INVALID
220 * Property::Map map = builder.GetConstants(); // get copy of current constants
221 * map["IMAGE_DIRECTORY"] = "/usr/share/images"; // make modification
222 * builder.AddConstants( map ); // write back changes
225 * @pre The Builder has been initialized.
226 * @param key The constant name to search for.
228 const Property::Value& GetConstant( const std::string& key ) const;
231 * Creates an animation from the set of known animations
233 * Animation a = builder.CreateAnimation( "wobble");
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 * @param animationName The animation name to create
239 * @returns The base handle of the created object
241 Animation CreateAnimation( const std::string& animationName );
244 * @brief Creates an animation from the set of known animations with user defined constants
248 * map["ACTOR"] = actor.GetName(); // replaces '{ACTOR} in the template
249 * Animation a = builder.CreateAnimation( "wobble");
251 * @pre The Builder has been initialized.
252 * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
253 * @pre The animationName exists in the animations section of the data representation
254 * @pre The map contains all the constant expansions in the style template
255 * @param animationName The animation name to create
256 * @param map The user defined constants used in style template expansion.
257 * @returns The base handle of the created object
259 Animation CreateAnimation( const std::string& animationName, const Property::Map& map );
262 * @brief Creates an animation from the set of known animations.
264 * The animation is applied to a specific actor.
266 * Actor myInstance = builder.Create( "templateActorTree" )
267 * Animation a = builder.CreateAnimation( "wobble", myInstance );
269 * @pre The Builder has been initialized.
270 * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
271 * @pre The animationName exists in the animations section of the data representation
272 * @param animationName The animation name to create
273 * @param sourceActor The starting point in an actor tree, from which to look for property owners
274 * @returns The base handle of the created object
276 Animation CreateAnimation( const std::string& animationName, Dali::Actor sourceActor );
279 * @brief Creates an animation from the set of known animations with user defined constants
281 * The animation is applied to a specific actor.
284 * map["ACTOR"] = actor.GetName(); // replaces '{ACTOR} in the template
285 * Actor myInstance = builder.Create( "templateActorTree" )
286 * Animation a = builder.CreateAnimation( "wobble", myInstance);
288 * @pre The Builder has been initialized.
289 * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
290 * @pre The animationName exists in the animations section of the data representation
291 * @pre The map contains all the constant expansions in the style template
292 * @param animationName The animation name to create
293 * @param map The user defined constants used in style template expansion.
294 * @param sourceActor The starting point in an actor tree, from which to look for property owners
295 * @returns The base handle of the created object
297 Animation CreateAnimation( const std::string& animationName, const Property::Map& map, Dali::Actor sourceActor );
300 * @brief Creates an object (e.g. an actor) from the set of known style templates
303 * mActor.Add( Actor::DownCast(builder.Create( "defaultText")) );
305 * @pre The Builder has been initialized.
306 * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
307 * @pre The templateName exists in the templates section of the data representation
308 * and contains 'type' property used to create the object.
309 * @param templateName The template to apply in creation.
310 * @returns The base handle of the created object
312 BaseHandle Create( const std::string& templateName );
315 * @brief Creates an object from the style templates with user defined constants
319 * map["IMAGE_DIR"] = "/usr/share/images"; // replaces '{IMAGE_DIR} in the template
320 * mActor.Add( Actor::DownCast(builder.Create( "defaultImage", map) ) );
322 * @pre The Builder has been initialized.
323 * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
324 * @pre The templateName exists in the templates section of the data representation
325 * and contains 'type' property used to create the object.
326 * @param templateName The template used to create the object.
327 * @param map The user defined constants used in template expansion.
328 * @returns The base handle of the created object
330 BaseHandle Create( const std::string& templateName, const Property::Map& map );
333 * @brief Creates an object (e.g. an actor) from given json snippet
336 * Actor a = Actor::DownCast(builder.CreateFromJson( "{\"type\":\"TextActor\"}"));
338 * @pre The Builder has been initialized.
339 * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
340 * @param json The json snippet used to create the object.
341 * @returns The base handle of the created object if any
343 BaseHandle CreateFromJson( const std::string& json );
346 * Apply a style (a collection of properties) to an actor.
347 * @pre The Builder has been initialized.
348 * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
349 * @param styleName The name of the set of style properties to set on the handle object.
350 * @param handle Then handle of the object on which to set the properties.
352 * @return Return true if the style was found
354 bool ApplyStyle( const std::string& styleName, Handle& handle );
357 * Apply a style (a collection of properties) to an actor from the given json snippet
358 * @pre The Builder has been initialized.
359 * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
360 * @param handle Then handle of the object on which to set the properties.
361 * @param json The json snippet used to create the object.
363 * @return Return true if the json snippet was parsed
365 bool ApplyFromJson( Handle& handle, const std::string& json );
369 * Add the actor tree in the "stage" section to the actor toActor.
370 * ie if the representation has a 'stage' section that contains a tree of
372 * builder.AddActors( Stage::GetCurrent().GetRootLayer() );
373 * will create and add the actors to the stage root layer.
374 * @param toActor The actor to add the created actors to
376 void AddActors( Actor toActor );
379 * Adds actors in the sectionName to the actor toActor.
380 * ie if the representation has a sectionName section that contains a tree of
382 * builder.AddActors( sectionName, Stage::GetCurrent().GetRootLayer() );
383 * will create and add the actors to the stage root layer.
384 * @param sectionName The section name to search for the actor tree
385 * @param toActor The actor to add the created actors to
387 void AddActors( const std::string §ionName, Actor toActor );
390 * Create a render task set.
391 * @pre The Builder has been initialized.
392 * @param name The library name of the render task set.
394 void CreateRenderTask( const std::string &name );
397 * Get or create FrameBufferImage from the FrameBufferImage instance library.
398 * An empty handle is returned otherwise.
399 * @pre The Builder has been initialized.
400 * @param name The name of a FrameBufferImage in the loaded representation
401 * @return A handle to a FrameBufferImage if found, otherwise empty
403 FrameBufferImage GetFrameBufferImage( const std::string &name );
406 * Get or create Path from the Path instance library.
407 * An empty handle is returned otherwise.
408 * @pre The Builder has been initialized.
409 * @param name The name of a Path in the loaded representation
410 * @return A handle to a Path if found, otherwise empty
412 Path GetPath( const std::string &name );
415 * Get or create a PathConstrainer from the set of known PathConstrainers
417 * PathConstrainer a = builder.GetPathConstrainer( "myPathConstrainer");
419 * @pre The Builder has been initialized.
420 * @pre The pathConstrainerName exists in the Constrainers section of the data representation
421 * @param pathConstrainerName The name of the PathConstrainer
422 * @returns A handle to a PathConstrainer if found, otherwise empty
424 PathConstrainer GetPathConstrainer( const std::string& pathConstrainerName );
427 * Get or create a LinearConstrainer from the set of known LinearConstrainers
429 * LinearConstrainer a = builder.GetLinearConstrainer( "myLinearConstrainer");
431 * @pre The Builder has been initialized.
432 * @pre The linearConstrainerName exists in the Constrainers section of the data representation
433 * @param linearConstrainerName The name of the LinearConstrainer
434 * @returns A handle to a LinearConstrainer if found, otherwise empty
436 LinearConstrainer GetLinearConstrainer( const std::string& linearConstrainerName );
441 * @brief Builder signal type
443 typedef Signal< void () > BuilderSignalType;
446 * @brief Signal emitted when a quit action is requested by the builder.
448 BuilderSignalType& QuitSignal();
451 explicit DALI_INTERNAL Builder(Internal::Builder *impl);
455 } // namespace Toolkit
459 #endif // __DALI_TOOLKIT_UIBUILDER_H__