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