docs/content/shared-javascript-and-cpp-documentation/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 ~~~{.js}
 147 // JavaScript
 148
 149 var builder = new dali.Builder();
 150 builder.loadFromFile( "my-app.json");
 151 var userActorTree = builder.create( { template:"basic-text"} );
 152 ~~~
 153
 154 ~~~{.cpp}
 155 // C++
 156
 157 Builder builder = Builder::New();
 158 std::string jsonData = loadFile("my-app.json");
 159 builder.LoadFromString( jsonData );
 160
 161 actorTree = builder.Create("basic-text");
 162 ~~~
 163
 164 Templates consist of a name, multiple property-value configurations and
 165 an optional actor sub hierarchy.
 166
 167 ~~~{.json}
 168    {                                    //
 169    "templates":                         //  Template library section
 170    {                                    //
 171    "basic-text":                        //  The template name
 172    {                                    //
 173      "type":"ImageActor",               //  Concrete Dali Type/Class to create
 174      "styles":["base-style"],           //  Style list to apply
 175      "name":"image",                    //  }
 176      "image":                           //  } property name : value
 177      {                                  //  }
 178      "filename":"{IMAGES}/b.jpg"        //
 179      },                                 //
 180      "parent-origin": "CENTER"          //
 181      ...                                //
 182      "actors":                          //  A tree of sub actors
 183      [                                  //
 184      {                                  //
 185      "type":"TextView"                  //
 186      "name":"text",                     //
 187      "text":"Hello World",              //
 188      "parent-origin": "CENTER",         //
 189      }                                  //
 190      ]                                  //
 191    }                                    //
 192    }                                    //
 193 ~~~
 194
 195 A template has a special 'type' property which must contain a concrete
 196 Dali Actor or Control type name.
 197
 198 A template has a special 'styles' property which contains a list of
 199 styles to apply when creating using the template.
 200
 201 ## Styles {#styles}
 202
 203 The styles section supports a named set of properties that can be
 204 applied to an actor or actor tree.
 205
 206 ~~~{.cpp}
 207 // C++
 208
 209 Builder.ApplyStyle("light-theme", myActor);
 210 ~~~
 211
 212 ~~~{.js}
 213 // JavaScript
 214
 215 builder.applyStyle("light-theme", myActor);
 216 ~~~
 217
 218
 219 The styles can also be applied as an animation.
 220
 221 ~~~{.cpp}
 222 Builder.AnimateTo("light-theme", myActor, TimePeriod(0, 10));
 223 ~~~
 224
 225
 226
 227 ~~~
 228    {                                   //
 229    "styles":                           // Style set section
 230    {                                   //
 231    "light-theme":                      // Style-set name
 232    {                                   //
 233      "color":[1,1,1,1]                 // }
 234      "position":[0,-120,0],            // } properties to set on the given actor
 235      "rotation":[0,0,30],              // }
 236      "actors":                         //
 237      {                                 // Sub Actors are referenced by name
 238        "title-text":                   // Actor name to search for under given actor
 239        {                               //
 240          "color":[1,1,1,1]             // }
 241          "position":[0,-120,0],        // } properties to set if 'title-text' is found
 242          "rotation":[0,0,30],          // }
 243        }
 244      },                                //
 245      "icon":                           //
 246      {                                 //
 247        "color":[1,1,1,1]               //
 248      }                                 //
 249     },                                 //
 250     "dark-theme":                      //
 251     {                                  //
 252     }                                  //
 253    }                                   //
 254 ~~~
 255
 256 When applied to an actor tree the actors are referenced by name. Names
 257 are not unique in Dali.
 258
 259 When a style is applied in code Dali will perform a depth first search
 260 stopping with the first matching name.
 261
 262 Typically an application developer will apply the style to the template
 263 root actor and not the stage root actor. Therefore in most uses cases
 264 name conflicts are not expected.
 265
 266 ## Animations {#animations}
 267
 268 The animation section defines a library of animation definitions.
 269
 270 The animations can be created by name from code.
 271
 272 They can also be created automatically from JSON in an actor signal.
 273
 274 ~~~
 275     {                                    //
 276     "animations":                        // Animation library
 277     {                                    //
 278      "rotate":                           // An Animation named rotate
 279      {                                   //
 280      "duration": 10,                     // Duration in seconds
 281      "loop": false,                      // Whether to loop.
 282      "end-action": "Bake",               // Whether to set final value(bake) or
 283                                          // reset
 284      "disconnect-aciton": "Discard",     // Whether 'Bake' or 'Discard' when disconnected
 285      "properties":
 286      [
 287                                          // Properties changed in this animation
 288      {
 289      "actor":"image",                    // Actor found by name from the stage
 290      "property":"rotation",              // Property to change
 291      "value":[0, 0.1, 0, 0],             // Value to set
 292      "alpha-function": "EASE\_IN\_OUT",  // Interpolation function
 293                                          //
 294      "time-period":                      // Time period for change
 295      {"delay": 0,
 296       "duration": 3
 297       }
 298      },
 299      ...                                 // 1 or more property changes per animation
 300      },                                  //
 301      ...                                 //
 302     },                                   //
 303 ~~~
 304
 305 ### Splines {#splines}
 306
 307 An animation property can be defined with a path and forward direction
 308 instead of a single final value.
 309
 310 Paths are defined in a top level path section and referenced by the
 311 animation property.
 312
 313 ~~~
 314     {                                    //
 315     "paths":                             // Path library
 316      {                                   //
 317      "path0":                            // Path definition by name
 318      {                                   //
 319      "points":[                          // points
 320        [-150, -50, 0],
 321        [0.0,70.0,0.0],
 322        [190.0,-150.0,0.0]
 323       ],
 324                                          // curvature automatically creates
 325      "curvature":0.35,                   // control-points
 326                                          //
 327      "control-points": [...]             // Otherwise control-points can be
 328                                          // directly specified.
 329      }                                   //
 330      },                                  //
 331     "animations":                        //
 332     {                                    //
 333      "path-animation":
 334      {
 335      "duration": 3.0,
 336      "properties":
 337      [
 338      {
 339      "actor": "greeting2",
 340                                          // Path is mandatory for spline
 341      "path":"path0",                     // animation.
 342      "forward":[1,0,0],                  // Forward vector specifies orientation
 343                                          // whilst travelling along the path
 344      "alpha-function": "EASE\_IN\_OUT",  // (optional)
 345      "time-period":
 346      {
 347      "delay": 0,
 348      "duration": 3
 349      }
 350      },
 351      ...
 352                                          // Other properties changes can use
 353      ]                                   // paths or values in the same
 354                                          // animation.
 355     },                                   //
 356     }                                    //
 357 ~~~
 358
 359 ## Shaders {#shaders}
 360
 361 The shader section of the JSON file defines a library of shader effect
 362 instances that are created on demand.
 363
 364 The shaders are referred to by name from the template, style, stage or
 365 animation sections.
 366
 367 Multiple actors can set the same shader as the name refers to a single
 368 instance.
 369
 370 Similarly one named shader instance can be set to several actors and can
 371 be animated by one animation.
 372
 373 ~~~
 374     {                                             //
 375     "shader-effects":                             // Shader Effect section
 376     {                                             //
 377       "myshader1":                                // Shader  instance  name
 378       {                                           //
 379        "program":                                 //
 380        {                                          // Prefixs are placed before DALi uniforms.
 381          "vertexPrefix": "",                      // (Useful for \#defines.)
 382          "vertex":"",                             // Glsl vertex program
 383          "fragmentPrefix": "",
 384          "fragment": "",                          // Glsl fragment program.
 385          "geometry-type": "GEOMETRY_TYPE_IMAGE",  // Geometry type(see DALi documentation)
 386        },
 387        "geometry-hints": "HINT_NONE":             // Geometry hints (see DALi documentation)
 388        "grid-density": 0,                         // Grid density(see DALi documentation)
 389        "image":
 390        {
 391          "filename": ""                           // Effect image available as a second texture unit.
 392        }
 393      },
 394      ...
 395     },
 396     "stage":
 397     [{
 398      "type": "ImageActor",
 399      "effect": "myshader1",
 400      ...
 401     }]
 402     }
 403 ~~~
 404
 405 At least one of the vertex or fragment fields is mandatory. All
 406 other fields are optional will use internal defaults.
 407
 408 Actors have an "effect" field that refers to the shader effect
 409 instance to use with that actor.
 410
 411 ### Animating shaders {#animatingshaders}
 412
 413 Shader uniforms can be animated as if they are properties of the actor.
 414
 415 When the animation is created from code (or from a signal) the property
 416 name search begins on the actor, if it isn't found the search continues
 417 on the attached shader object.
 418
 419 The actor property names and shader uniform names must not clash for the
 420 uniform to animate correctly. The convention in DALi is to prepend
 421 uniforms with 'u'.
 422
 423 ~~~
 424     {                                    \\
 425     "animations":                        \\ Animation library
 426     {                                    \\
 427      "rotate":                           \\ An Animation named rotate
 428      {                                   \\
 429      "duration": 10,                     \\
 430      "properties":                       \\ Properties changed in this animation
 431      [                                   \\
 432      {
 433      "actor":"image",                    \\ Actor found by name from the stage
 434      "property":"uTranslate",            \\ Uniform name specified as if it is a
 435                                          \\ property of the object.
 436      "value":[10, 20],
 437      ...
 438      },
 439      ...
 440      ]
 441      },
 442      "shader-effects":
 443      {
 444      "myshader1":
 445      {
 446                                         \\ Shader program with uniform
 447      "program": {...}                   \\ "uTranslate"
 448      }
 449      },
 450      "actors":
 451      [
 452      {
 453      "name": "image",
 454      "effect": "myshader1"              \\ Actor using shader effect instance
 455                                         \\ "myshader1"
 456      }
 457      ]
 458     },
 459 ~~~
 460
 461 ## Stage {#stage}
 462
 463 The stage section supports the immediate creation of actors at the time
 464 the JSON is loaded.
 465
 466 The stage is a tree of actors that can be added to Dali's stage object.
 467
 468 ~~~
 469 // C++
 470 builder = Dali.Builder();
 471 json_text = load("layout.json");
 472 builder.Load(json\_text);
 473 stage = Dali.Stage.GetCurrent();
 474 builder.AddActors( stage.GetRootLayer()); // Add actors to the stage root layer
 475 ~~~
 476
 477 ~~~{.js}
 478 // JavaScript
 479
 480 builder.addActors( dali.stage.getRootLayer() );
 481 ~~~
 482
 483 ~~~
 484     {                                    \\
 485     "stage":                             \\  Stage Section Number
 486     [                                    \\  An array of actors
 487      {
 488      "type": "ImageActor",
 489      ...
 490      "actors":                           \\  Each actor can have children
 491                                          \\ creating a tree
 492      [
 493      {
 494      "type": "TextView",
 495                                          \\  The Type to create; this can be a
 496      ...                                 \\ concrete Dali type (actor/control)
 497                                          \\ or a template name.
 498      "styles": ["base-style"]
 499                                          \\  A list of styles to apply to the
 500      }                                   \\ created type.
 501      ]
 502      }
 503     ]
 504     }
 505 ~~~
 506
 507 # Actor and Control Properties {#actorprop}
 508
 509 Each control has a set of supported properties documented in the "Dali
 510 UI Control Specification".
 511
 512 Please refer to the above document for further information about specific
 513 controls.
 514
 515 @class _Guide_JSON_Specification
 516 */