diff options
Diffstat (limited to 'doc/src/declarative/globalobject.qdoc')
| -rw-r--r-- | doc/src/declarative/globalobject.qdoc | 316 |
1 files changed, 316 insertions, 0 deletions
diff --git a/doc/src/declarative/globalobject.qdoc b/doc/src/declarative/globalobject.qdoc new file mode 100644 index 0000000..4b1c7d3 --- /dev/null +++ b/doc/src/declarative/globalobject.qdoc @@ -0,0 +1,316 @@ +/**************************************************************************** +** +** 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.closestAngle(number fromAngle, number toAngle) +This function returns an equivalent angle to toAngle, such that the difference between fromAngle and toAngle is never more than 180 degrees. This is useful when animating angles using a NumberAnimation, which does not know about equivalent angles, when you always want to take the shortest path. + +For example, the following would rotate myItem counterclockwise from 350 degrees to 10 degrees, for a total of 340 degrees of rotation. +\qml +NumberAnimation { target: myItem; property: "rotation"; from: 350; to: 10 } +\endqml + +while the following would rotate myItem clockwise from 350 degrees to 370 degrees (which is visually equivilant to 10 degrees), for a total of 20 degrees of rotation. +\qml +NumberAnimation { target: myItem; property: "rotation"; from: 350; to: Qt.closetAngle(350, 10) } +\endqml + +\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. + +\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 + + 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 QDeclarativeEngine::offlineStoragePath(), currently as SQLite databases. + +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. + +The API can be used from JavaScript functions in your QML: + +\quotefile declarative/sql/hello.qml + +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. + +*/ |