diff options
Diffstat (limited to 'doc/src')
| -rw-r--r-- | doc/src/declarative/globalobject.qdoc | 178 | ||||
| -rw-r--r-- | doc/src/declarative/qtdeclarative.qdoc | 1 |
2 files changed, 177 insertions, 2 deletions
diff --git a/doc/src/declarative/globalobject.qdoc b/doc/src/declarative/globalobject.qdoc index 2328c8a..fc5d988 100644 --- a/doc/src/declarative/globalobject.qdoc +++ b/doc/src/declarative/globalobject.qdoc @@ -42,7 +42,6 @@ /*! \page qmlglobalobject.html \title QML Global Object - Contains all the properties of the ECMAScript global object, plus: \list @@ -53,11 +52,186 @@ Contains all the properties of the ECMAScript global object, plus: \o openDatabase \endlist +Contents: +\tableofcontents \section1 Qt Object -\section1 Asynchronous JavaScript and XML +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 diff --git a/doc/src/declarative/qtdeclarative.qdoc b/doc/src/declarative/qtdeclarative.qdoc index 5d8623b..3be90f7 100644 --- a/doc/src/declarative/qtdeclarative.qdoc +++ b/doc/src/declarative/qtdeclarative.qdoc @@ -98,6 +98,7 @@ completely new applications. QML is fully \l {Extending QML}{extensible from C+ \section1 Reference: \list \o \l {QML Elements} +\o \l {QML Global Object} \o \l {Extending QML} \endlist |