1 #ifndef __DALI_TOOLKIT_UIBUILDER_H__
2 #define __DALI_TOOLKIT_UIBUILDER_H__
5 // Copyright (c) 2014 Samsung Electronics Co., Ltd.
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
11 // http://floralicense.org/license/
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.
21 #include <dali/dali.h>
23 namespace Dali DALI_IMPORT_API
29 namespace Internal DALI_INTERNAL
34 typedef std::map<std::string, Property::Value> PropertyValueMap;
38 * This class provides the ability to load an actor tree from a string representation.
40 * The following example is hello world in JSON.
51 * "parent-origin":[0.5,0.5,0],
58 * "type":"default-text",
59 * "text":"Hello World",
69 * The following is how to load the json data.
73 * Builder builder = Builder::New();
75 * std::string json_data(ReadFile("layout.json"));
77 * builder.LoadFromString(json_data);
79 * // 1) load all actors in the "stage" section to the root layer
80 * builder.AddActors( Stage::GetCurrent().GetRootLayer() );
82 * // or 2) create an actor from the library "templates" section
83 * TextActor actor = TextActor::DownCast( builder.Create( "default-text" ) );
87 class Builder : public BaseHandle
91 * Create an Builder handle; this can be initialised with Builder::New()
92 * Calling member functions with an uninitialised handle is not allowed.
97 * Creates an Builder object.
98 * @return A handle to the Builder control.
100 static Builder New();
103 * Virtual destructor.
108 * UI string data format
112 JSON, ///< String is JSON
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
124 void LoadFromString( const std::string& data, UIFormat format = JSON );
127 * @brief Adds user defined constants to all future style template or animation expansions
130 * PropertyValueMap map;
131 * map["IMAGE_DIRECTORY"] = "/usr/share/images";
132 * builder.AddConstants( map );
134 * @pre The Builder has been initialized.
135 * @param map The user defined constants used in template expansions.
137 void AddConstants( const PropertyValueMap& map );
140 * @brief Adds or modifies a user defined constant to all future style template or animation expansions
144 * builder.AddConstant( "IMAGE_DIRECTORY", "/usr/share/images" );
147 * @pre The Builder has been initialized.
148 * @param key The constant name to add or update
149 * @param value The new value for the constant.
151 void AddConstant( const std::string& key, const Property::Value& value );
154 * @brief Gets all currently defined constants.
158 * PropertyValueMap map = builder.GetConstants(); // get copy of current constants
159 * map["IMAGE_DIRECTORY"] = "/usr/share/images"; // make modification
160 * builder.AddConstants( map ); // write back changes
163 * @pre The Builder has been initialized.
164 * @return A reference to the currently defined constants.
166 const PropertyValueMap& GetConstants() const;
169 * @brief Gets a currently defined constant, or returns Property::INVALID
173 * PropertyValueMap map = builder.GetConstants(); // get copy of current constants
174 * map["IMAGE_DIRECTORY"] = "/usr/share/images"; // make modification
175 * builder.AddConstants( map ); // write back changes
178 * @pre The Builder has been initialized.
179 * @param key The constant name to search for.
181 const Property::Value& GetConstant( const std::string& key ) const;
184 * Creates an animation from the set of known animations
186 * Animation a = builder.CreateAnimation( "wobble");
188 * @pre The Builder has been initialized.
189 * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
190 * @pre The animationName exists in the animations section of the data representation
191 * @param animationName The animation name to create
192 * @returns The base handle of the created object
194 Animation CreateAnimation( const std::string& animationName );
197 * @brief Creates an animation from the set of known animations with user defined constants
200 * PropertyValueMap map;
201 * map["ACTOR"] = actor.GetName(); // replaces '{ACTOR} in the template
202 * Animation a = builder.CreateAnimation( "wobble");
204 * @pre The Builder has been initialized.
205 * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
206 * @pre The animationName exists in the animations section of the data representation
207 * @pre The map contains all the constant expansions in the style template
208 * @param animationName The animation name to create
209 * @param map The user defined constants used in style template expansion.
210 * @returns The base handle of the created object
212 Animation CreateAnimation( const std::string& animationName, const PropertyValueMap& map );
215 * @brief Creates an animation from the set of known animations.
217 * The animation is applied to a specific actor.
219 * Actor myInstance = builder.Create( "template-actor-tree" )
220 * Animation a = builder.CreateAnimation( "wobble", myInstance );
222 * @pre The Builder has been initialized.
223 * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
224 * @pre The animationName exists in the animations section of the data representation
225 * @param animationName The animation name to create
226 * @param sourceActor The starting point in an actor tree, from which to look for property owners
227 * @returns The base handle of the created object
229 Animation CreateAnimation( const std::string& animationName, Dali::Actor sourceActor );
232 * @brief Creates an animation from the set of known animations with user defined constants
234 * The animation is applied to a specific actor.
236 * PropertyValueMap map;
237 * map["ACTOR"] = actor.GetName(); // replaces '{ACTOR} in the template
238 * Actor myInstance = builder.Create( "template-actor-tree" )
239 * Animation a = builder.CreateAnimation( "wobble", myInstance);
241 * @pre The Builder has been initialized.
242 * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
243 * @pre The animationName exists in the animations section of the data representation
244 * @pre The map contains all the constant expansions in the style template
245 * @param animationName The animation name to create
246 * @param map The user defined constants used in style template expansion.
247 * @param sourceActor The starting point in an actor tree, from which to look for property owners
248 * @returns The base handle of the created object
250 Animation CreateAnimation( const std::string& animationName, const PropertyValueMap& map, Dali::Actor sourceActor );
253 * @deprecated Use Create()
255 BaseHandle CreateFromStyle( const std::string& styleName );
258 * @deprecated Use Create()
260 BaseHandle CreateFromStyle( const std::string& styleName, const PropertyValueMap& map );
263 * @brief Creates an object (e.g. an actor) from the set of known style templates
266 * mActor.Add( Actor::DownCast(builder.Create( "default-text")) );
268 * @pre The Builder has been initialized.
269 * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
270 * @pre The templateName exists in the templates section of the data representation
271 * and contains 'type' property used to create the object.
272 * @param templateName The template to apply in creation.
273 * @returns The base handle of the created object
275 BaseHandle Create( const std::string& templateName );
278 * @brief Creates an object from the style templates with user defined constants
281 * PropertyValueMap map;
282 * map["IMAGE_DIR"] = "/usr/share/images"; // replaces '{IMAGE_DIR} in the template
283 * mActor.Add( Actor::DownCast(builder.Create( "default-image", map) ) );
285 * @pre The Builder has been initialized.
286 * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
287 * @pre The templateName exists in the templates section of the data representation
288 * and contains 'type' property used to create the object.
289 * @param templateName The template used to create the object.
290 * @param map The user defined constants used in template expansion.
291 * @returns The base handle of the created object
293 BaseHandle Create( const std::string& templateName, const PropertyValueMap& map );
296 * Apply a style (a collection of properties) to an actor.
297 * @pre The Builder has been initialized.
298 * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
299 * @param styleName The name of the set of style properties to set on the handle object.
300 * @param handle Then handle of the object on which to set the properties.
302 * @return Return true if the style was found
304 bool ApplyStyle( const std::string& styleName, Handle& handle );
307 * Add the actor tree in the "stage" section to the actor toActor.
308 * ie if the representation has a 'stage' section that contains a tree of
310 * builder.AddActors( Stage::GetCurrent().GetRootLayer() );
311 * will create and add the actors to the stage root layer.
312 * @param toActor The actor to add the created actors to
314 void AddActors( Actor toActor );
317 * Adds actors in the sectionName to the actor toActor.
318 * ie if the representation has a sectionName section that contains a tree of
320 * builder.AddActors( sectionName, Stage::GetCurrent().GetRootLayer() );
321 * will create and add the actors to the stage root layer.
322 * @param sectionName The section name to search for the actor tree
323 * @param toActor The actor to add the created actors to
325 void AddActors( const std::string §ionName, Actor toActor );
328 * @deprecated Font as a separate asset is no longer supported
329 * Get's a Font asset previously created at load time
330 * An empty handle is returned otherwise.
331 * @pre The Builder has been initialized.
332 * @param name The name given to a Font in the loaded representation
333 * @return A handle to a Font if found, otherwise empty.
335 Font GetFont( const std::string &name ) const;
338 * Get's a TextStyle asset previously created at load time
339 * @pre The Builder has been initialized.
340 * @param name The name given to a TextStyle in the loaded representation
341 * @return a Created TextStyle if found, otherwise return a TextStyle created by Default constructor
343 TextStyle GetTextStyle( const std::string &name ) const;
346 * @deprecated Images as a separate asset is no longer supported
347 * Get's an Image asset previously created at load time
348 * An empty handle is returned otherwise.
349 * @pre The Builder has been initialized.
350 * @param name The name given to an Image in the loaded representation
351 * @return A handle to an Image if found, otherwise empty
353 Image GetImage( const std::string &name ) const;
356 * @deprecated Actors no longer held by builder
357 * Get's an Actor previously created at load time
358 * An empty handle is returned otherwise.
359 * @pre The Builder has been initialized.
360 * @param name The name given to an Actor in the loaded representation
361 * @return A handle to an Actor if found, otherwise empty
363 Actor GetActor( const std::string &name ) const;
366 * @deprecated Animations no longer held by builder
367 * Get's an Animation previously created at load time
368 * An empty handle is returned otherwise.
369 * @pre The Builder has been initialized.
370 * @param name The name given to an Animation in the loaded representation
371 * @return A handle to an Animation if found, otherwise empty
373 Animation GetAnimation( const std::string &name ) const;
376 * Create a render task set.
377 * @pre The Builder has been initialized.
378 * @param name The library name of the render task set.
380 void CreateRenderTask( const std::string &name );
383 * Get or create ShaderEffect from the ShaderEffect instance library.
384 * An empty handle is returned otherwise.
385 * @pre The Builder has been initialized.
386 * @param name The name of a ShaderEffect in the loaded representation
387 * @return A handle to a ShaderEffect if found, otherwise empty
389 ShaderEffect GetShaderEffect( const std::string &name );
392 * Get or create FrameBufferImage from the FrameBufferImage instance library.
393 * An empty handle is returned otherwise.
394 * @pre The Builder has been initialized.
395 * @param name The name of a FrameBufferImage in the loaded representation
396 * @return A handle to a FrameBufferImage if found, otherwise empty
398 FrameBufferImage GetFrameBufferImage( const std::string &name );
401 * @deprecated. Builder no longer holds actor handles/references
402 * Provides a list of the top level actors previously created at load time
403 * @return A container of Actors found at the top level of the loaded representation
405 ActorContainer GetTopLevelActors( void ) const;
408 Builder(Internal::Builder *impl);
412 } // namespace Toolkit
416 #endif // __DALI_TOOLKIT_UIBUILDER_H__