Dali 3D User Interface Engine
script-json-specification

Table of Contents

DALi JSON Specification

Overview

This document describes the DALi JSON specification. The format is not yet formally versioned within the JSON.

General format

The JSON format supports

Concrete Actors and Controls can be created from types registered in the DALi Type Registry.

Template, style and scene sections all configure Actors and Controls via the DALi property system.

The JSON format deviates from the formal JSON specification and allows C style comments.

{ //
"version": 0, // Version Number
"includes": // Include section
[ //
"base-theme.json" // Include file to merge into the
// JSON
] //
"constants": // Constant replacement section
{ //
... //
}, //
"templates": // Template library section
{ //
"basic-text": // A named template
{ // } key value properties
... //
"actors": // A tree of sub actors
[ //
... //
] //
} //
}, //
"styles": // Named Style set section
{ //
"light-theme": // Style set name
{ //
... //
}, //
dark-theme": //
{ //
... //
}, //
} //
"stage": // Stage section
[ //
{ // Actors|Controls to create on JSON file load
"type": "basic-text", // A DALi Control or a template name
"styles":["base-theme","light-theme"] // Style list to apply to this instance
} //
] //
} //

Top level sections

Includes

The "includes" section is an array of filenames to be merged in order to create a final in memory JSON tree.

The merge process will walk key, value attributes from the root JSON node and overwrite previous values with the newer values.

The merge is relatively simple and is expected to be used to build up from base themes to custom themes where there are few conflicts and simple direct replacements are desired.

Constants

The merge behaviour when a file has constants and includes is

  1. Constants are loaded first
  2. Includes file list is merged in order
  3. All other (non constant) data is merged

The include merge is recursive, so step (2) above will cause the constants in the first included file to be merged first.

Constants

The constants section supports sub-string and full property replacement.

{
"constants": // Constant replacement section
{ //
"IMAGES": "/usr/share/images/", // Constants can be set here or in code.
"SIZE": [100,100,1] //
}, //
... //
{ //
"type":"ImageActor" // An DALi type or a template name
"image": //
{ //
"filename":"{IMAGES}b.jpg" // Image filename substring replacement
}, //
"size": "{SIZE}" //
} // Property replacement
} //

The type of the constant should match the expected type of the property.

A property constant cannot be used for sub string replacement; a string constant should be used.

With a property replacement, the replace site must contain a string where the first and last positions are braces.

Templates

The template section supports the creation of actor instances. The template name can be used in code to create an actor tree.

// JavaScript
var builder = new dali.Builder();
builder.loadFromFile( "my-app.json");
var userActorTree = builder.create( { template:"basic-text"} );
// C++
Builder builder = Builder::New();
std::string jsonData = loadFile("my-app.json");
builder.LoadFromString( jsonData );
actorTree = builder.Create("basic-text");

Templates consist of a name, multiple property-value configurations and an optional actor sub hierarchy.

{ //
"templates": // Template library section
{ //
"basic-text": // The template name
{ //
"type":"ImageActor", // Concrete DALi Type/Class to create
"styles":["base-style"], // Style list to apply
"name":"image", // }
"image": // } property name : value
{ // }
"filename":"{IMAGES}/b.jpg" //
}, //
"parentOrigin": "CENTER" //
... //
"actors": // A tree of sub actors
[ //
{ //
"type":"TextView" //
"name":"text", //
"text":"Hello World", //
"parentOrigin": "CENTER", //
} //
] //
} //
} //

A template has a special 'type' property which must contain a concrete DALi Actor or Control type name.

A template has a special 'styles' property which contains a list of styles to apply when creating using the template.

Styles

The styles section supports a named set of properties that can be applied to an actor or actor tree.

// C++
Builder.ApplyStyle("light-theme", myActor);
// JavaScript
builder.applyStyle("light-theme", myActor);

The styles can also be applied as an animation.

Builder.AnimateTo("light-theme", myActor, TimePeriod(0, 10));
{ //
"styles": // Style set section
{ //
"light-theme": // Style-set name
{ //
"color":[1,1,1,1] // }
"position":[0,-120,0], // } properties to set on the given actor
"rotation":[0,0,30], // }
"actors": //
{ // Sub Actors are referenced by name
"title-text": // Actor name to search for under given actor
{ //
"color":[1,1,1,1] // }
"position":[0,-120,0], // } properties to set if 'title-text' is found
"rotation":[0,0,30], // }
}
}, //
"icon": //
{ //
"color":[1,1,1,1] //
} //
}, //
"dark-theme": //
{ //
} //
} //

When applied to an actor tree the actors are referenced by name. Names are not unique in Dali.

When a style is applied in code DALi will perform a depth first search stopping with the first matching name.

Typically an application developer will apply the style to the template root actor and not the stage root actor. Therefore in most uses cases name conflicts are not expected.

Animations

The animation section defines a library of animation definitions.

The animations can be created by name from code.

They can also be created automatically from JSON in an actor signal.

{ //
"animations": // Animation library
{ //
"rotate": // An Animation named rotate
{ //
"duration": 10, // Duration in seconds
"loop": false, // Whether to loop.
"endAction": "Bake", // Whether to set final value(bake) or
// reset
"disconnectAction": "Discard", // Whether 'Bake' or 'Discard' when disconnected
"properties":
[
// Properties changed in this animation
{
"actor":"image", // Actor found by name from the stage
"property":"rotation", // Property to change
"value":[0, 0.1, 0, 0], // Value to set
"alphaFunction": "EASE\_IN\_OUT", // Interpolation function
//
"timePeriod": // Time period for change
{"delay": 0,
"duration": 3
}
},
... // 1 or more property changes per animation
}, //
... //
}, //

Splines

An animation property can be defined with a path and forward direction instead of a single final value.

Paths are defined in a top level path section and referenced by the animation property.

{ //
"paths": // Path library
{ //
"path0": // Path definition by name
{ //
"points":[ // points
[-150, -50, 0],
[0.0,70.0,0.0],
[190.0,-150.0,0.0]
],
// curvature automatically creates
"curvature":0.35, // controlPoints
//
"controlPoints": [...] // Otherwise controlPoints can be
// directly specified.
} //
}, //
"animations": //
{ //
"pathAnimation":
{
"duration": 3.0,
"properties":
[
{
"actor": "greeting2",
// Path is mandatory for spline
"path":"path0", // animation.
"forward":[1,0,0], // Forward vector specifies orientation
// whilst travelling along the path
"alphaFunction": "EASE\_IN\_OUT", // (optional)
"timePeriod":
{
"delay": 0,
"duration": 3
}
},
...
// Other properties changes can use
] // paths or values in the same
// animation.
}, //
} //

Shaders

The shader section of the JSON file defines a library of shader effect instances that are created on demand.

The shaders are referred to by name from the template, style, stage or animation sections.

Multiple actors can set the same shader as the name refers to a single instance.

Similarly one named shader instance can be set to several actors and can be animated by one animation.

{ //
"shaderEffects": // Shader Effect section
{ //
"myshader1": // Shader instance name
{ //
"program": //
{ // Prefixs are placed before DALi uniforms.
"vertexPrefix": "", // (Useful for \#defines.)
"vertex":"", // Glsl vertex program
"fragmentPrefix": "",
"fragment": "", // Glsl fragment program.
"geometryType": "GEOMETRY_TYPE_IMAGE", // Geometry type(see DALi documentation)
},
"geometryHints": "HINT_NONE": // Geometry hints (see DALi documentation)
"gridDensity": 0, // Grid density(see DALi documentation)
"image":
{
"filename": "" // Effect image available as a second texture unit.
}
},
...
},
"stage":
[{
"type": "ImageActor",
"effect": "myshader1",
...
}]
}

At least one of the vertex or fragment fields is mandatory. All other fields are optional will use internal defaults.

Actors have an "effect" field that refers to the shader effect instance to use with that actor.

Animating shaders

Shader uniforms can be animated as if they are properties of the actor.

When the animation is created from code (or from a signal) the property name search begins on the actor, if it isn't found the search continues on the attached shader object.

The actor property names and shader uniform names must not clash for the uniform to animate correctly. The convention in DALi is to prepend uniforms with 'u'.

{ \\
"animations": \\ Animation library
{ \\
"rotate": \\ An Animation named rotate
{ \\
"duration": 10, \\
"properties": \\ Properties changed in this animation
[ \\
{
"actor":"image", \\ Actor found by name from the stage
"property":"uTranslate", \\ Uniform name specified as if it is a
\\ property of the object.
"value":[10, 20],
...
},
...
]
},
"shaderEffects":
{
"myshader1":
{
\\ Shader program with uniform
"program": {...} \\ "uTranslate"
}
},
"actors":
[
{
"name": "image",
"effect": "myshader1" \\ Actor using shader effect instance
\\ "myshader1"
}
]
},

Stage

The stage section supports the immediate creation of actors at the time the JSON is loaded.

The stage is a tree of actors that can be added to Dali's stage object.

// C++
builder = Dali.Builder();
json_text = load("layout.json");
builder.Load(json\_text);
stage = Dali.Stage.GetCurrent();
builder.AddActors( stage.GetRootLayer()); // Add actors to the stage root layer
// JavaScript
builder.addActors( dali.stage.getRootLayer() );
{ \\
"stage": \\ Stage Section Number
[ \\ An array of actors
{
"type": "ImageActor",
...
"actors": \\ Each actor can have children
\\ creating a tree
[
{
"type": "TextView",
\\ The Type to create; this can be a
... \\ concrete DALi type (actor/control)
\\ or a template name.
"styles": ["base-style"]
\\ A list of styles to apply to the
} \\ created type.
]
}
]
}

Actor and Control Properties

Each control has a set of supported properties documented in the "Dali UI Control Specification".

Please refer to the above document for further information about specific controls.

Dali Docs Home
Read more about Dali