--- /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
+*/
projects / platform / core / uifw / dali-toolkit.git / commitdiff