6 # DALi JSON Specification {#script-json-specification}
8 ## Overview {#overview}
10 This document describes the DALi JSON specification.
11 The format is not yet formally versioned within the JSON.
13 # General format {#format}
15 The JSON format supports
17 - Named templates for on demand creation of
21 - Dynamically change the style of Actor hierarchies
22 - Animate to a style set
24 - Build style sets up by merging JSON
25 - Creating Scene content on load
26 - Controls created without any code
29 Concrete Actors and Controls can be created from types registered in the
32 Template, style and scene sections all configure Actors and Controls via
33 the DALi property system.
35 The JSON format deviates from the formal JSON specification and allows C style comments.
39 "version": 0, // Version Number
40 "includes": // Include section
42 "base-theme.json" // Include file to merge into the
45 "constants": // Constant replacement section
49 "templates": // Template library section
51 "basic-text": // A named template
52 { // } key value properties
54 "actors": // A tree of sub actors
60 "styles": // Named Style set section
62 "light-theme": // Style set name
71 "stage": // Stage section
73 { // Actors|Controls to create on JSON file load
74 "type": "basic-text", // A DALi Control or a template name
75 "styles":["base-theme","light-theme"] // Style list to apply to this instance
81 # Top level sections {#sections}
83 ## Includes {#includes}
85 The "includes" section is an array of file names to be merged in order to
86 create a final in memory JSON tree.
88 The merge process will walk key, value attributes from the root JSON
89 node and overwrite previous values with the newer values.
91 - If the key does not exist then it will be created.
92 - If the newer value is a different type then the newer type will persist.
93 - Where both values are objects the merge will descend into the object.
94 - Where both values are arrays the merge will replace the old array entirely.
96 The merge is relatively simple and is expected to be used to build up
97 from base themes to custom themes where there are few conflicts and
98 simple direct replacements are desired.
100 ### Constants {#constants}
102 The merge behaviour when a file has constants and includes is
104 1. Constants are loaded first
105 2. Includes file list is merged in order
106 3. All other (non constant) data is merged
108 The include merge is recursive, so step (2) above will cause the
109 constants in the first included file to be merged first.
111 ## Constants {#constantdetail}
113 The constants section supports sub-string and full property replacement.
117 "constants": // Constant replacement section
119 "IMAGES": "/usr/share/images/", // Constants can be set here or in code.
120 "SIZE": [100,100,1] //
124 "type":"ImageView" // An DALi type or a template name
127 "url":"{IMAGES}b.jpg" // Image filename substring replacement
130 } // Property replacement
134 The type of the constant should match the expected type of the property.
136 A property constant cannot be used for sub string replacement; a string
137 constant should be used.
139 With a property replacement, the replace site must contain a string
140 where the first and last positions are braces.
142 ## Templates {#templates}
144 The template section supports the creation of actor instances. The
145 template name can be used in code to create an actor tree.
150 Builder builder = Builder::New();
151 std::string jsonData = loadFile("my-app.json");
152 builder.LoadFromString( jsonData );
154 actorTree = builder.Create("basic-text");
157 Templates consist of a name, multiple property-value configurations and
158 an optional actor sub hierarchy.
162 "templates": // Template library section
164 "basic-text": // The template name
166 "type":"ImageView", // Concrete DALi Type/Class to create
167 "styles":["base-style"], // Style list to apply
169 "image": // } property name : value
171 "url":"{IMAGES}/b.jpg" //
173 "parentOrigin": "CENTER" //
175 "actors": // A tree of sub actors
180 "text":"Hello World", //
181 "parentOrigin": "CENTER", //
188 A template has a special 'type' property which must contain a concrete
189 DALi Actor or Control type name.
191 A template has a special 'styles' property which contains a list of
192 styles to apply when creating using the template.
196 The styles section supports a named set of properties that can be
197 applied to an actor or actor tree.
202 Builder.ApplyStyle("light-theme", myActor);
205 The styles can also be applied as an animation.
208 Builder.AnimateTo("light-theme", myActor, TimePeriod(0, 10));
215 "styles": // Style set section
217 "light-theme": // Style-set name
219 "color":[1,1,1,1] // }
220 "position":[0,-120,0], // } properties to set on the given actor
221 "rotation":[0,0,30], // }
223 { // Sub Actors are referenced by name
224 "title-text": // Actor name to search for under given actor
226 "color":[1,1,1,1] // }
227 "position":[0,-120,0], // } properties to set if 'title-text' is found
228 "rotation":[0,0,30], // }
242 When applied to an actor tree the actors are referenced by name. Names
243 are not unique in DALi.
245 When a style is applied in code DALi will perform a depth first search
246 stopping with the first matching name.
248 Typically an application developer will apply the style to the template
249 root actor and not the stage root actor. Therefore in most uses cases
250 name conflicts are not expected.
252 ## Animations {#animations}
254 The animation section defines a library of animation definitions.
256 The animations can be created by name from code.
258 They can also be created automatically from JSON in an actor signal.
262 "animations": // Animation library
264 "rotate": // An Animation named rotate
266 "duration": 10, // Duration in seconds
267 "loop": false, // Whether to loop.
268 "endAction": "Bake", // Whether to set final value(bake) or
270 "disconnectAction": "Discard", // Whether 'Bake' or 'Discard' when disconnected
273 // Properties changed in this animation
275 "actor":"image", // Actor found by name from the stage
276 "property":"rotation", // Property to change
277 "value":[0, 0.1, 0, 0], // Value to set
278 "alphaFunction": "EASE\_IN\_OUT", // Interpolation function
280 "timePeriod": // Time period for change
285 ... // 1 or more property changes per animation
291 ### Splines {#splines}
293 An animation property can be defined with a path and forward direction
294 instead of a single final value.
296 Paths are defined in a top level path section and referenced by the
301 "paths": // Path library
303 "path0": // Path definition by name
310 // curvature automatically creates
311 "curvature":0.35, // controlPoints
313 "controlPoints": [...] // Otherwise controlPoints can be
314 // directly specified.
325 "actor": "greeting2",
326 // Path is mandatory for spline
327 "path":"path0", // animation.
328 "forward":[1,0,0], // Forward vector specifies orientation
329 // whilst travelling along the path
330 "alphaFunction": "EASE\_IN\_OUT", // (optional)
338 // Other properties changes can use
339 ] // paths or values in the same
345 At least one of the vertex or fragment fields is mandatory. All
346 other fields are optional will use internal defaults.
348 Actors have an "effect" field that refers to the shader effect
349 instance to use with that actor.
351 ### Animating shaders {#animatingshaders}
353 Shader uniforms can be animated as if they are properties of the actor.
355 When the animation is created from code (or from a signal) the property
356 name search begins on the actor, if it isn't found the search continues
357 on the attached renderer, and then on the attached shader object.
359 The actor property names and shader uniform names must not clash for the
360 uniform to animate correctly.
362 The actor needs to register the uniform properties as custom animatable
369 "rotate": \\ An Animation named rotate
371 "properties": \\ Properties changed in this animation
374 "actor": "image", \\ Actor found by name from the stage
375 "property": "uTranslate", \\ Uniform name specified as if it is a property of the object
376 "value": [10, 20], \\ Target value of uniform
387 "name": "image", \\ Name of the actor
392 "shader": \\ ImageView has a shader property where we can set a custom shader
394 "vertexShader": "..." \\ Vertex shader with uniform "uTranslate"
397 "animatableProperties": \\ Custom properties that the actor needs to register
399 "uTranslate": [0, 0] \\ The name should match the uniform we want to animate
410 The stage section supports the immediate creation of actors at the time
413 The stage is a tree of actors that can be added to DALi's stage object.
417 builder = Dali.Builder();
418 json_text = load("layout.json");
419 builder.Load(json\_text);
420 stage = Dali.Stage.GetCurrent();
421 builder.AddActors( stage.GetRootLayer()); // Add actors to the stage root layer
426 "stage": \\ Stage Section Number
427 [ \\ An array of actors
431 "actors": \\ Each actor can have children
436 \\ The Type to create; this can be a
437 ... \\ concrete DALi type (actor/control)
438 \\ or a template name.
439 "styles": ["base-style"]
440 \\ A list of styles to apply to the
448 # Actor and Control Properties {#actorprop}
450 Each control has a set of supported properties documented in the "DALi
451 UI Control Specification".
453 Please refer to the above document for further information about specific