1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
|
/****************************************************************************
**
** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Digia. For licensing terms and
** conditions see http://qt.digia.com/licensing. For further information
** use the contact form at http://qt.digia.com/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\example script/customclass
\title Custom Script Class Example
\brief 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.cpp 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.cpp 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.cpp 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.cpp 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.cpp 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.cpp 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 10
\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.
QScriptEngine::reportAdditionalMemoryCost() is called to inform the script engine of the
memory occupied by the QByteArray. This gives the garbage collector a hint that it should
perhaps trigger more frequently, possibly freeing up memory associated with large ByteArray
objects that are no longer in use.
\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 9
The resize() function is a helper function that resizes the QByteArray to a new size, and,
if the new size is greater than the old, reports the additional memory cost to the script
engine.
\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()).
*/
|
