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

   1 /**
   2  *
   3 # Scripting Overview  {#scriptoverview}
   4
   5 Dali has:
   6 - JSON to support:
   7  - layouting
   8  - theme / styling
   9  - templated actor/control creation
  10  - basic actions
  11  - DALi GUI builder generates JSON files. Allows UI designers to create / modify the application look and feel.
  12
  13 - JavaScript to support:
  14  - Rapid Application Development
  15  - Hybrid C++/JavaScript applications
  16  - Leaverage third party JavaScript modules (backbone.js etc)
  17
  18 JSON support is built in to DALi.
  19
  20 JavaScript support is via a plugin held in dali-toolkit, which builds automatically if Google's V8 engine is installed.
  21 The V8 version required by DALi can be built and installed using dali-core/scripts/dali_env script.
  22
  23 Files can be loaded inside any DALi application, or from command line using the launcher ( part of dali-demo).
  24
  25 ~~~{.cpp}
  26 scripting.example hello-world.json hello-world.js
  27 ~~~
  28
  29 We currently have JSON and JavaScript example files held in dali-demo/resources/scripts
  30
  31 ![ ](../assets/img/javascript-wrapping-guide/scripting-overview.png)
  32 ![ ](scripting-overview.png)
  33
  34 # JSON
  35
  36 JSON file contains different sections:
  37 - **Templates** actor & control tree creation
  38 - **Styles** used to style actor & control trees
  39 - **Animations**
  40 - **Instances** of objects for path, shader-effects, render-tasks, frame-buffers
  41 - **Stage**. A list of actors / controls that can be added to the stage
  42 - **Constants**  (e.g. positions / colors, that can be references by other parts of the JSON file);
  43 - **Actions**
  44
  45 ## Examples
  46
  47 ### JSON templates section
  48
  49 ~~~{.json}
  50
  51     “templates”:
  52     {
  53       "name":"users",
  54       "type":"Actor",
  55       "parent-origin":"TOP_CENTER",
  56       "anchor-point":"TOP_CENTER",
  57       "size":"{DEFAULT_MENU_USER_SIZE}",
  58       "color-mode":"USE_OWN_COLOR",
  59       "actors":
  60       [
  61         {
  62           "name":"usersBackground",
  63           "type":"ImageActor",
  64           "parent-origin":"CENTER",
  65           "anchor-point":"CENTER",
  66           "size":"{DEFAULT_MENU_USER_SIZE}",
  67           "color-mode":"USE_OWN_COLOR",
  68           "image":{ "filename":"{IMAGE_PATH}white-pixel.png" },
  69           "color":"{DEFAULT_MENU_BACKGROUND_COLOR}"
  70         },
  71         {
  72           "name":"icon",
  73           "type":"ImageActor",
  74           "parent-origin":"TOP_CENTER",
  75           "anchor-point":"TOP_CENTER",
  76           "position":[0,41,1],
  77           "image":{ "filename":"{IMAGE_PATH}ico_man_nor.png" }
  78         },
  79       ]
  80     },
  81
  82
  83 ~~~
  84
  85 #### JavaScript example
  86
  87 ~~~{.js}
  88
  89 var builder = new dali.Builder();
  90
  91 builder.loadFromFile( "my-app.json");
  92
  93 var userActorTree = builder.create( { template:"users"} );
  94
  95 ~~~
  96
  97 #### C++ example
  98
  99 ~~~{.cpp}
 100 Builder builder = Builder::New();
 101
 102 std::string jsonData = loadFile("my-app.json");
 103
 104 builder.LoadFromString( jsonData );
 105
 106 Actor userActorTree = builder.Create("users");
 107 ~~~
 108
 109
 110 ### JSON styles section
 111
 112 ~~~{.json}
 113 “styles”:
 114   {
 115     “live-tv-focus":
 116     {
 117       "actors":
 118       {
 119         "background":
 120         {
 121           "image":{ "filename":"{IMAGE_PATH}live_tv_background.png" },
 122           "color":"{DEFAULT_MENU_ITEM_COLOR_1}"
 123         },
 124         "icon":
 125         {
 126           "image":{ "filename":"{IMAGE_PATH}icn_live_tv_foc.png" }
 127         },
 128         "label":
 129         {
 130           "color-alpha":1,
 131           "text":"<font size='20' weight='bold'><b>LIVE</b></font>"
 132         }
 133       }
 134     },
 135   }
 136 ~~~
 137
 138 #### JavaScript example
 139
 140 ~~~{.js}
 141 builder.applyStyle( "live-tv-focus", tvIcon );
 142 ~~~
 143
 144 #### C++ example
 145
 146 ~~~{.cpp}
 147 builder.ApplyStyle( "live-tv-focus", tvIcon );
 148 ~~~
 149
 150 ### JSON animations section
 151
 152 ~~~{.json}
 153 "animations":
 154   {
 155     "animate-show":
 156     {
 157       "duration":0.5,
 158       "properties":
 159       [
 160         {
 161           "actor":"background",
 162           "property":"position-x",
 163           "value":30,
 164           "alpha-function":"EASE_IN_OUT"
 165         },
 166         {
 167           "actor":"itemsBackground",
 168           "property":"color-alpha",
 169           "value":0.85,
 170           "time-period": {"delay": 0.25, "duration": 0.25 },
 171           "alpha-function":"EASE_IN_OUT"
 172         },
 173         {
 174           "actor":"usersBackground",
 175           "property":"color-alpha",
 176           "value":0.85,
 177           "time-period": {"delay": 0.25, "duration": 0.25 },
 178           "alpha-function":"EASE_IN_OUT"
 179         }
 180       ]
 181     },
 182 ~~~
 183
 184 #### JavaScript example
 185
 186 ~~~{.js}
 187 // JavaScript
 188
 189 var anim = builder.createAnimation( { animation:"animate-show", actor: myActor } );
 190 ~~~
 191
 192 ~~~{.cpp}
 193 // C+++
 194
 195 Animation anim = builder.createAnimation( "animate-show", propertyMap );
 196 ~~~
 197
 198 ### JSON stage section
 199
 200 ~~~{.json}
 201
 202 “stage": [{
 203       "name":"simple-table",
 204       "type":"TableView",
 205       "background-color": [0.5,0.5,0,1],
 206       "parent-origin": "CENTER",
 207       "size":[400,500,1],
 208       "rows": 4,
 209       "columns":4,
 210       "cell-padding": [10, 5],
 211       "layout-animation-duration": 0.5,
 212       "layout-rows": {  // set the height of the rows
 213         "0": { "policy": "fixed", "value": 40 },
 214         "1": { "policy": "relative", "value": 0.33 },
 215         "2": { "policy": "fixed", "value": 120 }
 216       },
 217       "layout-columns": { // set the widths of the columns
 218         "1": { "policy": "fixed", "value": 150 },
 219         "2": { "policy": "relative", "value": 0.35 },
 220         "3": { "policy": "relative", "value": 0.15 }
 221       },
 222       "actors": [{
 223           "name":"gallery-1",
 224           "type":"ImageActor",
 225           "image": {
 226             "filename": "{DALI_IMAGE_DIR}gallery-large-1.jpg"
 227           },
 228           "custom-properties": { // properties registered dynamically
 229             "cell-indices": [0,0],// property to specify the top-left cell this child occupies
 230             "row-span":4, // property to specify how many rows this child occupies, if not set, default value is 1
 231             "column-spam":1 // property to specify how many columns this child occupies
 232             ....
 233 ~~~
 234
 235 #### JavaScript example
 236
 237 ~~~{.js}
 238 // add all actors under stage section to the root layer
 239 builder.addActors( dali.stage.getRootLayer() );
 240 ~~~
 241
 242 #### C++ example
 243
 244 ~~~{.cpp}
 245 // add all actors under stage section to the root layer
 246 builder.AddActors( Stage::GetCurrent().GetRootLayer() );
 247 ~~~
 248
 249 # JavaScript
 250
 251 For the JavaScript API please build dali-toolkit with YUIDOC installed. This will generate the documentation.
 252 See dali-toolkit/plugins/dali-script-v8/docs/README.txt
 253
 254 To execute JavaScript from C++
 255
 256 ~~~{.cpp}
 257 script = Toolkit::Script::New();
 258
 259 script.ExecuteFile( scriptFileName );
 260 ~~~
 261
 262 @class _Guide_JSON_and_JavaScript_overview
 263
 264 */