docs/content/programming-guide/script-json-specification.md

   1 /**
   2  *
   3 [TOC]
   4
   5 # DALi JSON Specification  {#script-json-specification}
   6
   7 ## Overview {#overview}
   8
   9 This document describes the Dali JSON specification.
  10 The format is not yet formally versioned within the JSON.
  11
  12 # General format {#format}
  13
  14 The JSON format supports
  15
  16 - Named templates for on demand creation of
  17  - Actors/ Controls
  18  - Animations
  19 - Style sets
  20  - Dynamically change the style of Actor hierarchies
  21  - Animate to a style set
  22 - Includes
  23  - Build style sets up by merging JSON
  24 - Creating Scene content on load
  25  - Controls created without any code
  26
  27
  28 Concrete Actors and Controls can be created from types registered in the
  29 Dali Type Registry.
  30
  31 Template, style and scene sections all configure Actors and Controls via
  32 the Dali property system.
  33
  34 The JSON format deviates from the formal JSON specification and allows C style comments.
  35
  36 ~~~
  37     {                                        //
  38       "version": 0,                          // Version Number
  39       "includes":                            // Include section
  40       [                                      //
  41        "base-theme.json"                     // Include file to merge into the
  42                                              // JSON
  43       ]                                      //
  44       "constants":                           // Constant replacement section
  45       {                                      //
  46         ...                                  //
  47       },                                     //
  48       "templates":                           // Template library section
  49       {                                      //
  50         "basic-text":                        // A named template
  51         {                                    // } key value properties
  52          ...                                 //
  53          "actors":                           // A tree of sub actors
  54          [                                   //
  55          ...                                 //
  56          ]                                   //
  57         }                                    //
  58         },                                   //
  59         "styles":                            // Named Style set section
  60         {                                    //
  61         "light-theme":                       // Style set name
  62         {                                    //
  63          ...                                 //
  64         },                                   //
  65         dark-theme":                         //
  66         {                                    //
  67          ...                                 //
  68         },                                   //
  69       }                                      //
  70       "stage":                               // Stage section
  71       [                                      //
  72        {                                     // Actors|Controls to create on JSON file load
  73        "type": "basic-text",                 // A Dali Control or a template name
  74        "styles":["base-theme","light-theme"] // Style list to apply to this instance
  75        }                                     //
  76       ]                                      //
  77     }                                        //
  78 ~~~
  79
  80 # Top level sections {#sections}
  81
  82 ## Includes {#includes}
  83
  84 The "includes" section is an array of filenames to be merged in order to
  85 create a final in memory JSON tree.
  86
  87 The merge process will walk key, value attributes from the root JSON
  88 node and overwrite previous values with the newer values.
  89
  90 - If the key does not exist then it will be created.
  91 - If the newer value is a different type then the newer type will persist.
  92 - Where both values are objects the merge will descend into the object.
  93 - Where both values are arrays the merge will replace the old array entirely.
  94
  95 The merge is relatively simple and is expected to be used to build up
  96 from base themes to custom themes where there are few conflicts and
  97 simple direct replacements are desired.
  98
  99 ### Constants {#constants}
 100
 101 The merge behaviour when a file has constants and includes is
 102
 103 1. Constants are loaded first
 104 2. Includes file list is merged in order
 105 3. All other (non constant) data is merged
 106
 107 The include merge is recursive, so step (2) above will cause the
 108 constants in the first included file to be merged first.
 109
 110 ## Constants {#constantdetail}
 111
 112 The constants section supports sub-string and full property replacement.
 113
 114 ~~~
 115     {
 116     "constants":                        // Constant replacement section
 117     {                                   //
 118       "IMAGES": "/usr/share/images/",   // Constants can be set here or in code.
 119       "SIZE": [100,100,1]               //
 120     },                                  //
 121     ...                                 //
 122     {                                   //
 123       "type":"ImageActor"               // An Dali type or a template name
 124       "image":                          //
 125       {                                 //
 126         "filename":"{IMAGES}b.jpg"      // Image filename substring replacement
 127       },                                //
 128       "size": "{SIZE}"                  //
 129     }                                   //  Property replacement
 130     }                                   //
 131 ~~~
 132
 133 The type of the constant should match the expected type of the property.
 134
 135 A property constant cannot be used for sub string replacement; a string
 136 constant should be used.
 137
 138 With a property replacement, the replace site must contain a string
 139 where the first and last positions are braces.
 140
 141 ## Templates {#templates}
 142
 143 The template section supports the creation of actor instances. The
 144 template name can be used in code to create an actor tree.
 145
 146 ~~~
 147 actorTree = builder.Create("basic-text");
 148 ~~~
 149
 150 Templates consist of a name, multiple property-value configurations and
 151 an optional actor sub hierarchy.
 152
 153 ~~~
 154    {                                    //
 155    "templates":                         //  Template library section
 156    {                                    //
 157    "basic-text":                        //  The template name
 158    {                                    //
 159      "type":"ImageActor",               //  Concrete Dali Type/Class to create
 160      "styles":["base-style"],           //  Style list to apply
 161      "name":"image",                    //  }
 162      "image":                           //  } property name : value
 163      {                                  //  }
 164      "filename":"{IMAGES}/b.jpg"        //
 165      },                                 //
 166      "parent-origin": "CENTER"          //
 167      ...                                //
 168      "actors":                          //  A tree of sub actors
 169      [                                  //
 170      {                                  //
 171      "type":"TextView"                  //
 172      "name":"text",                     //
 173      "text":"Hello World",              //
 174      "parent-origin": "CENTER",         //
 175      }                                  //
 176      ]                                  //
 177    }                                    //
 178    }                                    //
 179 ~~~
 180
 181 A template has a special 'type' property which must contain a concrete
 182 Dali Actor or Control type name.
 183
 184 A template has a special 'styles' property which contains a list of
 185 styles to apply when creating using the template.
 186
 187 ## Styles {#styles}
 188
 189 The styles section supports a named set of properties that can be
 190 applied to an actor or actor tree.
 191
 192 ~~~
 193 Builder.ApplyStyle("light-theme", myActor);
 194 ~~~
 195
 196 The styles can also be applied as an animation.
 197
 198 ~~~
 199 Builder.AnimateTo("light-theme", myActor, TimePeriod(0, 10));
 200 ~~~
 201
 202 ~~~
 203    {                                   //
 204    "styles":                           // Style set section
 205    {                                   //
 206    "light-theme":                      // Style-set name
 207    {                                   //
 208      "color":[1,1,1,1]                 // }
 209      "position":[0,-120,0],            // } properties to set on the given actor
 210      "rotation":[0,0,30],              // }
 211      "actors":                         //
 212      {                                 // Sub Actors are referenced by name
 213        "title-text":                   // Actor name to search for under given actor
 214        {                               //
 215          "color":[1,1,1,1]             // }
 216          "position":[0,-120,0],        // } properties to set if 'title-text' is found
 217          "rotation":[0,0,30],          // }
 218        }
 219      },                                //
 220      "icon":                           //
 221      {                                 //
 222        "color":[1,1,1,1]               //
 223      }                                 //
 224     },                                 //
 225     "dark-theme":                      //
 226     {                                  //
 227     }                                  //
 228    }                                   //
 229 ~~~
 230
 231 When applied to an actor tree the actors are referenced by name. Names
 232 are not unique in Dali.
 233
 234 When a style is applied in code Dali will perform a depth first search
 235 stopping with the first matching name.
 236
 237 Typically an application developer will apply the style to the template
 238 root actor and not the stage root actor. Therefore in most uses cases
 239 name conflicts are not expected.
 240
 241 ## Animations {#animations}
 242
 243 The animation section defines a library of animation definitions.
 244
 245 The animations can be created by name from code.
 246
 247 They can also be created automatically from JSON in an actor signal.
 248
 249 ~~~
 250     {                                    //
 251     "animations":                        // Animation library
 252     {                                    //
 253      "rotate":                           // An Animation named rotate
 254      {                                   //
 255      "duration": 10,                     // Duration in seconds
 256      "loop": false,                      // Whether to loop.
 257      "end-action": "Bake",               // Whether to set final value(bake) or
 258                                          // reset
 259      "disconnect-aciton": "Discard",     // Whether 'Bake' or 'Discard' when disconnected
 260      "properties":
 261      [
 262                                          // Properties changed in this animation
 263      {
 264      "actor":"image",                    // Actor found by name from the stage
 265      "property":"rotation",              // Property to change
 266      "value":[0, 0.1, 0, 0],             // Value to set
 267      "alpha-function": "EASE\_IN\_OUT",  // Interpolation function
 268                                          //
 269      "time-period":                      // Time period for change
 270      {"delay": 0,
 271       "duration": 3
 272       }
 273      },
 274      ...                                 // 1 or more property changes per animation
 275      },                                  //
 276      ...                                 //
 277     },                                   //
 278 ~~~
 279
 280 ### Splines {#splines}
 281
 282 An animation property can be defined with a path and forward direction
 283 instead of a single final value.
 284
 285 Paths are defined in a top level path section and referenced by the
 286 animation property.
 287
 288 ~~~~
 289     {                                    //
 290     "paths":                             // Path library
 291      {                                   //
 292      "path0":                            // Path definition by name
 293      {                                   //
 294      "points":[                          // points
 295        [-150, -50, 0],
 296        [0.0,70.0,0.0],
 297        [190.0,-150.0,0.0]
 298       ],
 299                                          // curvature automatically creates
 300      "curvature":0.35,                   // control-points
 301                                          //
 302      "control-points": [...]             // Otherwise control-points can be
 303                                          // directly specified.
 304      }                                   //
 305      },                                  //
 306     "animations":                        //
 307     {                                    //
 308      "path-animation":
 309      {
 310      "duration": 3.0,
 311      "properties":
 312      [
 313      {
 314      "actor": "greeting2",
 315                                          // Path is mandatory for spline
 316      "path":"path0",                     // animation.
 317      "forward":[1,0,0],                  // Forward vector specifies orientation
 318                                          // whilst travelling along the path
 319      "alpha-function": "EASE\_IN\_OUT",  // (optional)
 320      "time-period":
 321      {
 322      "delay": 0,
 323      "duration": 3
 324      }
 325      },
 326      ...
 327                                          // Other properties changes can use
 328      ]                                   // paths or values in the same
 329                                          // animation.
 330     },                                   //
 331     }                                    //
 332 ~~~~
 333
 334 ## Shaders {#shaders}
 335
 336 The shader section of the JSON file defines a library of shader effect
 337 instances that are created on demand.
 338
 339 The shaders are referred to by name from the template, style, stage or
 340 animation sections.
 341
 342 Multiple actors can set the same shader as the name refers to a single
 343 instance.
 344
 345 Similarly one named shader instance can be set to several actors and can
 346 be animated by one animation.
 347
 348 ~~~~
 349     {                                             //
 350     "shader-effects":                             // Shader Effect section
 351     {                                             //
 352       "myshader1":                                // Shader  instance  name
 353       {                                           //
 354        "program":                                 //
 355        {                                          // Prefixs are placed before DALi uniforms.
 356          "vertexPrefix": "",                      // (Useful for \#defines.)
 357          "vertex":"",                             // Glsl vertex program
 358          "fragmentPrefix": "",
 359          "fragment": "",                          // Glsl fragment program.
 360          "geometry-type": "GEOMETRY_TYPE_IMAGE",  // Geometry type(see DALi documentation)
 361        },
 362        "geometry-hints": "HINT_NONE":             // Geometry hints (see DALi documentation)
 363        "grid-density": 0,                         // Grid density(see DALi documentation)
 364        "image":
 365        {
 366          "filename": ""                           // Effect image available as a second texture unit.
 367        }
 368      },
 369      ...
 370     },
 371     "stage":
 372     [{
 373      "type": "ImageActor",
 374      "effect": "myshader1",
 375      ...
 376     }]
 377     }
 378 ~~~~
 379
 380 At least one of the vertex or fragment fields is mandatory. All
 381 other fields are optional will use internal defaults.
 382
 383 Actors have an "effect" field that refers to the shader effect
 384 instance to use with that actor.
 385
 386 ### Animating shaders {#animatingshaders}
 387
 388 Shader uniforms can be animated as if they are properties of the actor.
 389
 390 When the animation is created from code (or from a signal) the property
 391 name search begins on the actor, if it isn't found the search continues
 392 on the attached shader object.
 393
 394 The actor property names and shader uniform names must not clash for the
 395 uniform to animate correctly. The convention in DALi is to prepend
 396 uniforms with 'u'.
 397
 398 ~~~~
 399     {                                    \\
 400     "animations":                        \\ Animation library
 401     {                                    \\
 402      "rotate":                           \\ An Animation named rotate
 403      {                                   \\
 404      "duration": 10,                     \\
 405      "properties":                       \\ Properties changed in this animation
 406      [                                   \\
 407      {
 408      "actor":"image",                    \\ Actor found by name from the stage
 409      "property":"uTranslate",            \\ Uniform name specified as if it is a
 410                                          \\ property of the object.
 411      "value":[10, 20],
 412      ...
 413      },
 414      ...
 415      ]
 416      },
 417      "shader-effects":
 418      {
 419      "myshader1":
 420      {
 421                                         \\ Shader program with uniform
 422      "program": {...}                   \\ "uTranslate"
 423      }
 424      },
 425      "actors":
 426      [
 427      {
 428      "name": "image",
 429      "effect": "myshader1"              \\ Actor using shader effect instance
 430                                         \\ "myshader1"
 431      }
 432      ]
 433     },
 434 ~~~~
 435
 436 ## Stage {#stage}
 437
 438 The stage section supports the immediate creation of actors at the time
 439 the JSON is loaded.
 440
 441 The stage is a tree of actors that can be added to Dali's stage object.
 442
 443 ~~~
 444 builder = Dali.Builder();
 445 json_text = load("layout.json");
 446 builder.Load(json\_text);
 447 stage = Dali.Stage.GetCurrent();
 448 builder.AddActors( stage.GetRootLayer()); // Add actors to the stage root layer
 449 ~~~
 450
 451 ~~~
 452     {                                    \\
 453     "stage":                             \\  Stage Section Number
 454     [                                    \\  An array of actors
 455      {
 456      "type": "ImageActor",
 457      ...
 458      "actors":                           \\  Each actor can have children
 459                                          \\ creating a tree
 460      [
 461      {
 462      "type": "TextView",
 463                                          \\  The Type to create; this can be a
 464      ...                                 \\ concrete Dali type (actor/control)
 465                                          \\ or a template name.
 466      "styles": ["base-style"]
 467                                          \\  A list of styles to apply to the
 468      }                                   \\ created type.
 469      ]
 470      }
 471     ]
 472     }
 473 ~~~
 474
 475 # Actor and Control Properties {#actorprop}
 476
 477 Each control has a set of supported properties documented in the "Dali
 478 UI Control Specification".
 479
 480 Please refer to the above document for further information about specific
 481 controls.
 482
 483 @class ScriptJsonSpecification
 484 */