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.
147 actorTree = builder.Create("basic-text");
150 Templates consist of a name, multiple property-value configurations and
151 an optional actor sub hierarchy.
155 "templates": // Template library section
157 "basic-text": // The template name
159 "type":"ImageActor", // Concrete Dali Type/Class to create
160 "styles":["base-style"], // Style list to apply
162 "image": // } property name : value
164 "filename":"{IMAGES}/b.jpg" //
166 "parent-origin": "CENTER" //
168 "actors": // A tree of sub actors
173 "text":"Hello World", //
174 "parent-origin": "CENTER", //
181 A template has a special 'type' property which must contain a concrete
182 Dali Actor or Control type name.
184 A template has a special 'styles' property which contains a list of
185 styles to apply when creating using the template.
189 The styles section supports a named set of properties that can be
190 applied to an actor or actor tree.
193 Builder.ApplyStyle("light-theme", myActor);
196 The styles can also be applied as an animation.
199 Builder.AnimateTo("light-theme", myActor, TimePeriod(0, 10));
204 "styles": // Style set section
206 "light-theme": // Style-set name
208 "color":[1,1,1,1] // }
209 "position":[0,-120,0], // } properties to set on the given actor
210 "rotation":[0,0,30], // }
212 { // Sub Actors are referenced by name
213 "title-text": // Actor name to search for under given actor
215 "color":[1,1,1,1] // }
216 "position":[0,-120,0], // } properties to set if 'title-text' is found
217 "rotation":[0,0,30], // }
231 When applied to an actor tree the actors are referenced by name. Names
232 are not unique in Dali.
234 When a style is applied in code Dali will perform a depth first search
235 stopping with the first matching name.
237 Typically an application developer will apply the style to the template
238 root actor and not the stage root actor. Therefore in most uses cases
239 name conflicts are not expected.
241 ## Animations {#animations}
243 The animation section defines a library of animation definitions.
245 The animations can be created by name from code.
247 They can also be created automatically from JSON in an actor signal.
251 "animations": // Animation library
253 "rotate": // An Animation named rotate
255 "duration": 10, // Duration in seconds
256 "loop": false, // Whether to loop.
257 "end-action": "Bake", // Whether to set final value(bake) or
259 "disconnect-aciton": "Discard", // Whether 'Bake' or 'Discard' when disconnected
262 // Properties changed in this animation
264 "actor":"image", // Actor found by name from the stage
265 "property":"rotation", // Property to change
266 "value":[0, 0.1, 0, 0], // Value to set
267 "alpha-function": "EASE\_IN\_OUT", // Interpolation function
269 "time-period": // Time period for change
274 ... // 1 or more property changes per animation
280 ### Splines {#splines}
282 An animation property can be defined with a path and forward direction
283 instead of a single final value.
285 Paths are defined in a top level path section and referenced by the
290 "paths": // Path library
292 "path0": // Path definition by name
299 // curvature automatically creates
300 "curvature":0.35, // control-points
302 "control-points": [...] // Otherwise control-points can be
303 // directly specified.
314 "actor": "greeting2",
315 // Path is mandatory for spline
316 "path":"path0", // animation.
317 "forward":[1,0,0], // Forward vector specifies orientation
318 // whilst travelling along the path
319 "alpha-function": "EASE\_IN\_OUT", // (optional)
327 // Other properties changes can use
328 ] // paths or values in the same
334 ## Shaders {#shaders}
336 The shader section of the JSON file defines a library of shader effect
337 instances that are created on demand.
339 The shaders are referred to by name from the template, style, stage or
342 Multiple actors can set the same shader as the name refers to a single
345 Similarly one named shader instance can be set to several actors and can
346 be animated by one animation.
350 "shader-effects": // Shader Effect section
352 "myshader1": // Shader instance name
355 { // Prefixs are placed before DALi uniforms.
356 "vertexPrefix": "", // (Useful for \#defines.)
357 "vertex":"", // Glsl vertex program
358 "fragmentPrefix": "",
359 "fragment": "", // Glsl fragment program.
360 "geometry-type": "GEOMETRY_TYPE_IMAGE", // Geometry type(see DALi documentation)
362 "geometry-hints": "HINT_NONE": // Geometry hints (see DALi documentation)
363 "grid-density": 0, // Grid density(see DALi documentation)
366 "filename": "" // Effect image available as a second texture unit.
373 "type": "ImageActor",
374 "effect": "myshader1",
380 At least one of the vertex or fragment fields is mandatory. All
381 other fields are optional will use internal defaults.
383 Actors have an "effect" field that refers to the shader effect
384 instance to use with that actor.
386 ### Animating shaders {#animatingshaders}
388 Shader uniforms can be animated as if they are properties of the actor.
390 When the animation is created from code (or from a signal) the property
391 name search begins on the actor, if it isn't found the search continues
392 on the attached shader object.
394 The actor property names and shader uniform names must not clash for the
395 uniform to animate correctly. The convention in DALi is to prepend
400 "animations": \\ Animation library
402 "rotate": \\ An Animation named rotate
405 "properties": \\ Properties changed in this animation
408 "actor":"image", \\ Actor found by name from the stage
409 "property":"uTranslate", \\ Uniform name specified as if it is a
410 \\ property of the object.
421 \\ Shader program with uniform
422 "program": {...} \\ "uTranslate"
429 "effect": "myshader1" \\ Actor using shader effect instance
438 The stage section supports the immediate creation of actors at the time
441 The stage is a tree of actors that can be added to Dali's stage object.
444 builder = Dali.Builder();
445 json_text = load("layout.json");
446 builder.Load(json\_text);
447 stage = Dali.Stage.GetCurrent();
448 builder.AddActors( stage.GetRootLayer()); // Add actors to the stage root layer
453 "stage": \\ Stage Section Number
454 [ \\ An array of actors
456 "type": "ImageActor",
458 "actors": \\ Each actor can have children
463 \\ The Type to create; this can be a
464 ... \\ concrete Dali type (actor/control)
465 \\ or a template name.
466 "styles": ["base-style"]
467 \\ A list of styles to apply to the
475 # Actor and Control Properties {#actorprop}
477 Each control has a set of supported properties documented in the "Dali
478 UI Control Specification".
480 Please refer to the above document for further information about specific
483 @class ScriptJsonSpecification