ground/gcs/src/shared/scriptwrapper/README

   1 Some wrap helpers for Script support.
   2
   3 How to wrap an interface:
   4 =========================
   5
   6 1) Prototypes (preferred)
   7 -------------------------
   8
   9 - Interface must inherit QObjectInterface and be qvariant-castable, that is,
  10   declared as Q-MetaType.
  11
  12 - Register a prototype with the engine for each interface:
  13   - Provide an informative toString()-slot.
  14   - Use properties and slots for everything, can be non-void as well
  15   - Accessors to interfaces should be properties.
  16
  17 - In the toScriptValue() function passed on to qScriptRegisterMetaType, create
  18   an newQObject on the QObject obtained from the QObjectInterface and assign it the prototype
  19   registered for the interface (obtained  from the engine) using QScriptValue::setDefaultPrototype
  20   The prototype can then qobject (-extension)-cast to the interface as each
  21   implementing class returns 'this' as qObject() of QObjectInterface.
  22
  23 - If sequences of the  interface are used, declare them as Q-MetaType
  24   and do qScriptRegisterSequenceMetaType().
  25
  26 The template  registerQObjectInterface does the magic.
  27
  28 2) Manually bless a script value with properties
  29 ------------------------------------------------
  30
  31 Typically, a qobject-derived wrapper will be used
  32 that provides an accessor to the wrapped class.
  33 The wrapper contains a QScriptValue 'm_self' which
  34 typically is initialized using:
  35
  36 - engine.newQObject(this, QScriptEngine::ScriptOwnership))
  37   for interfaces that are always present.
  38
  39 - m_self(engine.newQObject(this, QScriptEngine::QtOwnership)),
  40   can be used when setting the qObject() of an QObjectInterface
  41   as parent of the qobject-derived wrapper. If the QObject goes
  42   out of scope while running the script, the script object
  43   will stop working.
  44
  45 A conversion cast to QScriptValue can then be provided.
  46
  47 How to wrap functions:
  48
  49 Most functions can then be implemented as slots, property-like
  50 things as such.
  51
  52 The other functions have to be implemented via script-callbacks.
  53 (Parameter checking required).
  54
  55 The templates in here can help in writing the wrapper
  56 objects. For examples, see
  57
  58 src/plugins/core/scriptmanager/qworkbench_wrapper.h