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;
38 * This class provides the ability to load and style an actor tree from a string representation.
40 * The following is an example in JSON.
45 * "templates": // are named instantiable actor trees
51 * "parent-origin":[0.5,0.5,0],
55 * "styles": // are named property sets applied to actor trees
59 * "size": [10,10,1] // root properties applied to a given root actor
60 * "actors": // properties applied to actors found by name from root
62 * "ok": // properties for an actor named "ok"
76 * "type":"default-text",
77 * "text":"Hello World",
85 * The following shows a method to load the json file.
87 * Builder builder = Builder::New();
88 * std::string json_data(ReadFile("layout.json"));
89 * builder.LoadFromString(json_data);
92 * - Load all actors in the "stage" section to the root layer
94 * builder.AddActors( Stage::GetCurrent().GetRootLayer() );
97 * - Create an actor tree from the "templates" section
99 * TextActor actor = TextActor::DownCast( builder.Create( "default-text" ) );
102 * - Style an actor tree from the "styles" section
104 * builder.ApplyStyle( "my-style", actor );
107 * - Create an actor tree from json
109 * TextActor actor = TextActor::DownCast( builder.CreateFromJson("{\"type\":\"TextActor\",\"font\":\"\",\"scale\":[50,50,1]}") );
112 * - Apply a style to an actor tree from json
114 * builder.ApplyFromJson( textActor, ("{\"scale\":[5,5,1]}") );
119 class Builder : public BaseHandle
123 * Create an Builder handle; this can be initialised with Builder::New()
124 * Calling member functions with an uninitialised handle is not allowed.
129 * Creates an Builder object.
130 * @return A handle to the Builder control.
132 static Builder New();
137 * This is non-virtual since derived Handle types must not contain data or virtual methods.
142 * UI string data format
146 JSON, ///< String is JSON
150 * Loads a string representation of an actor tree into memory.
151 * The Actor is not automatically added to the stage.
152 * This function will raise an exception for parse and logical structure errors.
153 * @pre The Builder has been initialized.
154 * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
155 * @param data A string represenation of an Actor tree
156 * @param format The string representation format ie JSON
158 void LoadFromString( const std::string& data, UIFormat format = JSON );
161 * @brief Adds user defined constants to all future style template or animation expansions
164 * PropertyValueMap map;
165 * map["IMAGE_DIRECTORY"] = "/usr/share/images";
166 * builder.AddConstants( map );
168 * @pre The Builder has been initialized.
169 * @param map The user defined constants used in template expansions.
171 void AddConstants( const PropertyValueMap& map );
174 * @brief Adds or modifies a user defined constant to all future style template or animation expansions
178 * builder.AddConstant( "IMAGE_DIRECTORY", "/usr/share/images" );
181 * @pre The Builder has been initialized.
182 * @param key The constant name to add or update
183 * @param value The new value for the constant.
185 void AddConstant( const std::string& key, const Property::Value& value );
188 * @brief Gets all currently defined constants.
192 * PropertyValueMap map = builder.GetConstants(); // get copy of current constants
193 * map["IMAGE_DIRECTORY"] = "/usr/share/images"; // make modification
194 * builder.AddConstants( map ); // write back changes
197 * @pre The Builder has been initialized.
198 * @return A reference to the currently defined constants.
200 const PropertyValueMap& GetConstants() const;
203 * @brief Gets a currently defined constant, or returns Property::INVALID
207 * PropertyValueMap map = builder.GetConstants(); // get copy of current constants
208 * map["IMAGE_DIRECTORY"] = "/usr/share/images"; // make modification
209 * builder.AddConstants( map ); // write back changes
212 * @pre The Builder has been initialized.
213 * @param key The constant name to search for.
215 const Property::Value& GetConstant( const std::string& key ) const;
218 * Creates an animation from the set of known animations
220 * Animation a = builder.CreateAnimation( "wobble");
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 * @returns The base handle of the created object
228 Animation CreateAnimation( const std::string& animationName );
231 * @brief Creates an animation from the set of known animations with user defined constants
234 * PropertyValueMap map;
235 * map["ACTOR"] = actor.GetName(); // replaces '{ACTOR} in the template
236 * Animation a = builder.CreateAnimation( "wobble");
238 * @pre The Builder has been initialized.
239 * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
240 * @pre The animationName exists in the animations section of the data representation
241 * @pre The map contains all the constant expansions in the style template
242 * @param animationName The animation name to create
243 * @param map The user defined constants used in style template expansion.
244 * @returns The base handle of the created object
246 Animation CreateAnimation( const std::string& animationName, const PropertyValueMap& map );
249 * @brief Creates an animation from the set of known animations.
251 * The animation is applied to a specific actor.
253 * Actor myInstance = builder.Create( "template-actor-tree" )
254 * Animation a = builder.CreateAnimation( "wobble", myInstance );
256 * @pre The Builder has been initialized.
257 * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
258 * @pre The animationName exists in the animations section of the data representation
259 * @param animationName The animation name to create
260 * @param sourceActor The starting point in an actor tree, from which to look for property owners
261 * @returns The base handle of the created object
263 Animation CreateAnimation( const std::string& animationName, Dali::Actor sourceActor );
266 * @brief Creates an animation from the set of known animations with user defined constants
268 * The animation is applied to a specific actor.
270 * PropertyValueMap map;
271 * map["ACTOR"] = actor.GetName(); // replaces '{ACTOR} in the template
272 * Actor myInstance = builder.Create( "template-actor-tree" )
273 * Animation a = builder.CreateAnimation( "wobble", myInstance);
275 * @pre The Builder has been initialized.
276 * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
277 * @pre The animationName exists in the animations section of the data representation
278 * @pre The map contains all the constant expansions in the style template
279 * @param animationName The animation name to create
280 * @param map The user defined constants used in style template expansion.
281 * @param sourceActor The starting point in an actor tree, from which to look for property owners
282 * @returns The base handle of the created object
284 Animation CreateAnimation( const std::string& animationName, const PropertyValueMap& map, Dali::Actor sourceActor );
287 * @brief Creates an object (e.g. an actor) from the set of known style templates
290 * mActor.Add( Actor::DownCast(builder.Create( "default-text")) );
292 * @pre The Builder has been initialized.
293 * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
294 * @pre The templateName exists in the templates section of the data representation
295 * and contains 'type' property used to create the object.
296 * @param templateName The template to apply in creation.
297 * @returns The base handle of the created object
299 BaseHandle Create( const std::string& templateName );
302 * @brief Creates an object from the style templates with user defined constants
305 * PropertyValueMap map;
306 * map["IMAGE_DIR"] = "/usr/share/images"; // replaces '{IMAGE_DIR} in the template
307 * mActor.Add( Actor::DownCast(builder.Create( "default-image", map) ) );
309 * @pre The Builder has been initialized.
310 * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
311 * @pre The templateName exists in the templates section of the data representation
312 * and contains 'type' property used to create the object.
313 * @param templateName The template used to create the object.
314 * @param map The user defined constants used in template expansion.
315 * @returns The base handle of the created object
317 BaseHandle Create( const std::string& templateName, const PropertyValueMap& map );
320 * @brief Creates an object (e.g. an actor) from given json snippet
323 * Actor a = Actor::DownCast(builder.CreateFromJson( "{\"type\":\"TextActor\"}"));
325 * @pre The Builder has been initialized.
326 * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
327 * @param json The json snippet used to create the object.
328 * @returns The base handle of the created object if any
330 BaseHandle CreateFromJson( const std::string& json );
333 * Apply a style (a collection of properties) to an actor.
334 * @pre The Builder has been initialized.
335 * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
336 * @param styleName The name of the set of style properties to set on the handle object.
337 * @param handle Then handle of the object on which to set the properties.
339 * @return Return true if the style was found
341 bool ApplyStyle( const std::string& styleName, Handle& handle );
344 * Apply a style (a collection of properties) to an actor from the given json snippet
345 * @pre The Builder has been initialized.
346 * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
347 * @param handle Then handle of the object on which to set the properties.
348 * @param json The json snippet used to create the object.
350 * @return Return true if the json snippet was parsed
352 bool ApplyFromJson( Handle& handle, const std::string& json );
356 * Add the actor tree in the "stage" section to the actor toActor.
357 * ie if the representation has a 'stage' section that contains a tree of
359 * builder.AddActors( Stage::GetCurrent().GetRootLayer() );
360 * will create and add the actors to the stage root layer.
361 * @param toActor The actor to add the created actors to
363 void AddActors( Actor toActor );
366 * Adds actors in the sectionName to the actor toActor.
367 * ie if the representation has a sectionName section that contains a tree of
369 * builder.AddActors( sectionName, Stage::GetCurrent().GetRootLayer() );
370 * will create and add the actors to the stage root layer.
371 * @param sectionName The section name to search for the actor tree
372 * @param toActor The actor to add the created actors to
374 void AddActors( const std::string §ionName, Actor toActor );
377 * Create a render task set.
378 * @pre The Builder has been initialized.
379 * @param name The library name of the render task set.
381 void CreateRenderTask( const std::string &name );
384 * Get or create ShaderEffect from the ShaderEffect instance library.
385 * An empty handle is returned otherwise.
386 * @pre The Builder has been initialized.
387 * @param name The name of a ShaderEffect in the loaded representation
388 * @return A handle to a ShaderEffect if found, otherwise empty
390 ShaderEffect GetShaderEffect( const std::string &name );
393 * Get or create FrameBufferImage from the FrameBufferImage instance library.
394 * An empty handle is returned otherwise.
395 * @pre The Builder has been initialized.
396 * @param name The name of a FrameBufferImage in the loaded representation
397 * @return A handle to a FrameBufferImage if found, otherwise empty
399 FrameBufferImage GetFrameBufferImage( const std::string &name );
402 Builder(Internal::Builder *impl);
406 } // namespace Toolkit
410 #endif // __DALI_TOOLKIT_UIBUILDER_H__