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
|
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en_US" lang="en_US">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- defaultprototypes.qdoc -->
<title>Qt 4.8: Default Prototypes Example</title>
<link rel="stylesheet" type="text/css" href="style/offline.css" />
</head>
<body>
<div class="header" id="qtdocheader">
<div class="content">
<a href="index.html" class="qtref"><span>Qt Reference Documentation</span></a>
</div>
<div class="breadcrumb toolblock">
<ul>
<li class="first"><a href="index.html">Home</a></li>
<!-- Breadcrumbs go here -->
<li><a href="all-examples.html">Examples</a></li>
<li>Default Prototypes Example</li>
</ul>
</div>
</div>
<div class="content mainContent">
<h1 class="title">Default Prototypes Example</h1>
<span class="subtitle"></span>
<!-- $$$script/defaultprototypes-description -->
<div class="descr"> <a name="details"></a>
<p>Files:</p>
<ul>
<li><a href="script-defaultprototypes-code-js.html">script/defaultprototypes/code.js</a></li>
<li><a href="script-defaultprototypes-prototypes-cpp.html">script/defaultprototypes/prototypes.cpp</a></li>
<li><a href="script-defaultprototypes-prototypes-h.html">script/defaultprototypes/prototypes.h</a></li>
<li><a href="script-defaultprototypes-main-cpp.html">script/defaultprototypes/main.cpp</a></li>
<li><a href="script-defaultprototypes-defaultprototypes-pro.html">script/defaultprototypes/defaultprototypes.pro</a></li>
<li><a href="script-defaultprototypes-defaultprototypes-qrc.html">script/defaultprototypes/defaultprototypes.qrc</a></li>
</ul>
<p>The Default Prototypes <a href="qtscript.html">QtScript</a> example shows how to use default prototypes to make a non-<a href="qobject.html">QObject</a>-based type scriptable.<p class="centerAlign"><img src="images/defaultprototypes-example.png" alt="" /></p><p>With <a href="qscriptengine.html#setDefaultPrototype">QScriptEngine::setDefaultPrototype</a>() you can specify a <a href="qtscript.html">QtScript</a> object that defines a scripting interface for a C++ type; Qt Script operations on values of such types will then be delegated to your prototype object. In this example, a simple scripting interface for <a href="qlistwidgetitem.html">QListWidgetItem</a> is defined, so that the text of items can easily be accessed from script code.</p>
<p>To define a scripting API for <a href="qlistwidgetitem.html">QListWidgetItem</a> in terms of Qt properties and slots, we subclass <a href="qobject.html">QObject</a> and <a href="qscriptable.html">QScriptable</a>.</p>
<pre class="cpp"> <span class="keyword">class</span> ListWidgetItemPrototype : <span class="keyword">public</span> <span class="type"><a href="qobject.html">QObject</a></span><span class="operator">,</span> <span class="keyword">public</span> <span class="type"><a href="qscriptable.html">QScriptable</a></span>
{
Q_OBJECT
Q_PROPERTY(<span class="type"><a href="qstring.html">QString</a></span> text READ text WRITE setText)
<span class="keyword">public</span>:
ListWidgetItemPrototype(<span class="type"><a href="qobject.html">QObject</a></span> <span class="operator">*</span>parent <span class="operator">=</span> <span class="number">0</span>);
<span class="type"><a href="qstring.html">QString</a></span> text() <span class="keyword">const</span>;
<span class="type">void</span> setText(<span class="keyword">const</span> <span class="type"><a href="qstring.html">QString</a></span> <span class="operator">&</span>text);
<span class="keyword">public</span> <span class="keyword">slots</span>:
<span class="type"><a href="qstring.html">QString</a></span> toString() <span class="keyword">const</span>;
};</pre>
<p>A single property, <tt>text</tt>, is defined, along with a slot, <tt>toString</tt>.</p>
<pre class="cpp"> ListWidgetItemPrototype<span class="operator">::</span>ListWidgetItemPrototype(<span class="type"><a href="qobject.html">QObject</a></span> <span class="operator">*</span>parent)
: <span class="type"><a href="qobject.html">QObject</a></span>(parent)
{
}
<span class="type"><a href="qstring.html">QString</a></span> ListWidgetItemPrototype<span class="operator">::</span>text() <span class="keyword">const</span>
{
<span class="type"><a href="qlistwidgetitem.html">QListWidgetItem</a></span> <span class="operator">*</span>item <span class="operator">=</span> qscriptvalue_cast<span class="operator"><</span><span class="type"><a href="qlistwidgetitem.html">QListWidgetItem</a></span><span class="operator">*</span><span class="operator">></span>(thisObject());
<span class="keyword">if</span> (item)
<span class="keyword">return</span> item<span class="operator">-</span><span class="operator">></span>text();
<span class="keyword">return</span> <span class="type"><a href="qstring.html">QString</a></span>();
}
<span class="type">void</span> ListWidgetItemPrototype<span class="operator">::</span>setText(<span class="keyword">const</span> <span class="type"><a href="qstring.html">QString</a></span> <span class="operator">&</span>text)
{
<span class="type"><a href="qlistwidgetitem.html">QListWidgetItem</a></span> <span class="operator">*</span>item <span class="operator">=</span> qscriptvalue_cast<span class="operator"><</span><span class="type"><a href="qlistwidgetitem.html">QListWidgetItem</a></span><span class="operator">*</span><span class="operator">></span>(thisObject());
<span class="keyword">if</span> (item)
item<span class="operator">-</span><span class="operator">></span>setText(text);
}
<span class="type"><a href="qstring.html">QString</a></span> ListWidgetItemPrototype<span class="operator">::</span>toString() <span class="keyword">const</span>
{
<span class="keyword">return</span> <span class="type"><a href="qstring.html">QString</a></span>(<span class="string">"ListWidgetItem(text = %0)"</span>)<span class="operator">.</span>arg(text());
}</pre>
<p>The implementation of the property accessors use the <a href="qscriptvalue.html#qscriptvalue_cast">qscriptvalue_cast</a>() function to cast the script object to a <a href="qlistwidgetitem.html">QListWidgetItem</a> pointer. The normal C++ <a href="qlistwidgetitem.html">QListWidgetItem</a> API is then used to implement the desired functionality.</p>
<p>Although not shown here, it is possible to throw a script exception from a prototype function; for example, you could throw a TypeError exception if the <a href="qscriptvalue.html#qscriptvalue_cast">qscriptvalue_cast</a>() fails.</p>
<p>QListWidgetItems are usually added to a <a href="qlistwidget.html">QListWidget</a>. While <a href="qlistwidget.html">QListWidget</a> is a <a href="qobject.html">QObject</a>-based class, not all the functionality needed for this example are present. We can solve this by creating a default prototype for the <a href="qlistwidget.html">QListWidget</a> class as well. The prototype will augment the functionality already provided by the Qt Script <a href="qobject.html">QObject</a> integration; i.e. if a property or slot is not found in the <a href="qlistwidget.html">QListWidget</a> object itself, the prototype will be used as a fallback.</p>
<pre class="cpp"> <span class="keyword">class</span> ListWidgetPrototype : <span class="keyword">public</span> <span class="type"><a href="qobject.html">QObject</a></span><span class="operator">,</span> <span class="keyword">public</span> <span class="type"><a href="qscriptable.html">QScriptable</a></span>
{
Q_OBJECT
<span class="keyword">public</span>:
ListWidgetPrototype(<span class="type"><a href="qobject.html">QObject</a></span> <span class="operator">*</span>parent <span class="operator">=</span> <span class="number">0</span>);
<span class="keyword">public</span> <span class="keyword">slots</span>:
<span class="type">void</span> addItem(<span class="keyword">const</span> <span class="type"><a href="qstring.html">QString</a></span> <span class="operator">&</span>text);
<span class="type">void</span> addItems(<span class="keyword">const</span> <span class="type"><a href="qstringlist.html">QStringList</a></span> <span class="operator">&</span>texts);
<span class="type">void</span> setBackgroundColor(<span class="keyword">const</span> <span class="type"><a href="qstring.html">QString</a></span> <span class="operator">&</span>colorName);
};</pre>
<p>The additional slots will make it possible to add items to a <a href="qlistwidget.html">QListWidget</a> from script code, and to set the background color of the widget from a string.</p>
<pre class="cpp"> ListWidgetPrototype<span class="operator">::</span>ListWidgetPrototype(<span class="type"><a href="qobject.html">QObject</a></span> <span class="operator">*</span>parent)
: <span class="type"><a href="qobject.html">QObject</a></span>(parent)
{
}
<span class="type">void</span> ListWidgetPrototype<span class="operator">::</span>addItem(<span class="keyword">const</span> <span class="type"><a href="qstring.html">QString</a></span> <span class="operator">&</span>text)
{
<span class="type"><a href="qlistwidget.html">QListWidget</a></span> <span class="operator">*</span>widget <span class="operator">=</span> qscriptvalue_cast<span class="operator"><</span><span class="type"><a href="qlistwidget.html">QListWidget</a></span><span class="operator">*</span><span class="operator">></span>(thisObject());
<span class="keyword">if</span> (widget)
widget<span class="operator">-</span><span class="operator">></span>addItem(text);
}
<span class="type">void</span> ListWidgetPrototype<span class="operator">::</span>addItems(<span class="keyword">const</span> <span class="type"><a href="qstringlist.html">QStringList</a></span> <span class="operator">&</span>texts)
{
<span class="type"><a href="qlistwidget.html">QListWidget</a></span> <span class="operator">*</span>widget <span class="operator">=</span> qscriptvalue_cast<span class="operator"><</span><span class="type"><a href="qlistwidget.html">QListWidget</a></span><span class="operator">*</span><span class="operator">></span>(thisObject());
<span class="keyword">if</span> (widget)
widget<span class="operator">-</span><span class="operator">></span>addItems(texts);
}
<span class="type">void</span> ListWidgetPrototype<span class="operator">::</span>setBackgroundColor(<span class="keyword">const</span> <span class="type"><a href="qstring.html">QString</a></span> <span class="operator">&</span>colorName)
{
<span class="type"><a href="qlistwidget.html">QListWidget</a></span> <span class="operator">*</span>widget <span class="operator">=</span> qscriptvalue_cast<span class="operator"><</span><span class="type"><a href="qlistwidget.html">QListWidget</a></span><span class="operator">*</span><span class="operator">></span>(thisObject());
<span class="keyword">if</span> (widget) {
<span class="preprocessor">#ifdef Q_WS_MAEMO_5</span>
<span class="type"><a href="qstring.html">QString</a></span> style <span class="operator">=</span> <span class="type"><a href="qstring.html">QString</a></span>(<span class="string">"QListWidget::item {background-color: %1;}"</span>)<span class="operator">.</span>arg(colorName);
style <span class="operator">+</span><span class="operator">=</span> <span class="string">"QListWidget::item {selection-color: black;}"</span>;
widget<span class="operator">-</span><span class="operator">></span>setStyleSheet(style);
<span class="preprocessor">#else</span>
<span class="type"><a href="qpalette.html">QPalette</a></span> palette <span class="operator">=</span> widget<span class="operator">-</span><span class="operator">></span>palette();
<span class="type"><a href="qcolor.html">QColor</a></span> color(colorName);
palette<span class="operator">.</span>setBrush(<span class="type"><a href="qpalette.html">QPalette</a></span><span class="operator">::</span>Base<span class="operator">,</span> color);
widget<span class="operator">-</span><span class="operator">></span>setPalette(palette);
<span class="preprocessor">#endif</span>
}
}</pre>
<p>Again, we use <a href="qscriptvalue.html#qscriptvalue_cast">qscriptvalue_cast</a>() to cast the script object to the relevant C++ type, in this case a <a href="qlistwidget.html">QListWidget</a> pointer. The addItem() and addItems() functions simply forward their arguments to the corresponding functions in the <a href="qlistwidget.html">QListWidget</a> class. setBackgroundColor() gets the widget's palette, creates a <a href="qcolor.html">QColor</a> from the given string argument and changes the palette accordingly.</p>
<pre class="cpp"> <a href="qmetatype.html#Q_DECLARE_METATYPE">Q_DECLARE_METATYPE</a>(<span class="type"><a href="qlistwidgetitem.html">QListWidgetItem</a></span><span class="operator">*</span>)
<a href="qmetatype.html#Q_DECLARE_METATYPE">Q_DECLARE_METATYPE</a>(<span class="type"><a href="qlistwidget.html">QListWidget</a></span><span class="operator">*</span>)</pre>
<p>The relevant C++ types must be made known to Qt's meta type system.</p>
<pre class="cpp"> <span class="type"><a href="qscriptengine.html">QScriptEngine</a></span> engine;
ListWidgetItemPrototype lwiProto;
engine<span class="operator">.</span>setDefaultPrototype(<a href="qmetatype.html#qMetaTypeId">qMetaTypeId</a><span class="operator"><</span><span class="type"><a href="qlistwidgetitem.html">QListWidgetItem</a></span><span class="operator">*</span><span class="operator">></span>()<span class="operator">,</span>
engine<span class="operator">.</span>newQObject(<span class="operator">&</span>lwiProto));
ListWidgetPrototype lwProto;
engine<span class="operator">.</span>setDefaultPrototype(<a href="qmetatype.html#qMetaTypeId">qMetaTypeId</a><span class="operator"><</span><span class="type"><a href="qlistwidget.html">QListWidget</a></span><span class="operator">*</span><span class="operator">></span>()<span class="operator">,</span>
engine<span class="operator">.</span>newQObject(<span class="operator">&</span>lwProto));</pre>
<p>For each type that we want to associate a prototype object with, we create an instance of the prototype class, pass it to <a href="qscriptengine.html#newQObject">QScriptEngine::newQObject</a>(), and then create the link between the C++ type and the resulting script object by calling <a href="qscriptengine.html#setDefaultPrototype">QScriptEngine::setDefaultPrototype</a>().</p>
<pre class="cpp"> <span class="type"><a href="qlistwidget.html">QListWidget</a></span> listWidget;
engine<span class="operator">.</span>globalObject()<span class="operator">.</span>setProperty(<span class="string">"listWidget"</span><span class="operator">,</span>
engine<span class="operator">.</span>newQObject(<span class="operator">&</span>listWidget));</pre>
<p>In this example, a single <a href="qlistwidget.html">QListWidget</a> object is added as a global script variable, called <tt>listWidget</tt>. Script code can add items to this widget by calling addItem() or addItems().</p>
<pre class="js"> <span class="name">listWidget</span>.<span class="name">addItem</span>(<span class="string">"Red"</span>);
<span class="name">listWidget</span>.<span class="name">addItem</span>(<span class="string">"Blue"</span>);
<span class="name">listWidget</span>.<span class="name">addItem</span>(<span class="string">"Green"</span>);
<span class="name">listWidget</span>.<span class="name">addItem</span>(<span class="string">"Cyan"</span>);
<span class="name">listWidget</span>.<span class="name">addItem</span>(<span class="string">"Yellow"</span>);
<span class="name">listWidget</span>.<span class="name">addItem</span>(<span class="string">"Purple"</span>);
<span class="name">listWidget</span>.<span class="name">addItems</span>([<span class="string">"Orange"</span>, <span class="string">"Gray"</span>]);</pre>
<p>Script code can connect to signals of the <a href="qlistwidget.html">QListWidget</a> object; signal handlers can use the interface defined in the <a href="qlistwidgetitem.html">QListWidgetItem</a> prototype to manipulate item arguments.</p>
<pre class="js"> <span class="name">listWidget</span>.<span class="name">currentItemChanged</span>.<span class="name">connect</span>(
<span class="keyword">function</span>(<span class="name">item</span>)
{
<span class="name">listWidget</span>.<span class="name">setBackgroundColor</span>(<span class="name">item</span>.<span class="name">text</span>);
}
);</pre>
<p>Not shown in this example is how to make <a href="qlistwidgetitem.html">QListWidgetItem</a> constructible from Qt Script code, i.e. to be able to write "new QListWidgetItem()" in a script. In order to do this, you have to define your own script constructor for the type. The constructor would just be a factory function that constructs a new C++ <a href="qlistwidgetitem.html">QListWidgetItem</a> and returns it back to the script. See <a href="qscriptengine.html#newFunction">QScriptEngine::newFunction</a>() for more information.</p>
</div>
<!-- @@@script/defaultprototypes -->
<div class="ft">
<span></span>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2012 Nokia Corporation and/or its
subsidiaries. Documentation contributions included herein are the copyrights of
their respective owners.</p>
<br />
<p>
The documentation provided herein is licensed under the terms of the
<a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation
License version 1.3</a> as published by the Free Software Foundation.</p>
<p>
Documentation sources may be obtained from <a href="http://www.qt-project.org">
www.qt-project.org</a>.</p>
<br />
<p>
Nokia, Qt and their respective logos are trademarks of Nokia Corporation
in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. <a title="Privacy Policy"
href="http://en.gitorious.org/privacy_policy/">Privacy Policy</a></p>
</div>
</body>
</html>
|
