Programming guide of DebugRenderer

[platform/core/uifw/dali-toolkit.git] / docs / content / shared-javascript-and-cpp-documentation / script-json-specification.md

<!--
/**-->

[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.

~~~{.js}
// JavaScript

var builder = new dali.Builder();
builder.loadFromFile( "my-app.json");
var userActorTree = builder.create( { template:"basic-text"} );
~~~

~~~{.cpp}
// 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.

~~~{.json}
   {                                    //
   "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 {#styles}

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

~~~{.cpp}
// C++

Builder.ApplyStyle("light-theme", myActor);
~~~

~~~{.js}
// JavaScript

builder.applyStyle("light-theme", myActor);
~~~


The styles can also be applied as an animation.

~~~{.cpp}
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.
     "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 {#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 {#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 {#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],
     ...
     },
     ...
     ]
     },
     "shaderEffects":
     {
     "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.

~~~
// 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
~~~

~~~{.js}
// 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 {#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 _Guide_JSON_Specification
*/