docs/content/programming-guide/script-overview.h

   1 /*! \page script-overview Scripting Overview
   2  *
   3  * Dali has scripting support to
   4  *
   5  * <ul>
   6  *   <li>Provide a mechanism to allow custom controls in scripting.
   7  *   <li>Support layouts using JSON.
   8  *   <li>Support a dynamic Javascript runtime.
   9  * </ul>
  10  *
  11  * This is accessed via the Dali script external application which wraps Dali with a scripting engine. For example
  12  *
  13  * @code
  14  * daliscript hello-world.js
  15  * @endcode
  16  *
  17  * <h1 class="pg">A Mechanism To Allow Custom Controls in Scripting</h1>
  18  *
  19  * <h2 class="pg">The TypeRegistry</h2>
  20  *
  21  * The TypeRegistry allows class 'types' to register themselves as creatable from a scripting environment.
  22  *
  23  * Custom controls can register a creation function using class run time type information (RTTI).
  24  *
  25  * The RTTI typeid provides Dali with a unique name to register the type. In this registration the creation function is responsible for creating new instances of the custom class.
  26  *
  27  * Signals can be added to this type registration with a signal connection function.
  28  *
  29  * Actions can be similarly added with an action function.
  30  *
  31  *
  32  * <h2 class="pg">Non Animatable Properies</h2>
  33  *
  34  * The property system has non animatable properties that can be used by the scripting runtime to set actor attributes.
  35  *
  36  * Custom controls can register properties for scripting access.
  37  *
  38  *
  39  * <h2 class="pg">A Javascript example</h2>
  40  *
  41  * A Javascript runtime wrapping Dali and the V8 Javacript engine is being developed to allow the creation of pure Javascript applications.
  42  *
  43  * ie 'daliscript helloworld.js'.
  44  *
  45  * This example shows how a Javacript file relates to the TypeRegistry and Property system.
  46  *
  47  * @code
  48  * // Creation
  49  * // This line looks for a type registered as "MyActor" and calls its creation function
  50  * var custom = new MyActor();
  51  *
  52  * // Property access
  53  * // This line finds a property called "alpha" and Sets with SetProperty(index, Property::Value(2.0))
  54  * custom.alpha = 2.0;
  55  *
  56  * // NB: non animatable properties can be strings
  57  * custom.text = "a label";
  58  *
  59  * // Actions
  60  * // This line finds the action function registered as "SelectPage" and calls its with a list of arguments
  61  * // (NB: arguments are currently limited to non aggregate types ie no list, maps or objects)
  62  * custom.SelectPage("one");
  63  *
  64  * // Signals
  65  * // This line finds the signal registered as "touched" and sets the "OnTouch" callback function
  66  * custom.signals.touched = OnTouch;
  67  *
  68  * // OnTouch could have been previously defined as
  69  * function OnTouch(name)
  70  * {
  71  *   custom.text = name
  72  * }
  73  * @endcode
  74  *
  75  * <h1 class="pg">Supporting Layouts Using JSON</h1>
  76  *
  77  * The builder in Dali Toolkit provides a means to define layouts using the JSON file format.
  78  *
  79  * This format defines a text representation for key value pairs and lists of data. Lists and Maps can hold the fundamental Javascript data types of string, number(float/int), true, false, nil.
  80  *
  81  * *** Current Status
  82  *
  83  * Currently the builder supports internal Toolkit and Dali controls.
  84  *
  85  * *** Next Iteration
  86  *
  87  * The builder will be improved to make use of the TypeRegistry and non animatable properties and allow Custom Controls to be added into Scripting.
  88  *
  89  * This means the current JSON format will alter slightly (for example; properties will not be defined as a tree but as one level below the actor definition)
  90  *
  91  * An actor tree defined in JSON will be retrievable as a "Buildable" class instance.
  92  *
  93  * This buildable class allows the creation of the actor tree. It will also aid resource managment as a buildable can store the layout representation and unload resources when off stage (reconstructing the object when its added back onto the stage).
  94  *
  95  * <h1 class="pg">Supporting A Javascript Runtime</h1>
  96  *
  97  * As a separate project an application will be available that can execute Javascript.
  98  *
  99  * This application will provide a wrapping layer between V8 and Dali and allow a natural interface to the Javascript developer.
 100  *
 101  *
 102  *
 103  *
 104  *
 105  *
 106  *
 107  *
 108  */