Changes between Version 4 and Version 5 of QtScript

Timestamp:

Aug 17, 2010 5:54:42 AM (14 years ago)

Author:

kent.hansen@nokia.com

Comment:

--

QtScript

@@ -214 +214 @@
 
 The above algorithm doesn't consider the case where the QObject inherits QScriptable. In that case, an internal member must be set on the QScriptable before invoking the C++ method, so that the C++ method has access to the original JS environment of the call (see http://doc.trolltech.com/qscriptable.html).
+
+=== Value Conversion ===
+
+When interacting with Qt/C++ objects in JS, it will often be necessary to perform value conversion between the two worlds. For reading properties, QMetaProperty::read() returns a QVariant; this value must be converted to a JS value of a suitable type. For writing properties, QMetaProperty::write() takes a QVariant as argument; hence, the value passed from JS must first be converted to a QVariant of a suitable type. For calling slots, we may have to perform conversion both ways; converting arguments from JS to C++, and converting the slot's return value back to JS.
+
+The two "top-level" Qt/C++ <--> JS conversion functions are:
+
+   * '''qtVariantToJS(QVariant) : JSValue''': Converts a QVariant to a JS value.
+   * '''qtVariantFromJS(JSValue) : QVariant''': Converts a JSValue to a QVariant.
+
+A QVariant can contain a value of any type known to the Qt meta-type system; this includes both QMetaType's built-in types (bool, int, QString, etc.) and custom (user) types.
+
+A QVariant's meta-type can be obtained from QVariant::userType(). A void pointer to the value can be obtained from QVariant::constData(). For example, if the type is QMetaType::Double, it's safe to cast the data pointer to double*; if the type is QMetaType::QString, it's safe to cast the data pointer to QString*; and so on.
+
+Given a meta-type, storage for a value of that type can be allocated using the QMetaType(int type, const void *data) constructor.
+
+We introduce two helper functions to convert between (userType, data*) pairs and JS values:
+
+   * '''qtMetaTypeToJS(int, void*) : JSValue''': Converts a meta-type to a JS value.
+   * '''qtMetaTypeFromJS(JSValue, int, void*) : bool''': Converts a JSValue to a meta-type.
+
+These functions are essentially huge switches on the type argument, that cast the data pointer and get/set the value accordingly.
+
+Some non-primitive types have special handling:
+
+   * QDateTime: Converted from/to JS Date object.
+   * QRegExp: Converted from/to JS RegExp object.
+   * QStringList: Converted from/to JS Array object.
+   * QVariantList: Converted from/to JS Array object.
+   * QVariantMap: Converted from/to JS Object object.
+
+In many cases there is no "good" conversion between a C++ type and JS. For example, there's no obvious way to convert a QPixmap to a JS object. For types where no "standard" (read: automagic) conversion makes sense, including user types, QtScript falls back to creating a JS wrapper object that contains the QVariant.
+
+It's possible to override QtScript's conversion of any type by registering a pair of conversion functions for the type using qScriptRegisterMetaType().