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

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