1 #ifndef __DALI_TOOLKIT_UIBUILDER_H__
2 #define __DALI_TOOLKIT_UIBUILDER_H__
5 * Copyright (c) 2014 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/dali.h>
24 namespace Dali DALI_IMPORT_API
30 namespace Internal DALI_INTERNAL
35 typedef std::map<std::string, Property::Value> PropertyValueMap;
39 * This class provides the ability to load an actor tree from a string representation.
41 * The following example is hello world in JSON.
52 * "parent-origin":[0.5,0.5,0],
59 * "type":"default-text",
60 * "text":"Hello World",
70 * The following is how to load the json data.
74 * Builder builder = Builder::New();
76 * std::string json_data(ReadFile("layout.json"));
78 * builder.LoadFromString(json_data);
80 * // 1) load all actors in the "stage" section to the root layer
81 * builder.AddActors( Stage::GetCurrent().GetRootLayer() );
83 * // or 2) create an actor from the library "templates" section
84 * TextActor actor = TextActor::DownCast( builder.Create( "default-text" ) );
88 class Builder : public BaseHandle
92 * Create an Builder handle; this can be initialised with Builder::New()
93 * Calling member functions with an uninitialised handle is not allowed.
98 * Creates an Builder object.
99 * @return A handle to the Builder control.
101 static Builder New();
106 * This is non-virtual since derived Handle types must not contain data or virtual methods.
111 * UI string data format
115 JSON, ///< String is JSON
119 * Loads a string representation of an actor tree into memory.
120 * The Actor is not automatically added to the stage.
121 * This function will raise an exception for parse and logical structure errors.
122 * @pre The Builder has been initialized.
123 * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
124 * @param data A string represenation of an Actor tree
125 * @param format The string representation format ie JSON
127 void LoadFromString( const std::string& data, UIFormat format = JSON );
130 * @brief Adds user defined constants to all future style template or animation expansions
133 * PropertyValueMap map;
134 * map["IMAGE_DIRECTORY"] = "/usr/share/images";
135 * builder.AddConstants( map );
137 * @pre The Builder has been initialized.
138 * @param map The user defined constants used in template expansions.
140 void AddConstants( const PropertyValueMap& map );
143 * @brief Adds or modifies a user defined constant to all future style template or animation expansions
147 * builder.AddConstant( "IMAGE_DIRECTORY", "/usr/share/images" );
150 * @pre The Builder has been initialized.
151 * @param key The constant name to add or update
152 * @param value The new value for the constant.
154 void AddConstant( const std::string& key, const Property::Value& value );
157 * @brief Gets all currently defined constants.
161 * PropertyValueMap map = builder.GetConstants(); // get copy of current constants
162 * map["IMAGE_DIRECTORY"] = "/usr/share/images"; // make modification
163 * builder.AddConstants( map ); // write back changes
166 * @pre The Builder has been initialized.
167 * @return A reference to the currently defined constants.
169 const PropertyValueMap& GetConstants() const;
172 * @brief Gets a currently defined constant, or returns Property::INVALID
176 * PropertyValueMap map = builder.GetConstants(); // get copy of current constants
177 * map["IMAGE_DIRECTORY"] = "/usr/share/images"; // make modification
178 * builder.AddConstants( map ); // write back changes
181 * @pre The Builder has been initialized.
182 * @param key The constant name to search for.
184 const Property::Value& GetConstant( const std::string& key ) const;
187 * Creates an animation from the set of known animations
189 * Animation a = builder.CreateAnimation( "wobble");
191 * @pre The Builder has been initialized.
192 * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
193 * @pre The animationName exists in the animations section of the data representation
194 * @param animationName The animation name to create
195 * @returns The base handle of the created object
197 Animation CreateAnimation( const std::string& animationName );
200 * @brief Creates an animation from the set of known animations with user defined constants
203 * PropertyValueMap map;
204 * map["ACTOR"] = actor.GetName(); // replaces '{ACTOR} in the template
205 * Animation a = builder.CreateAnimation( "wobble");
207 * @pre The Builder has been initialized.
208 * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
209 * @pre The animationName exists in the animations section of the data representation
210 * @pre The map contains all the constant expansions in the style template
211 * @param animationName The animation name to create
212 * @param map The user defined constants used in style template expansion.
213 * @returns The base handle of the created object
215 Animation CreateAnimation( const std::string& animationName, const PropertyValueMap& map );
218 * @brief Creates an animation from the set of known animations.
220 * The animation is applied to a specific actor.
222 * Actor myInstance = builder.Create( "template-actor-tree" )
223 * Animation a = builder.CreateAnimation( "wobble", myInstance );
225 * @pre The Builder has been initialized.
226 * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
227 * @pre The animationName exists in the animations section of the data representation
228 * @param animationName The animation name to create
229 * @param sourceActor The starting point in an actor tree, from which to look for property owners
230 * @returns The base handle of the created object
232 Animation CreateAnimation( const std::string& animationName, Dali::Actor sourceActor );
235 * @brief Creates an animation from the set of known animations with user defined constants
237 * The animation is applied to a specific actor.
239 * PropertyValueMap map;
240 * map["ACTOR"] = actor.GetName(); // replaces '{ACTOR} in the template
241 * Actor myInstance = builder.Create( "template-actor-tree" )
242 * Animation a = builder.CreateAnimation( "wobble", myInstance);
244 * @pre The Builder has been initialized.
245 * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
246 * @pre The animationName exists in the animations section of the data representation
247 * @pre The map contains all the constant expansions in the style template
248 * @param animationName The animation name to create
249 * @param map The user defined constants used in style template expansion.
250 * @param sourceActor The starting point in an actor tree, from which to look for property owners
251 * @returns The base handle of the created object
253 Animation CreateAnimation( const std::string& animationName, const PropertyValueMap& map, Dali::Actor sourceActor );
256 * @deprecated Use Create()
258 BaseHandle CreateFromStyle( const std::string& styleName );
261 * @deprecated Use Create()
263 BaseHandle CreateFromStyle( const std::string& styleName, const PropertyValueMap& map );
266 * @brief Creates an object (e.g. an actor) from the set of known style templates
269 * mActor.Add( Actor::DownCast(builder.Create( "default-text")) );
271 * @pre The Builder has been initialized.
272 * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
273 * @pre The templateName exists in the templates section of the data representation
274 * and contains 'type' property used to create the object.
275 * @param templateName The template to apply in creation.
276 * @returns The base handle of the created object
278 BaseHandle Create( const std::string& templateName );
281 * @brief Creates an object from the style templates with user defined constants
284 * PropertyValueMap map;
285 * map["IMAGE_DIR"] = "/usr/share/images"; // replaces '{IMAGE_DIR} in the template
286 * mActor.Add( Actor::DownCast(builder.Create( "default-image", map) ) );
288 * @pre The Builder has been initialized.
289 * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
290 * @pre The templateName exists in the templates section of the data representation
291 * and contains 'type' property used to create the object.
292 * @param templateName The template used to create the object.
293 * @param map The user defined constants used in template expansion.
294 * @returns The base handle of the created object
296 BaseHandle Create( const std::string& templateName, const PropertyValueMap& map );
299 * Apply a style (a collection of properties) to an actor.
300 * @pre The Builder has been initialized.
301 * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
302 * @param styleName The name of the set of style properties to set on the handle object.
303 * @param handle Then handle of the object on which to set the properties.
305 * @return Return true if the style was found
307 bool ApplyStyle( const std::string& styleName, Handle& handle );
310 * Add the actor tree in the "stage" section to the actor toActor.
311 * ie if the representation has a 'stage' section that contains a tree of
313 * builder.AddActors( Stage::GetCurrent().GetRootLayer() );
314 * will create and add the actors to the stage root layer.
315 * @param toActor The actor to add the created actors to
317 void AddActors( Actor toActor );
320 * Adds actors in the sectionName to the actor toActor.
321 * ie if the representation has a sectionName section that contains a tree of
323 * builder.AddActors( sectionName, Stage::GetCurrent().GetRootLayer() );
324 * will create and add the actors to the stage root layer.
325 * @param sectionName The section name to search for the actor tree
326 * @param toActor The actor to add the created actors to
328 void AddActors( const std::string §ionName, Actor toActor );
331 * @deprecated Font as a separate asset is no longer supported
332 * Get's a Font asset previously created at load time
333 * An empty handle is returned otherwise.
334 * @pre The Builder has been initialized.
335 * @param name The name given to a Font in the loaded representation
336 * @return A handle to a Font if found, otherwise empty.
338 Font GetFont( const std::string &name ) const;
341 * Get's a TextStyle asset previously created at load time
342 * @pre The Builder has been initialized.
343 * @param name The name given to a TextStyle in the loaded representation
344 * @return a Created TextStyle if found, otherwise return a TextStyle created by Default constructor
346 TextStyle GetTextStyle( const std::string &name ) const;
349 * @deprecated Images as a separate asset is no longer supported
350 * Get's an Image asset 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 Image in the loaded representation
354 * @return A handle to an Image if found, otherwise empty
356 Image GetImage( const std::string &name ) const;
359 * @deprecated Actors no longer held by builder
360 * Get's an Actor previously created at load time
361 * An empty handle is returned otherwise.
362 * @pre The Builder has been initialized.
363 * @param name The name given to an Actor in the loaded representation
364 * @return A handle to an Actor if found, otherwise empty
366 Actor GetActor( const std::string &name ) const;
369 * @deprecated Animations no longer held by builder
370 * Get's an Animation previously created at load time
371 * An empty handle is returned otherwise.
372 * @pre The Builder has been initialized.
373 * @param name The name given to an Animation in the loaded representation
374 * @return A handle to an Animation if found, otherwise empty
376 Animation GetAnimation( const std::string &name ) const;
379 * Create a render task set.
380 * @pre The Builder has been initialized.
381 * @param name The library name of the render task set.
383 void CreateRenderTask( const std::string &name );
386 * Get or create ShaderEffect from the ShaderEffect instance library.
387 * An empty handle is returned otherwise.
388 * @pre The Builder has been initialized.
389 * @param name The name of a ShaderEffect in the loaded representation
390 * @return A handle to a ShaderEffect if found, otherwise empty
392 ShaderEffect GetShaderEffect( const std::string &name );
395 * Get or create FrameBufferImage from the FrameBufferImage instance library.
396 * An empty handle is returned otherwise.
397 * @pre The Builder has been initialized.
398 * @param name The name of a FrameBufferImage in the loaded representation
399 * @return A handle to a FrameBufferImage if found, otherwise empty
401 FrameBufferImage GetFrameBufferImage( const std::string &name );
404 * @deprecated. Builder no longer holds actor handles/references
405 * Provides a list of the top level actors previously created at load time
406 * @return A container of Actors found at the top level of the loaded representation
408 ActorContainer GetTopLevelActors( void ) const;
411 Builder(Internal::Builder *impl);
415 } // namespace Toolkit
419 #endif // __DALI_TOOLKIT_UIBUILDER_H__