docs/content/shared-javascript-and-cpp-documentation/javascript-wrapping-guide.md

   1 /**
   2  *
   3 # JavaScript wrapping guide  {#javascriptwrapping}
   4
   5 This guide outlines what files to modify when the DALi C++ public API changes.
   6
   7 ## Background
   8
   9 We use Google's V8 to run JavaScript code.
  10 https://developers.google.com/v8/get_started
  11
  12 #### Folder structure
  13
  14 There is a folder for each type of wrapped object.
  15
  16
  17 The filename for a wrapped type are always object-wrapper.xxx
  18 The filename for the static functions that forward calls to DALi are always object-api.xxx
  19
  20 The current file / folder structure is as follows:
  21
  22 ![ ](../assets/img/javascript-wrapping-guide/folder-view.png)
  23 ![ ](folder-view.png)
  24
  25
  26 ## What to do when the DALi public API changes:
  27
  28 ### New property has been added
  29 - No code change required.
  30 - It will be automatically avalable using the dot notation. E.g. actor.my_new_property = true;
  31
  32 ### New property type has been added
  33 - modify property-value-wrapper.h / .cpp to support the new type
  34
  35 ### New function added to an object
  36 - Add the function name to function table in my-object-wrapper.cpp
  37 - Add the forwarding function to my-object-api.cpp/.h
  38 - Ensure you have created YUIDOC documention above the function
  39
  40 ![ ](../assets/img/javascript-wrapping-guide/adding-function.png)
  41 ![ ](adding-function.png)
  42
  43 ### New object added
  44
  45 This is an example of wrapping a new DALi C++ object called Light.
  46
  47 - in dali-wrapper.cpp in ConstructorFunctionTable insert the constructor in the table.
  48
  49 ![ ](../assets/img/javascript-wrapping-guide/constructors.png)
  50 ![ ](constructors.png)
  51
  52
  53 Objects registered in this table can be created in JavaScript as follows:
  54
  55 ~~~{.js}
  56 var light = new dali.Light();
  57 ~~~
  58
  59 - Add the Light to the Type enum in BaseWrappedObject class.
  60
  61 ![ ](../assets/img/javascript-wrapping-guide/base-wrapped-types.png)
  62 ![ ](base-wrapped-types.png)
  63
  64
  65 -  Create the light-wrapper / light-api files
  66
  67 If Light inherits from Handle then use path-wrapper and path-api as a template to create light-wrapper and light-api
  68 ( inherits from HandleWrapper)
  69
  70 Otherwise use animation-wrapper and animation-api as a template ( inherts from BaseWrappedObject)
  71
  72
  73
  74 ## Design
  75 ![ ](../assets/img/javascript-wrapping-guide/high-level-design.png)
  76 ![ ](high-level-design.png)
  77
  78
  79 ![ ](../assets/img/javascript-wrapping-guide/plugin-creation.png)
  80 ![ ](plugin-creation.png)
  81
  82
  83 ![ ](../assets/img/javascript-wrapping-guide/plugin-execution.png)
  84 ![ ](plugin-execution.png)
  85
  86 ### Internals
  87 In order to wrap DALi C++ objects in JavaScript, we use
  88 hidden fields inside the JavaScript object.
  89
  90
  91
  92 | JavaScript Object                     |   _   |  C++ WrappedObject  (e.g. ImageWrapper)|
  93 |---------------------------------------|-------|----------------------------------------|
  94 | Hidden internal fields                |       |                                        |
  95 | *Pointer to a     WrappedObject       | ----> |      Handle to a Dali::Image object    |
  96 | Type of wrapped object (e.g. Image)   |       |                                        |
  97
  98
  99 So if you call
 100 ~~~{.js}
 101 var name = myActor.getId();
 102 ~~~
 103 v8 will detect myActor is a wrapped object, and call getId() on that wrapped object.
 104 The wrapped object, then forwards the command to the real DALi object.
 105
 106 Whenever we want to access functions / properties of that wrapped object, we unwrap it
 107 to get access to the Dali object.
 108
 109 Each wrapped object registers with Dali garbage collector so they can be deleted
 110 when Dali shuts down
 111
 112 @class _Guide_JavaScript_Wrapping
 113 */