summaryrefslogtreecommitdiffstats
path: root/doc/src/declarative/globalobject.qdoc
blob: e2152b35bcff23908da621608d281aebcc0fdb4d (plain)
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
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
/****************************************************************************
**
** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation (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 Technology Preview License Agreement accompanying
** this package.
**
** 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.1, included in the file LGPL_EXCEPTION.txt in this package.
**
** If you have questions regarding the use of this file, please contact
** Nokia at qt-info@nokia.com.
**
**
**
**
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
\page qdeclarativeglobalobject.html
\title QML Global Object

Contains all the properties of the JavaScript global object, plus:

\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 \l{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{qdeclarativebasictypes.html}{Qml Types}.

\section3 Qt.rgba(qreal red, qreal green, qreal blue, qreal 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-1 inclusive.

\section3 Qt.hsla(qreal hue, qreal saturation, qreal lightness, qreal 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-1 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)
This function returns as Size with the specified \c width and \c height.
\section3 Qt.vector3d(real x, real y, real z)
This function returns a Vector3D with the specified \c x, \c y and \c z.

\section2 Formatters
The Qt object contains several functions for formatting dates and times.

\section3 Qt.formatDate(datetime date, variant format)
This function returns the string representation of \c date, formatted according to \c format.
\section3 Qt.formatTime(datetime time, variant format)
This function returns the string representation of \c time, formatted according to \c format.
\section3 Qt.formatDateTime(datetime dateTime, variant format)
This function returns the string representation of \c dateTime, formatted according to \c format.

\c format for the above formatting functions can be specified as follows.

    These expressions may be used for the date:

    \table
    \header \i Expression \i Output
    \row \i d \i the day as number without a leading zero (1 to 31)
    \row \i dd \i the day as number with a leading zero (01 to 31)
    \row \i ddd
            \i the abbreviated localized day name (e.g. 'Mon' to 'Sun').
            Uses QDate::shortDayName().
    \row \i dddd
            \i the long localized day name (e.g. 'Monday' to 'Qt::Sunday').
            Uses QDate::longDayName().
    \row \i M \i the month as number without a leading zero (1-12)
    \row \i MM \i the month as number with a leading zero (01-12)
    \row \i MMM
            \i the abbreviated localized month name (e.g. 'Jan' to 'Dec').
            Uses QDate::shortMonthName().
    \row \i MMMM
            \i the long localized month name (e.g. 'January' to 'December').
            Uses QDate::longMonthName().
    \row \i yy \i the year as two digit number (00-99)
    \row \i yyyy \i the year as four digit number
    \endtable

    These expressions may be used for the time:

    \table
    \header \i Expression \i Output
    \row \i h
         \i the hour without a leading zero (0 to 23 or 1 to 12 if AM/PM display)
    \row \i hh
         \i the hour with a leading zero (00 to 23 or 01 to 12 if AM/PM display)
    \row \i m \i the minute without a leading zero (0 to 59)
    \row \i mm \i the minute with a leading zero (00 to 59)
    \row \i s \i the second without a leading zero (0 to 59)
    \row \i ss \i the second with a leading zero (00 to 59)
    \row \i z \i the milliseconds without leading zeroes (0 to 999)
    \row \i zzz \i the milliseconds with leading zeroes (000 to 999)
    \row \i AP
            \i use AM/PM display. \e AP will be replaced by either "AM" or "PM".
    \row \i ap
            \i use am/pm display. \e ap will be replaced by either "am" or "pm".
    \endtable

    All other input characters will be ignored. Any sequence of characters that
    are enclosed in singlequotes will be treated as text and not be used as an
    expression. Two consecutive singlequotes ("''") are replaced by a singlequote
    in the output.

    Example format strings (assumed that the date and time is 21 May 2001
    14:13:09):

    \table
    \header \i Format       \i Result
    \row \i dd.MM.yyyy      \i 21.05.2001
    \row \i ddd MMMM d yy   \i Tue May 21 01
    \row \i hh:mm:ss.zzz    \i 14:13:09.042
    \row \i h:m:s ap        \i 2:13:9 pm
    \endtable

If no format is specified the locale's short format is used. Alternatively, you can specify
\c Qt.DefaultLocaleLongDate to get the locale's long format.

\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::darker() 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.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.

\section3 Qt.md5(data)
This function returns a hex string of the md5 hash of \c data.

\section3 Qt.btoa(data)
This function returns a base64 encoding of \c data.

\section3 Qt.atob(data)
This function returns a base64 decoding of \c data.

\section3 Qt.quit()
This function causes the QML engine to emit the quit signal, which in
\l {Qt Declarative UI Runtime}{qml} causes the runtime to quit.

\section3 Qt.resolvedUrl(url)
This function returns \c url resolved relative to the URL of the
caller.

\section3 Qt.isQtObject(object)
Returns true if \c object is a valid reference to a Qt or QML object, otherwise false.

\section1 Dynamic Object Creation
The following functions on the global object allow you to dynamically create QML
items from files or strings. See \l{Dynamic Object Management} for an overview
of their use.

\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
            console.log(component.errorsString());
        }else{
            sprite.parent = page;
            sprite.x = 200;
            //...
        }
    \endcode

    The methods and properties of the Component element are defined in its own
    page, but when using it dynamically only two methods are usually used.
    Component.createObject() returns the created object or null if there is an error.
    If there is an error, Component.errorsString() describes what the error was.

    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.7; 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, a QtScript Error object is thrown. This object has the additional property,
    qmlErrors, which is an array of all the errors encountered when trying to execute the
    QML. Each object in the array has the members: lineNumber, columnNumber, fileName and message.

    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

\section2 Database API

The \c openDatabaseSync() and related functions
provide the ability to access local offline storage in an SQL database.

These databases are user-specific and QML-specific, but accessible to all QML applications.
They are stored in the \c Databases subdirectory
of QDeclarativeEngine::offlineStoragePath(), currently as SQLite databases.

The API can be used from JavaScript functions in your QML:

\quotefile declarative/sql/hello.qml

The API conforms to the Synchronous API of the HTML5 Web Database API,
\link http://www.w3.org/TR/2009/WD-webdatabase-20091029/ W3C Working Draft 29 October 2009\endlink.

\section3 db = openDatabaseSync(identifier, version, description, estimated_size, callback(db))

Returns the database identified by \e identifier. If the database does not already exist, it
is created with the properties \e description and \e estimated_size and the function \e callback
is called with the database as a parameter.

May throw exception with code property SQLException.DATABASE_ERR, or SQLException.VERSION_ERR.

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 Driver \o Currently "QSQLITE"
\endtable

This data can be used by application tools.

\section3 db.changeVersion(from, to, callback(tx))

This method allows you to perform a \e{Scheme Upgrade}.

If the current version of \e db is not \e from, then an exception is thrown.

Otherwise, a database transaction is created and passed to \e callback. In this function,
you can call \e executeSql on \e tx to upgrade the database.

May throw exception with code property SQLException.DATABASE_ERR or SQLException.UNKNOWN_ERR.

\section3 db.transaction(callback(tx))

This method creates a read/write transaction and passed to \e callback. In this function,
you can call \e executeSql on \e tx to read and modify the database.

If the callback throws exceptions, the transaction is rolled back.

\section3 db.readTransaction(callback(tx))

This method creates a read-only transaction and passed to \e callback. In this function,
you can call \e executeSql on \e tx to read the database (with SELECT statements).

\section3 results = tx.executeSql(statement, values)

This method executes a SQL \e statement, binding the list of \e values to SQL positional parameters ("?").

It returns a results object, with the following properties:

\table
\header \o \bold {Type} \o \bold {Property} \o \bold {Value} \o \bold {Applicability}
\row \o int \o rows.length \o The number of rows in the result \o SELECT
\row \o var \o rows.item(i) \o Function that returns row \e i of the result \o SELECT
\row \o int \o rowsAffected \o The number of rows affected by a modification \o UPDATE, DELETE
\row \o string \o insertId \o The id of the row inserted \o INSERT
\endtable

May throw exception with code property SQLException.DATABASE_ERR, SQLException.SYNTAX_ERR, or SQLException.UNKNOWN_ERR.

\section1 Logging

\c console.log() and \c console.debug() can be used to print information
to the console. See \l{Debugging QML} for more information.

*/