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. The custom control is notified of a non animatable property value change.
  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  * // If the property is non animatable it calls OnPropertySet(Property::Value(2.0))
  55  * custom.alpha = 2.0;
  56  *
  57  * // NB: non animatable properties can be strings
  58  * custom.text = "a label";
  59  *
  60  * // Actions
  61  * // This line finds the action function registered as "SelectPage" and calls its with a list of arguments
  62  * // (NB: arguments are currently limited to non aggregate types ie no list, maps or objects)
  63  * custom.SelectPage("one");
  64  *
  65  * // Signals
  66  * // This line finds the signal registered as "touched" and sets the "OnTouch" callback function
  67  * custom.signals.touched = OnTouch;
  68  *
  69  * // OnTouch could have been previously defined as
  70  * function OnTouch(name)
  71  * {
  72  *   custom.text = name
  73  * }
  74  * @endcode
  75  *
  76  * <h1 class="pg">Supporting Layouts Using JSON</h1>
  77  *
  78  * The builder in Dali Toolkit provides a means to define layouts using the JSON file format.
  79  *
  80  * 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.
  81  *
  82  * *** Current Status
  83  *
  84  * Currently the builder supports internal Toolkit and Dali controls.
  85  *
  86  * *** Next Iteration
  87  *
  88  * The builder will be improved to make use of the TypeRegistry and non animatable properties and allow Custom Controls to be added into Scripting.
  89  *
  90  * 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)
  91  *
  92  * An actor tree defined in JSON will be retrievable as a "Buildable" class instance.
  93  *
  94  * 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).
  95  *
  96  * <h1 class="pg">Supporting A Javascript Runtime</h1>
  97  *
  98  * As a separate project an application will be available that can execute Javascript.
  99  *
 100  * This application will provide a wrapping layer between V8 and Dali and allow a natural interface to the Javascript developer.
 101  *
 102  *
 103  *
 104  *
 105  *
 106  *
 107  *
 108  *
 109  */