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
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
|
/****************************************************************************
**
** 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$
**
****************************************************************************/
/*!
\page qmlglobalobject.html
\title QML Global Object
Contains all the properties of the ECMAScript global object, plus:
\list
\o Qt
\o createQmlObject
\o createComponent
\o XMLHttpRequest
\o openDatabase
\endlist
Contents:
\tableofcontents
\section1 Qt Object
The Qt object provides useful enums and functions from Qt, for use in all QML
files.
\section2 Enums
The Qt object contains all enums in the Qt namespace. For example, you can
access the AlignLeft member of the Qt::AlignmentFlag enum with \c Qt.AlignLeft.
For a full list of enums, see the Qt Namespace documentation.
\section2 Types
The Qt object also contains helper functions for creating objects of specific
data types. This is primarily useful when setting the properties of an item
when the property has one of the following types:
\list
\o Color
\o Rect
\o Point
\o Size
\o Vector3D
\endlist
There are also string based constructors for these types, see \l{basicqmltypes.html}{Qml Types}.
\section3 Qt.rgba(int red, int green, int blue, int alpha)
This function returns a Color with the specified \c red, \c green, \c blue and \c alpha components. All components should be in the range 0-255 inclusive.
\section3 Qt.hsla(int hue, int saturation, int lightness, int alpha)
This function returns a Color with the specified \c hue, \c saturation, \c lightness and \c alpha components. All components should be in the range 0-255 inclusive.
\section3 Qt.rect(int x, int y, int width, int height)
This function returns a Rect with the top-left corner at \c x,\c y and the specified \c width and \c height.
\section3 Qt.point(int x, int y)
This function returns a Point with the specified \c x and \c y coordinates.
\section3 Qt.size(int width, int height)
returns as Size with the specified width and height.
\section3 Qt.vector(real x, real y, real z)
This function is intended for use inside QML only. In C++ just create a
QVector3D as usual.
This function takes three numeric components and combines them into a
QVector3D value that can be used with any property that takes a
QVector3D argument. The following QML code:
\code
transform: Rotation {
id: rotation
origin.x: Container.width / 2;
axis: vector(0, 1, 1)
}
\endcode
is equivalent to:
\code
transform: Rotation {
id: rotation
origin.x: Container.width / 2;
axis.x: 0; axis.y: 1; axis.z: 0
}
\endcode
\section2 Functions
The Qt object also contains the following miscellaneous functions which expose Qt functionality for use in QML.
\section3 Qt.lighter(color baseColor)
This function returns a color 50% lighter than \c baseColor. See QColor::lighter() for further details.
\section3 Qt.darker(color baseColor)
This function returns a color 50% darker than \c baseColor. See QColor::lighter() for further details.
\section3 Qt.tint(color baseColor, color tintColor)
This function allows tinting one color with another.
The tint color should usually be mostly transparent, or you will not be able to see the underlying color. The below example provides a slight red tint by having the tint color be pure red which is only 1/16th opaque.
\qml
Rectangle { x: 0; width: 80; height: 80; color: "lightsteelblue" }
Rectangle { x: 100; width: 80; height: 80; color: Qt.tint("lightsteelblue", "#10FF0000") }
\endqml
\image declarative-rect_tint.png
Tint is most useful when a subtle change is intended to be conveyed due to some event; you can then use tinting to more effectively tune the visible color.
\section3 Qt.playSound(url soundLocation)
This function plays the audio file located at \c soundLocation. Only .wav files are supported.
\section3 Qt.openUrlExternally(url target)
This function attempts to open the specified \c target url in an external application, based on the user's desktop preferences. It will return true if it succeeds, and false otherwise.
\endlist
\section1 Dynamic Object Creation
The following functions on the global object allow you to dynamically create QML
items from files or strings.
You can also dynamically create objects in a declarative manner, using items
such as ListView, Repeater and Loader.
\section2 createComponent(url file)
This function takes the URL of a QML file as its only argument. It returns
a component object which can be used to create and load that QML file.
Example QML script is below. Remember that QML files that might be loaded
over the network cannot be expected to be ready immediately.
\code
var component;
var sprite;
function finishCreation(){
if(component.isReady()){
sprite = component.createObject();
if(sprite == 0){
// Error Handling
}else{
sprite.parent = page;
sprite.x = 200;
//...
}
}else if(component.isError()){
// Error Handling
}
}
component = createComponent("Sprite.qml");
if(component.isReady()){
finishCreation();
}else{
component.statusChanged.connect(finishCreation);
}
\endcode
If you are certain the files will be local, you could simplify to
\code
component = createComponent("Sprite.qml");
sprite = component.createObject();
if(sprite == 0){
// Error Handling
print(component.errorsString());
}else{
sprite.parent = page;
sprite.x = 200;
//...
}
\endcode
If you want to just create an arbitrary string of QML, instead of
loading a QML file, consider the createQmlObject() function.
\section2 createQmlObject(string qml, object parent, string filepath)
Creates a new object from the specified string of QML. It requires a
second argument, which is the id of an existing QML object to use as
the new object's parent. If a third argument is provided, this is used
for error reporting as the filepath that the QML came from.
Example (where targetItem is the id of an existing QML item):
\code
newObject = createQmlObject('import Qt 4.6; Rectangle {color: "red"; width: 20; height: 20}',
targetItem, "dynamicSnippet1");
\endcode
This function is intended for use inside QML only. It is intended to behave
similarly to eval, but for creating QML elements.
Returns the created object, or null if there is an error. In the case of an
error, details of the error are output using qWarning().
Note that this function returns immediately, and therefore may not work if
the QML loads new components. If you are trying to load a new component,
for example from a QML file, consider the createComponent() function
instead. 'New components' refers to external QML files that have not yet
been loaded, and so it is safe to use createQmlObject to load built-in
components.
\section1 Asynchronous JavaScript and XML
QML script supports the XMLHttpRequest object, which can be used to asynchronously obtain data from over a network.
\section2 XMLHttpRequest()
In QML you can construct an XMLHttpRequest object just like in a web browser! TODO: Real documentation for this object.
\section1 Offline Storage API
The \c openDatabase() and related functions
provide the ability to access local offline storage in an SQL database.
These databases are user-specific and QML-specific. They are stored in the \c Databases subdirectory
of QmlEngine::offlineStoragePath(), currently as SQLite databases.
The API is based on the HTML5 offline storage SQL draft API. The main difference is that this QML
API is currently synchronous. You should avoid relying on synchronicity to make your scripts more
portable, both to/from HTML5 and to future QML versions.
The API can be used from JavaScript functions in your QML:
\quotefile declarative/sql/hello.qml
\section2 DbObject openDatabase(string name, string version, string description, int estimatedsize)
Opens a database identified by the given \c name and \c version.
If a database with this name and version does not exist, it is created. The \c version should
always be "1.0" until schema upgrade semantics are defined.
The \c description and \c estimatedsize are provided to allow application tools to give the user
control over the databases created, but are otherwise not used by QML.
The returned DbObject has a \c transaction() method by which SQL transactions can be done.
When a database is first created, an INI file is also created specifying its characteristics:
\table
\header \o \bold {Key} \o \bold {Value}
\row \o Name \o The name of the database passed to \c openDatabase()
\row \o Version \o The version of the database passed to \c openDatabase()
\row \o Description \o The description of the database passed to \c openDatabase()
\row \o EstimatedSize \o The estimated size of the database passed to \c openDatabase()
\row \o DbType \o Currently "QSQLITE"
\endtable
This data can be used by application tools.
\section2 void DbObject::transaction(function usesql(DbTxObject), function errorcb=0, function successcb=0)
Executes \c usesql() in a database transaction. The \c DbTxObject object has a \c executeSql() method by which the
code of \c usesql can execute SQL. The optional second and third arguments are an error callback and success
callback respectively (note that the order of these is the opposite to DbTxObject::executeSql()).
\section2 void DbTxObject::executeSql(string sql, function successcb=0, function errorcb=0)
Executes \c sql as an SQL block. The optional second and third arguments are a success callback and error
callback respectively (note that the order of these is the opposite to DbObject::transaction()).
*/
|
