5 # DALi JSON Specification {#script-json-specification}
7 ## Overview {#overview}
9 This document describes the Dali JSON specification.
10 The format is not yet formally versioned within the JSON.
12 # General format {#format}
14 The JSON format supports
16 - Named templates for on demand creation of
20 - Dynamically change the style of Actor hierarchies
21 - Animate to a style set
23 - Build style sets up by merging JSON
24 - Creating Scene content on load
25 - Controls created without any code
28 Concrete Actors and Controls can be created from types registered in the
31 Template, style and scene sections all configure Actors and Controls via
32 the Dali property system.
34 The JSON format deviates from the formal JSON specification and allows C style comments.
38 "version": 0, // Version Number
39 "includes": // Include section
41 "base-theme.json" // Include file to merge into the
44 "constants": // Constant replacement section
48 "templates": // Template library section
50 "basic-text": // A named template
51 { // } key value properties
53 "actors": // A tree of sub actors
59 "styles": // Named Style set section
61 "light-theme": // Style set name
70 "stage": // Stage section
72 { // Actors|Controls to create on JSON file load
73 "type": "basic-text", // A Dali Control or a template name
74 "styles":["base-theme","light-theme"] // Style list to apply to this instance
80 # Top level sections {#sections}
82 ## Includes {#includes}
84 The "includes" section is an array of filenames to be merged in order to
85 create a final in memory JSON tree.
87 The merge process will walk key, value attributes from the root JSON
88 node and overwrite previous values with the newer values.
90 - If the key does not exist then it will be created.
91 - If the newer value is a different type then the newer type will persist.
92 - Where both values are objects the merge will descend into the object.
93 - Where both values are arrays the merge will replace the old array entirely.
95 The merge is relatively simple and is expected to be used to build up
96 from base themes to custom themes where there are few conflicts and
97 simple direct replacements are desired.
99 ### Constants {#constants}
101 The merge behaviour when a file has constants and includes is
103 1. Constants are loaded first
104 2. Includes file list is merged in order
105 3. All other (non constant) data is merged
107 The include merge is recursive, so step (2) above will cause the
108 constants in the first included file to be merged first.
110 ## Constants {#constantdetail}
112 The constants section supports sub-string and full property replacement.
116 "constants": // Constant replacement section
118 "IMAGES": "/usr/share/images/", // Constants can be set here or in code.
119 "SIZE": [100,100,1] //
123 "type":"ImageActor" // An Dali type or a template name
126 "filename":"{IMAGES}b.jpg" // Image filename substring replacement
129 } // Property replacement
133 The type of the constant should match the expected type of the property.
135 A property constant cannot be used for sub string replacement; a string
136 constant should be used.
138 With a property replacement, the replace site must contain a string
139 where the first and last positions are braces.
141 ## Templates {#templates}
143 The template section supports the creation of actor instances. The
144 template name can be used in code to create an actor tree.
149 var builder = new dali.Builder();
150 builder.loadFromFile( "my-app.json");
151 var userActorTree = builder.create( { template:"basic-text"} );
157 Builder builder = Builder::New();
158 std::string jsonData = loadFile("my-app.json");
159 builder.LoadFromString( jsonData );
161 actorTree = builder.Create("basic-text");
164 Templates consist of a name, multiple property-value configurations and
165 an optional actor sub hierarchy.
169 "templates": // Template library section
171 "basic-text": // The template name
173 "type":"ImageActor", // Concrete Dali Type/Class to create
174 "styles":["base-style"], // Style list to apply
176 "image": // } property name : value
178 "filename":"{IMAGES}/b.jpg" //
180 "parent-origin": "CENTER" //
182 "actors": // A tree of sub actors
187 "text":"Hello World", //
188 "parent-origin": "CENTER", //
195 A template has a special 'type' property which must contain a concrete
196 Dali Actor or Control type name.
198 A template has a special 'styles' property which contains a list of
199 styles to apply when creating using the template.
203 The styles section supports a named set of properties that can be
204 applied to an actor or actor tree.
209 Builder.ApplyStyle("light-theme", myActor);
215 builder.applyStyle("light-theme", myActor);
219 The styles can also be applied as an animation.
222 Builder.AnimateTo("light-theme", myActor, TimePeriod(0, 10));
229 "styles": // Style set section
231 "light-theme": // Style-set name
233 "color":[1,1,1,1] // }
234 "position":[0,-120,0], // } properties to set on the given actor
235 "rotation":[0,0,30], // }
237 { // Sub Actors are referenced by name
238 "title-text": // Actor name to search for under given actor
240 "color":[1,1,1,1] // }
241 "position":[0,-120,0], // } properties to set if 'title-text' is found
242 "rotation":[0,0,30], // }
256 When applied to an actor tree the actors are referenced by name. Names
257 are not unique in Dali.
259 When a style is applied in code Dali will perform a depth first search
260 stopping with the first matching name.
262 Typically an application developer will apply the style to the template
263 root actor and not the stage root actor. Therefore in most uses cases
264 name conflicts are not expected.
266 ## Animations {#animations}
268 The animation section defines a library of animation definitions.
270 The animations can be created by name from code.
272 They can also be created automatically from JSON in an actor signal.
276 "animations": // Animation library
278 "rotate": // An Animation named rotate
280 "duration": 10, // Duration in seconds
281 "loop": false, // Whether to loop.
282 "end-action": "Bake", // Whether to set final value(bake) or
284 "disconnect-aciton": "Discard", // Whether 'Bake' or 'Discard' when disconnected
287 // Properties changed in this animation
289 "actor":"image", // Actor found by name from the stage
290 "property":"rotation", // Property to change
291 "value":[0, 0.1, 0, 0], // Value to set
292 "alpha-function": "EASE\_IN\_OUT", // Interpolation function
294 "time-period": // Time period for change
299 ... // 1 or more property changes per animation
305 ### Splines {#splines}
307 An animation property can be defined with a path and forward direction
308 instead of a single final value.
310 Paths are defined in a top level path section and referenced by the
315 "paths": // Path library
317 "path0": // Path definition by name
324 // curvature automatically creates
325 "curvature":0.35, // control-points
327 "control-points": [...] // Otherwise control-points can be
328 // directly specified.
339 "actor": "greeting2",
340 // Path is mandatory for spline
341 "path":"path0", // animation.
342 "forward":[1,0,0], // Forward vector specifies orientation
343 // whilst travelling along the path
344 "alpha-function": "EASE\_IN\_OUT", // (optional)
352 // Other properties changes can use
353 ] // paths or values in the same
359 ## Shaders {#shaders}
361 The shader section of the JSON file defines a library of shader effect
362 instances that are created on demand.
364 The shaders are referred to by name from the template, style, stage or
367 Multiple actors can set the same shader as the name refers to a single
370 Similarly one named shader instance can be set to several actors and can
371 be animated by one animation.
375 "shader-effects": // Shader Effect section
377 "myshader1": // Shader instance name
380 { // Prefixs are placed before DALi uniforms.
381 "vertexPrefix": "", // (Useful for \#defines.)
382 "vertex":"", // Glsl vertex program
383 "fragmentPrefix": "",
384 "fragment": "", // Glsl fragment program.
385 "geometry-type": "GEOMETRY_TYPE_IMAGE", // Geometry type(see DALi documentation)
387 "geometry-hints": "HINT_NONE": // Geometry hints (see DALi documentation)
388 "grid-density": 0, // Grid density(see DALi documentation)
391 "filename": "" // Effect image available as a second texture unit.
398 "type": "ImageActor",
399 "effect": "myshader1",
405 At least one of the vertex or fragment fields is mandatory. All
406 other fields are optional will use internal defaults.
408 Actors have an "effect" field that refers to the shader effect
409 instance to use with that actor.
411 ### Animating shaders {#animatingshaders}
413 Shader uniforms can be animated as if they are properties of the actor.
415 When the animation is created from code (or from a signal) the property
416 name search begins on the actor, if it isn't found the search continues
417 on the attached shader object.
419 The actor property names and shader uniform names must not clash for the
420 uniform to animate correctly. The convention in DALi is to prepend
425 "animations": \\ Animation library
427 "rotate": \\ An Animation named rotate
430 "properties": \\ Properties changed in this animation
433 "actor":"image", \\ Actor found by name from the stage
434 "property":"uTranslate", \\ Uniform name specified as if it is a
435 \\ property of the object.
446 \\ Shader program with uniform
447 "program": {...} \\ "uTranslate"
454 "effect": "myshader1" \\ Actor using shader effect instance
463 The stage section supports the immediate creation of actors at the time
466 The stage is a tree of actors that can be added to Dali's stage object.
470 builder = Dali.Builder();
471 json_text = load("layout.json");
472 builder.Load(json\_text);
473 stage = Dali.Stage.GetCurrent();
474 builder.AddActors( stage.GetRootLayer()); // Add actors to the stage root layer
480 builder.addActors( dali.stage.getRootLayer() );
485 "stage": \\ Stage Section Number
486 [ \\ An array of actors
488 "type": "ImageActor",
490 "actors": \\ Each actor can have children
495 \\ The Type to create; this can be a
496 ... \\ concrete Dali type (actor/control)
497 \\ or a template name.
498 "styles": ["base-style"]
499 \\ A list of styles to apply to the
507 # Actor and Control Properties {#actorprop}
509 Each control has a set of supported properties documented in the "Dali
510 UI Control Specification".
512 Please refer to the above document for further information about specific
515 @class _Guide_JSON_Specification