+++ /dev/null
-/**
- *
-[TOC]
-
-# DALi JSON Specification {#script-json-specification}
-
-## Overview {#overview}
-
-This document describes the Dali JSON specification.
-The format is not yet formally versioned within the JSON.
-
-# General format {#format}
-
-The JSON format supports
-
-- Named templates for on demand creation of
- - Actors/ Controls
- - Animations
-- Style sets
- - Dynamically change the style of Actor hierarchies
- - Animate to a style set
-- Includes
- - Build style sets up by merging JSON
-- Creating Scene content on load
- - Controls created without any code
-
-
-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 {#sections}
-
-## Includes {#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.
-
-- If the key does not exist then it will be created.
-- If the newer value is a different type then the newer type will persist.
-- Where both values are objects the merge will descend into the object.
-- Where both values are arrays the merge will replace the old array entirely.
-
-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 {#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 {#constantdetail}
-
-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 {#templates}
-
-The template section supports the creation of actor instances. The
-template name can be used in code to create an actor tree.
-
-~~~
-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" //
- }, //
- "parent-origin": "CENTER" //
- ... //
- "actors": // A tree of sub actors
- [ //
- { //
- "type":"TextView" //
- "name":"text", //
- "text":"Hello World", //
- "parent-origin": "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 {#styles}
-
-The styles section supports a named set of properties that can be
-applied to an actor or actor tree.
-
-~~~
-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 {#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.
- "end-action": "Bake", // Whether to set final value(bake) or
- // reset
- "disconnect-aciton": "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
- "alpha-function": "EASE\_IN\_OUT", // Interpolation function
- //
- "time-period": // Time period for change
- {"delay": 0,
- "duration": 3
- }
- },
- ... // 1 or more property changes per animation
- }, //
- ... //
- }, //
-~~~
-
-### Splines {#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, // control-points
- //
- "control-points": [...] // Otherwise control-points can be
- // directly specified.
- } //
- }, //
- "animations": //
- { //
- "path-animation":
- {
- "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
- "alpha-function": "EASE\_IN\_OUT", // (optional)
- "time-period":
- {
- "delay": 0,
- "duration": 3
- }
- },
- ...
- // Other properties changes can use
- ] // paths or values in the same
- // animation.
- }, //
- } //
-~~~~
-
-## Shaders {#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.
-
-~~~~
- { //
- "shader-effects": // 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.
- "geometry-type": "GEOMETRY_TYPE_IMAGE", // Geometry type(see DALi documentation)
- },
- "geometry-hints": "HINT_NONE": // Geometry hints (see DALi documentation)
- "grid-density": 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 {#animatingshaders}
-
-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],
- ...
- },
- ...
- ]
- },
- "shader-effects":
- {
- "myshader1":
- {
- \\ Shader program with uniform
- "program": {...} \\ "uTranslate"
- }
- },
- "actors":
- [
- {
- "name": "image",
- "effect": "myshader1" \\ Actor using shader effect instance
- \\ "myshader1"
- }
- ]
- },
-~~~~
-
-## Stage {#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.
-
-~~~
-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
-~~~
-
-~~~
- { \\
- "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 {#actorprop}
-
-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.
-
-@class ScriptJsonSpecification
-*/