docs/content/shared-javascript-and-cpp-documentation/script-json-specification.md

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