1 #ifndef DALI_TOOLKIT_UIBUILDER_H
2 #define DALI_TOOLKIT_UIBUILDER_H
5 * Copyright (c) 2021 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/devel-api/animation/path-constrainer.h>
23 #include <dali/public-api/actors/actor.h>
24 #include <dali/public-api/animation/animation.h>
25 #include <dali/public-api/animation/linear-constrainer.h>
28 #include <dali-toolkit/public-api/dali-toolkit-common.h>
34 namespace Internal DALI_INTERNAL
40 * This class provides the ability to load and style an actor tree from a string representation.
42 * The following is an example in JSON.
47 * "templates": // are named instantiable actor trees
53 * "parentOrigin":[0.5,0.5,0],
57 * "styles": // are named property sets applied to actor trees
61 * "size": [10,10,1] // root properties applied to a given root actor
62 * "actors": // properties applied to actors found by name from root
64 * "ok": // properties for an actor named "ok"
78 * "type":"defaultText",
79 * "text":"Hello World",
87 * The following shows a method to load the json file.
89 * Builder builder = Builder::New();
90 * std::string json_data(ReadFile("layout.json"));
91 * builder.LoadFromString(json_data);
94 * - Load all actors in the "stage" section to the root layer
96 * builder.AddActors( Stage::GetCurrent().GetRootLayer() );
99 * - Create an actor tree from the "templates" section
101 * TextActor actor = TextActor::DownCast( builder.Create( "defaultText" ) );
104 * - Style an actor tree from the "styles" section
106 * builder.ApplyStyle( "myStyle", actor );
109 * - Create an actor tree from json
111 * TextActor actor = TextActor::DownCast( builder.CreateFromJson("{\"type\":\"TextActor\",\"font\":\"\",\"scale\":[50,50,1]}") );
114 * - Apply a style to an actor tree from json
116 * builder.ApplyFromJson( textActor, ("{\"scale\":[5,5,1]}") );
121 class DALI_TOOLKIT_API Builder : public BaseHandle
125 * Create an Builder handle; this can be initialised with Builder::New()
126 * Calling member functions with an uninitialised handle is not allowed.
131 * Creates an Builder object.
132 * @return A handle to the Builder control.
134 static Builder New();
139 * This is non-virtual since derived Handle types must not contain data or virtual methods.
144 * UI string data format
148 JSON, ///< String is JSON
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
160 void LoadFromString(const std::string& data, UIFormat format = JSON);
163 * @brief Adds user defined constants to all future style template or animation expansions
168 * map["IMAGE_DIRECTORY"] = "/usr/share/images";
169 * builder.AddConstants( map );
172 * The following shows a list of constants available by default:
174 * Constant | Description
175 * ----------------------------- | ----------------------------------------------------------------------------------------------------
176 * DALI_IMAGE_DIR | The Image Directory used by Toolkit.
177 * DALI_SOUND_DIR | The Sound Directory used by Toolkit.
178 * DALI_STYLE_DIR | The Style directory that the Toolkit uses.
179 * DALI_STYLE_IMAGE_DIR | The directory that stores all the images used by Toolkit's style.
180 * DALI_SHADER_VERSION_PREFIX | For use in custom shaders to prepend the shader version in use. @ref Shader::GetShaderVersionPrefix
181 * DALI_VERTEX_SHADER_PREFIX | For use in custom vertex shaders to preprocessor prefix used. @ref Shader::GetVertexShaderPrefix
182 * DALI_FRAGMENT_SHADER_PREFIX | For use in custom vertex shaders to preprocessor prefix used. @ref Shader::GetFragmentShaderPrefix()
184 * @pre The Builder has been initialized.
185 * @param map The user defined constants used in template expansions.
187 void AddConstants(const Property::Map& map);
190 * @brief Adds or modifies a user defined constant to all future style template or animation expansions
194 * builder.AddConstant( "IMAGE_DIRECTORY", "/usr/share/images" );
197 * @see AddConstants(const Property::Map&) for builder pre-defined default constants.
199 * @pre The Builder has been initialized.
200 * @param key The constant name to add or update
201 * @param value The new value for the constant.
203 void AddConstant(const std::string& key, const Property::Value& value);
206 * @brief Gets all currently defined configurations.
208 * @pre The Builder has been initialized.
209 * @return A reference to the currently defined configurations.
211 const Property::Map& GetConfigurations() const;
214 * @brief Gets all currently defined constants.
218 * Property::Map map = builder.GetConstants(); // get copy of current constants
219 * map["IMAGE_DIRECTORY"] = "/usr/share/images"; // make modification
220 * builder.AddConstants( map ); // write back changes
223 * @pre The Builder has been initialized.
224 * @return A reference to the currently defined constants.
226 const Property::Map& GetConstants() const;
229 * @brief Gets a currently defined constant, or returns Property::INVALID
233 * Property::Map map = builder.GetConstants(); // get copy of current constants
234 * map["IMAGE_DIRECTORY"] = "/usr/share/images"; // make modification
235 * builder.AddConstants( map ); // write back changes
238 * @pre The Builder has been initialized.
239 * @param key The constant name to search for.
241 const Property::Value& GetConstant(const std::string& key) const;
244 * Creates an animation from the set of known animations
246 * Animation a = builder.CreateAnimation( "wobble");
248 * @pre The Builder has been initialized.
249 * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
250 * @pre The animationName exists in the animations section of the data representation
251 * @param animationName The animation name to create
252 * @returns The base handle of the created object
254 Animation CreateAnimation(const std::string& animationName);
257 * @brief Creates an animation from the set of known animations with user defined constants
261 * map["ACTOR"] = actor.GetProperty< std::string >( Dali::Actor::Property::NAME ); // replaces '{ACTOR} in the template
262 * Animation a = builder.CreateAnimation( "wobble");
264 * @pre The Builder has been initialized.
265 * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
266 * @pre The animationName exists in the animations section of the data representation
267 * @pre The map contains all the constant expansions in the style template
268 * @param animationName The animation name to create
269 * @param map The user defined constants used in style template expansion.
270 * @returns The base handle of the created object
272 Animation CreateAnimation(const std::string& animationName, const Property::Map& map);
275 * @brief Creates an animation from the set of known animations.
277 * The animation is applied to a specific actor.
279 * Actor myInstance = builder.Create( "templateActorTree" )
280 * Animation a = builder.CreateAnimation( "wobble", myInstance );
282 * @pre The Builder has been initialized.
283 * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
284 * @pre The animationName exists in the animations section of the data representation
285 * @param animationName The animation name to create
286 * @param sourceActor The starting point in an actor tree, from which to look for property owners
287 * @returns The base handle of the created object
289 Animation CreateAnimation(const std::string& animationName, Dali::Actor sourceActor);
292 * @brief Creates an animation from the set of known animations with user defined constants
294 * The animation is applied to a specific actor.
297 * map["ACTOR"] = actor.GetProperty< std::string >( Dali::Actor::Property::NAME ); // replaces '{ACTOR} in the template
298 * Actor myInstance = builder.Create( "templateActorTree" )
299 * Animation a = builder.CreateAnimation( "wobble", myInstance);
301 * @pre The Builder has been initialized.
302 * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
303 * @pre The animationName exists in the animations section of the data representation
304 * @pre The map contains all the constant expansions in the style template
305 * @param animationName The animation name to create
306 * @param map The user defined constants used in style template expansion.
307 * @param sourceActor The starting point in an actor tree, from which to look for property owners
308 * @returns The base handle of the created object
310 Animation CreateAnimation(const std::string& animationName, const Property::Map& map, Dali::Actor sourceActor);
313 * @brief Creates an object (e.g. an actor) from the set of known style templates
316 * mActor.Add( Actor::DownCast(builder.Create( "defaultText")) );
318 * @pre The Builder has been initialized.
319 * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
320 * @pre The templateName exists in the templates section of the data representation
321 * and contains 'type' property used to create the object.
322 * @param templateName The template to apply in creation.
323 * @returns The base handle of the created object
325 BaseHandle Create(const std::string& templateName);
328 * @brief Creates an object from the style templates with user defined constants
332 * map["IMAGE_DIR"] = "/usr/share/images"; // replaces '{IMAGE_DIR} in the template
333 * mActor.Add( Actor::DownCast(builder.Create( "defaultImage", map) ) );
335 * @pre The Builder has been initialized.
336 * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
337 * @pre The templateName exists in the templates section of the data representation
338 * and contains 'type' property used to create the object.
339 * @param templateName The template used to create the object.
340 * @param map The user defined constants used in template expansion.
341 * @returns The base handle of the created object
343 BaseHandle Create(const std::string& templateName, const Property::Map& map);
346 * @brief Creates an object (e.g. an actor) from given json snippet
349 * Actor a = Actor::DownCast(builder.CreateFromJson( "{\"type\":\"TextActor\"}"));
351 * @pre The Builder has been initialized.
352 * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
353 * @param json The json snippet used to create the object.
354 * @returns The base handle of the created object if any
356 BaseHandle CreateFromJson(const std::string& json);
359 * Apply a style (a collection of properties) to an actor.
360 * @pre The Builder has been initialized.
361 * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
362 * @param styleName The name of the set of style properties to set on the handle object.
363 * @param handle Then handle of the object on which to set the properties.
365 * @return Return true if the style was found
367 bool ApplyStyle(const std::string& styleName, Handle& handle);
370 * Apply a style (a collection of properties) to an actor from the given json snippet
371 * @pre The Builder has been initialized.
372 * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
373 * @param handle Then handle of the object on which to set the properties.
374 * @param json The json snippet used to create the object.
376 * @return Return true if the json snippet was parsed
378 bool ApplyFromJson(Handle& handle, const std::string& json);
381 * Add the actor tree in the "stage" section to the actor toActor.
382 * ie if the representation has a 'stage' section that contains a tree of
384 * builder.AddActors( Stage::GetCurrent().GetRootLayer() );
385 * will create and add the actors to the stage root layer.
386 * @param toActor The actor to add the created actors to
388 void AddActors(Actor toActor);
391 * Adds actors in the sectionName to the actor toActor.
392 * ie if the representation has a sectionName section that contains a tree of
394 * builder.AddActors( sectionName, Stage::GetCurrent().GetRootLayer() );
395 * will create and add the actors to the stage root layer.
396 * @param sectionName The section name to search for the actor tree
397 * @param toActor The actor to add the created actors to
399 void AddActors(const std::string& sectionName, Actor toActor);
402 * Create a render task set.
403 * @pre The Builder has been initialized.
404 * @param name The library name of the render task set.
406 void CreateRenderTask(const std::string& name);
409 * Get or create Path from the Path instance library.
410 * An empty handle is returned otherwise.
411 * @pre The Builder has been initialized.
412 * @param name The name of a Path in the loaded representation
413 * @return A handle to a Path if found, otherwise empty
415 Path GetPath(const std::string& name);
418 * Get or create a PathConstrainer from the set of known PathConstrainers
420 * PathConstrainer a = builder.GetPathConstrainer( "myPathConstrainer");
422 * @pre The Builder has been initialized.
423 * @pre The pathConstrainerName exists in the Constrainers section of the data representation
424 * @param pathConstrainerName The name of the PathConstrainer
425 * @returns A handle to a PathConstrainer if found, otherwise empty
427 PathConstrainer GetPathConstrainer(const std::string& pathConstrainerName);
430 * Get or create a LinearConstrainer from the set of known LinearConstrainers
432 * LinearConstrainer a = builder.GetLinearConstrainer( "myLinearConstrainer");
434 * @pre The Builder has been initialized.
435 * @pre The linearConstrainerName exists in the Constrainers section of the data representation
436 * @param linearConstrainerName The name of the LinearConstrainer
437 * @returns A handle to a LinearConstrainer if found, otherwise empty
439 LinearConstrainer GetLinearConstrainer(const std::string& linearConstrainerName);
444 * @brief Builder signal type
446 typedef Signal<void()> BuilderSignalType;
449 * @brief Signal emitted when a quit action is requested by the builder.
451 BuilderSignalType& QuitSignal();
454 explicit DALI_INTERNAL Builder(Internal::Builder* impl);
458 } // namespace Toolkit
462 #endif // DALI_TOOLKIT_UIBUILDER_H