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 filenames 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 var builder = new dali.Builder();
151 builder.loadFromFile( "my-app.json");
152 var userActorTree = builder.create( { template:"basic-text"} );
158 Builder builder = Builder::New();
159 std::string jsonData = loadFile("my-app.json");
160 builder.LoadFromString( jsonData );
162 actorTree = builder.Create("basic-text");
165 Templates consist of a name, multiple property-value configurations and
166 an optional actor sub hierarchy.
170 "templates": // Template library section
172 "basic-text": // The template name
174 "type":"ImageView", // Concrete DALi Type/Class to create
175 "styles":["base-style"], // Style list to apply
177 "image": // } property name : value
179 "url":"{IMAGES}/b.jpg" //
181 "parentOrigin": "CENTER" //
183 "actors": // A tree of sub actors
188 "text":"Hello World", //
189 "parentOrigin": "CENTER", //
196 A template has a special 'type' property which must contain a concrete
197 DALi Actor or Control type name.
199 A template has a special 'styles' property which contains a list of
200 styles to apply when creating using the template.
204 The styles section supports a named set of properties that can be
205 applied to an actor or actor tree.
210 Builder.ApplyStyle("light-theme", myActor);
216 builder.applyStyle("light-theme", myActor);
220 The styles can also be applied as an animation.
223 Builder.AnimateTo("light-theme", myActor, TimePeriod(0, 10));
230 "styles": // Style set section
232 "light-theme": // Style-set name
234 "color":[1,1,1,1] // }
235 "position":[0,-120,0], // } properties to set on the given actor
236 "rotation":[0,0,30], // }
238 { // Sub Actors are referenced by name
239 "title-text": // Actor name to search for under given actor
241 "color":[1,1,1,1] // }
242 "position":[0,-120,0], // } properties to set if 'title-text' is found
243 "rotation":[0,0,30], // }
257 When applied to an actor tree the actors are referenced by name. Names
258 are not unique in Dali.
260 When a style is applied in code DALi will perform a depth first search
261 stopping with the first matching name.
263 Typically an application developer will apply the style to the template
264 root actor and not the stage root actor. Therefore in most uses cases
265 name conflicts are not expected.
267 ## Animations {#animations}
269 The animation section defines a library of animation definitions.
271 The animations can be created by name from code.
273 They can also be created automatically from JSON in an actor signal.
277 "animations": // Animation library
279 "rotate": // An Animation named rotate
281 "duration": 10, // Duration in seconds
282 "loop": false, // Whether to loop.
283 "endAction": "Bake", // Whether to set final value(bake) or
285 "disconnectAction": "Discard", // Whether 'Bake' or 'Discard' when disconnected
288 // Properties changed in this animation
290 "actor":"image", // Actor found by name from the stage
291 "property":"rotation", // Property to change
292 "value":[0, 0.1, 0, 0], // Value to set
293 "alphaFunction": "EASE\_IN\_OUT", // Interpolation function
295 "timePeriod": // Time period for change
300 ... // 1 or more property changes per animation
306 ### Splines {#splines}
308 An animation property can be defined with a path and forward direction
309 instead of a single final value.
311 Paths are defined in a top level path section and referenced by the
316 "paths": // Path library
318 "path0": // Path definition by name
325 // curvature automatically creates
326 "curvature":0.35, // controlPoints
328 "controlPoints": [...] // Otherwise controlPoints can be
329 // directly specified.
340 "actor": "greeting2",
341 // Path is mandatory for spline
342 "path":"path0", // animation.
343 "forward":[1,0,0], // Forward vector specifies orientation
344 // whilst travelling along the path
345 "alphaFunction": "EASE\_IN\_OUT", // (optional)
353 // Other properties changes can use
354 ] // paths or values in the same
360 At least one of the vertex or fragment fields is mandatory. All
361 other fields are optional will use internal defaults.
363 Actors have an "effect" field that refers to the shader effect
364 instance to use with that actor.
366 ### Animating shaders {#animatingshaders}
368 Shader uniforms can be animated as if they are properties of the actor.
370 When the animation is created from code (or from a signal) the property
371 name search begins on the actor, if it isn't found the search continues
372 on the attached shader object.
374 The actor property names and shader uniform names must not clash for the
375 uniform to animate correctly. The convention in DALi is to prepend
380 "animations": \\ Animation library
382 "rotate": \\ An Animation named rotate
385 "properties": \\ Properties changed in this animation
388 "actor":"image", \\ Actor found by name from the stage
389 "property":"uTranslate", \\ Uniform name specified as if it is a
390 \\ property of the object.
401 \\ Shader program with uniform
402 "program": {...} \\ "uTranslate"
409 "effect": "myshader1" \\ Actor using shader effect instance
418 The stage section supports the immediate creation of actors at the time
421 The stage is a tree of actors that can be added to Dali's stage object.
425 builder = Dali.Builder();
426 json_text = load("layout.json");
427 builder.Load(json\_text);
428 stage = Dali.Stage.GetCurrent();
429 builder.AddActors( stage.GetRootLayer()); // Add actors to the stage root layer
435 builder.addActors( dali.stage.getRootLayer() );
440 "stage": \\ Stage Section Number
441 [ \\ An array of actors
445 "actors": \\ Each actor can have children
450 \\ The Type to create; this can be a
451 ... \\ concrete DALi type (actor/control)
452 \\ or a template name.
453 "styles": ["base-style"]
454 \\ A list of styles to apply to the
462 # Actor and Control Properties {#actorprop}
464 Each control has a set of supported properties documented in the "Dali
465 UI Control Specification".
467 Please refer to the above document for further information about specific
470 @class _Guide_JSON_Specification