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
36 * This class provides the ability to load an actor tree from a string representation.
38 * The following example is hello world in JSON.
49 * "parent-origin":[0.5,0.5,0],
56 * "type":"default-text",
57 * "text":"Hello World",
67 * The following is how to load the json data.
71 * Builder builder = Builder::New();
73 * std::string json_data(ReadFile("layout.json"));
75 * builder.LoadFromString(json_data);
77 * // 1) load all actors in the "stage" section to the root layer
78 * builder.AddActors( Stage::GetCurrent().GetRootLayer() );
80 * // or 2) create an actor from the library "styles" section
81 * TextActor actor = TextActor::DownCast( builder.CreateFromStyle( "default-text" ) );
85 class Builder : public BaseHandle
89 * Create an Builder handle; this can be initialised with Builder::New()
90 * Calling member functions with an uninitialised handle is not allowed.
95 * Creates an Builder object.
96 * @return A handle to the Builder control.
101 * Virtual destructor.
106 * UI string data format
110 JSON, ///< String is JSON
114 * Loads a string representation of an actor tree into memory.
115 * The Actor is not automatically added to the stage.
116 * This function will raise an exception for parse and logical structure errors.
117 * @pre The Builder has been initialized.
118 * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
119 * @param data A string represenation of an Actor tree
120 * @param format The string representation format ie JSON
122 void LoadFromString( const std::string& data, UIFormat format = JSON );
125 * Creates an animation from the set of known animations
127 * Animation a = builder.CreateAnimation( "wobble");
129 * @pre The Builder has been initialized.
130 * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
131 * @pre The animationName exists in the animations section of the data representation
132 * @param animationName The animation name to create
133 * @returns The base handle of the created object
135 Animation CreateAnimation( const std::string& animationName );
138 * Creates an object (e.g. an actor) from the set of known styles
140 * mActor.Add( Actor::DownCast(builder.CreateFromStyle( "default-text")) );
142 * @pre The Builder has been initialized.
143 * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
144 * @pre The styleName has been loaded from the styles section of the data representation
145 * and contains 'type' property used to create the object.
146 * @param styleName The set of styles/properties to set on the handle object.
147 * @returns The base handle of the created object
149 BaseHandle CreateFromStyle( const std::string& styleName );
152 * Apply a style (a collection of properties) to an actor.
153 * @pre The Builder has been initialized.
154 * @pre Preconditions have been met for creating dali objects ie Images, Actors etc
155 * @param styleName The name of the set of style properties to set on the handle object.
156 * @param handle Then handle of the object on which to set the properties.
158 void ApplyStyle( const std::string& styleName, Handle& handle );
161 * Add the actor tree in the "stage" section to the actor toActor.
162 * ie if the representation has a 'stage' section that contains a tree of
164 * builder.AddActors( Stage::GetCurrent().GetRootLayer() );
165 * will create and add the actors to the stage root layer.
166 * @param toActor The actor to add the created actors to
168 void AddActors( Actor toActor );
171 * Adds actors in the sectionName to the actor toActor.
172 * ie if the representation has a sectionName section that contains a tree of
174 * builder.AddActors( sectionName, Stage::GetCurrent().GetRootLayer() );
175 * will create and add the actors to the stage root layer.
176 * @param sectionName The section name to search for the actor tree
177 * @param toActor The actor to add the created actors to
179 void AddActors( const std::string §ionName, Actor toActor );
182 * @deprecated Font as a separate asset is no longer supported
183 * Get's a Font asset previously created at load time
184 * An empty handle is returned otherwise.
185 * @pre The Builder has been initialized.
186 * @param name The name given to a Font in the loaded representation
187 * @return A handle to a Font if found, otherwise empty.
189 Font GetFont( const std::string &name ) const;
192 * Get's a TextStyle asset previously created at load time
193 * @pre The Builder has been initialized.
194 * @param name The name given to a TextStyle in the loaded representation
195 * @return a Created TextStyle if found, otherwise return a TextStyle created by Default constructor
197 TextStyle GetTextStyle( const std::string &name ) const;
200 * @deprecated Images as a separate asset is no longer supported
201 * Get's an Image asset previously created at load time
202 * An empty handle is returned otherwise.
203 * @pre The Builder has been initialized.
204 * @param name The name given to an Image in the loaded representation
205 * @return A handle to an Image if found, otherwise empty
207 Image GetImage( const std::string &name ) const;
210 * @deprecated Actors no longer held by builder
211 * Get's an Actor previously created at load time
212 * An empty handle is returned otherwise.
213 * @pre The Builder has been initialized.
214 * @param name The name given to an Actor in the loaded representation
215 * @return A handle to an Actor if found, otherwise empty
217 Actor GetActor( const std::string &name ) const;
220 * @deprecated Animations no longer held by builder
221 * Get's an Animation previously created at load time
222 * An empty handle is returned otherwise.
223 * @pre The Builder has been initialized.
224 * @param name The name given to an Animation in the loaded representation
225 * @return A handle to an Animation if found, otherwise empty
227 Animation GetAnimation( const std::string &name ) const;
230 * Create a render task set.
231 * @pre The Builder has been initialized.
232 * @param name The library name of the render task set.
234 void CreateRenderTask( const std::string &name );
237 * Get or create ShaderEffect from the ShaderEffect instance library.
238 * An empty handle is returned otherwise.
239 * @pre The Builder has been initialized.
240 * @param name The name of a ShaderEffect in the loaded representation
241 * @return A handle to a ShaderEffect if found, otherwise empty
243 ShaderEffect GetShaderEffect( const std::string &name );
246 * Get or create FrameBufferImage from the FrameBufferImage instance library.
247 * An empty handle is returned otherwise.
248 * @pre The Builder has been initialized.
249 * @param name The name of a FrameBufferImage in the loaded representation
250 * @return A handle to a FrameBufferImage if found, otherwise empty
252 FrameBufferImage GetFrameBufferImage( const std::string &name );
255 * @deprecated. Builder no longer holds actor handles/references
256 * Provides a list of the top level actors previously created at load time
257 * @return A container of Actors found at the top level of the loaded representation
259 ActorContainer GetTopLevelActors( void ) const;
262 Builder(Internal::Builder *impl);
266 } // namespace Toolkit
270 #endif // __DALI_TOOLKIT_UIBUILDER_H__