Initial import of statemachine branch from the old kinetic repository

1 files changed, 198 insertions, 0 deletions

diff --git a/doc/src/examples/qtscriptcustomclass.qdoc b/doc/src/examples/qtscriptcustomclass.qdoc
new file mode 100644
index 0000000..f8d85a2
--- /dev/null
+++ b/doc/src/examples/qtscriptcustomclass.qdoc
@@ -0,0 +1,198 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Qt Software Information (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain
+** additional rights. These rights are described in the Nokia Qt LGPL
+** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at qt-sales@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \example script/customclass
+    \title Custom Script Class Example
+
+    The Custom Script Class example shows how to use QScriptClass and QScriptClassPropertyIterator
+    to implement a custom script class.
+
+    The script class we are going to implement is called \c{ByteArray}. It provides a wrapper around
+    the QByteArray class in Qt, with a simplified API. Why do we need such a class? Well, neither the
+    ECMAScript \c{Array} class or \c{String} class is appropriate to use when working with arrays of
+    bytes. Our \c{ByteArray} class will have the right semantics; objects will use only the amount of
+    memory that is really needed (a byte is stored as a byte, not as a floating-point number or a
+    Unicode character) and can be passed directly to C++ slots taking QByteArray arguments (no costly
+    conversion necessary).
+
+    \section1 ByteArray Class In Use
+
+    When the \c{ByteArray} class has been made available to the
+    scripting environment, \c{ByteArray} objects can be constructed like
+    so:
+
+    \snippet doc/src/snippets/code/doc_src_examples_qtscriptcustomclass.qdoc 0
+
+    \c{ByteArray} objects behave similar to normal \c{Array} objects. Every \c{ByteArray} object has
+    a \c{length} property, that holds the length of the array. If a new value is assigned to the \c{length}
+    property, the array is resized. If the array is enlarged, the new bytes are initialized to 0.
+    (This is a difference from normal \c{Array} objects; \c{ByteArray} objects are always dense arrays.)
+    Use normal array operations to read or write bytes in the array. The following code sets all the
+    bytes of an array to a certain value:
+
+    \snippet doc/src/snippets/code/doc_src_examples_qtscriptcustomclass.qdoc 1
+
+    When assigning a value to an array element, the value is truncated to eight bits:
+
+    \snippet doc/src/snippets/code/doc_src_examples_qtscriptcustomclass.qdoc 2
+
+    Like normal \c{Array} objects, if the array index is greater than the current length
+    of the array, the array is resized accordingly:
+
+    \snippet doc/src/snippets/code/doc_src_examples_qtscriptcustomclass.qdoc 3
+
+    Property names that aren't valid array indexes are treated
+    like normal object properties (again, the same is the case for normal \c{Array} objects);
+    in other words, it's perfectly fine to do something like this:
+
+    \snippet doc/src/snippets/code/doc_src_examples_qtscriptcustomclass.qdoc 4
+
+    The above assignment won't affect the contents of the array, but will rather assign a value
+    to the object property named "foo".
+
+    \c{ByteArray} objects have a set of methods: chop(), equals(), left(), mid(), toBase64() and so on.
+    These map directly onto the corresponding methods in QByteArray.
+
+    \snippet doc/src/snippets/code/doc_src_examples_qtscriptcustomclass.qdoc 5
+
+    \section1 ByteArray Class Implementation
+
+    To implement the \c{ByteArray} script class in C++, we create a subclass of QScriptClass,
+    called ByteArrayClass, and reimplement the virtual functions from QScriptClass. We also provide
+    a Qt Script constructor function suitable for being added to a QScriptEngine's environment.
+
+    The ByteArrayClass constructor prepares the script class:
+
+    \snippet examples/script/customclass/bytearrayclass.cpp 0
+
+    First, the constructor registers a pair of conversion functions, so that C++ QByteArray objects
+    and Qt Script \c{ByteArray} objects can move seamlessly between the C++ side and the script side.
+    For example, if a \c{ByteArray} object is passed to a C++ slot that takes a QByteArray
+    argument, the actual QByteArray that the \c{ByteArray} object wraps will be passed correctly.
+
+    Second, we store a handle to the string "length", so that we can quickly compare a given property name
+    to "length" later on.
+
+    Third, we initialize the standard \c{ByteArray} prototype, to be returned by our prototype()
+    reimplementation later on. (The implementation of the prototype is discussed later.)
+
+    Fourth, we initialize a constructor function for \c{ByteArray}, to be returned by the
+    constructor() function. We set the internal data of the constructor to be a pointer to
+    this ByteArrayClass object, so that the constructor, when it is invoked, can extract the
+    pointer and use it to create a new \c{ByteArray} object.
+
+    \snippet examples/script/customclass/bytearrayclass.cpp 1
+
+    The newInstance() function isn't part of the QScriptClass API; its purpose is to offer
+    a convenient way to construct a \c{ByteArray} object from an existing QByteArray. We store the
+    QByteArray as the internal data of the new object, and return the new object.
+    QScriptEngine::newObject() will call the prototype() function of our class, ensuring that
+    the prototype of the new object will be the standard \c{ByteArray} prototype.
+
+    \snippet examples/script/customclass/bytearrayclass.cpp 2
+
+    construct() is the native function that will act as a constructor for \c{ByteArray}
+    in scripts. We extract the pointer to the class, then call a newInstance() overload
+    that takes an initial size as argument, and return the new script object.
+
+    \snippet examples/script/customclass/bytearrayclass.cpp 3
+
+    queryProperty() is the function that Qt Script will call whenever someone tries to access
+    a property of a \c{ByteArray} object. We first get a pointer to the underlying QByteArray.
+    We check if the property being accessed is the special \c{length} property; if so, we
+    return, indicating that we will handle every kind of access to this property (e.g. both
+    read and write). Otherwise, we attempt to convert the property name to an array index. If
+    this fails, we return, indicating that we don't want to handle this property. Otherwise, we
+    have a valid array index, and store it in the \c{id} argument, so that we don't have to
+    recompute it in e.g. property() or setProperty(). If the index is greater than or equal to
+    the QByteArray's size, we indicate that we don't want to handle read access (but we still want
+    to handle writes, if requested).
+
+    \snippet examples/script/customclass/bytearrayclass.cpp 4
+
+    In the property() reimplementation, we do similar checks as in queryProperty() to find out
+    which property is being requested, and then return the value of that property.
+
+    \snippet examples/script/customclass/bytearrayclass.cpp 5
+
+    The setProperty() reimplementation has a structure that is similar to property(). If the \c{length} property
+    is being set, we resize the underlying QByteArray to the given length. Otherwise, we grab the
+    array index that was calculated in the queryProperty() function, enlarge the array if necessary,
+    and write the given value to the array.
+
+    \snippet examples/script/customclass/bytearrayclass.cpp 6
+
+    The propertyFlags() reimplementation specifies that the \c{length} property can't be deleted,
+    and that it is not enumerable. Array elements can't be deleted.
+
+    \snippet examples/script/customclass/bytearrayclass.cpp 7
+
+    We want the array elements to show up when a \c{ByteArray} object is used in for-in
+    statements and together with QScriptValueIterator. Therefore, we reimplement the
+    newIterator() function and have it return a new iterator for a given \c{ByteArray}.
+
+    \section1 ByteArray Iterator Implementation
+
+    \snippet examples/script/customclass/bytearrayclass.cpp 8
+
+    The \c{ByteArrayClassPropertyIterator} class is simple. It maintains an index into the
+    underlying QByteArray, and checks and updates the index in hasNext(), next() and so on.
+
+    \section1 ByteArray Prototype Implementation
+
+    The prototype class, ByteArrayPrototype, implements the \c{ByteArray} functions as slots.
+
+    \snippet examples/script/customclass/bytearrayprototype.h 0
+
+    There is a small helper function, thisByteArray(), that returns a pointer to the QByteArray
+    being operated upon:
+
+    \snippet examples/script/customclass/bytearrayprototype.cpp 0
+
+    The slots simply forward the calls to the QByteArray. Examples:
+
+    \snippet examples/script/customclass/bytearrayprototype.cpp 1
+
+    The remove() function is noteworthy; if we look at QByteArray::remove(), we see that it
+    should return a reference to the QByteArray itself (i.e. not a copy). To get the same
+    behavior in scripts, we return the script object (thisObject()).
+*/