diff options
| -rw-r--r-- | doc/src/declarative/globalobject.qdoc | 178 | ||||
| -rw-r--r-- | doc/src/declarative/qtdeclarative.qdoc | 1 | ||||
| -rw-r--r-- | src/declarative/qml/qmlengine.cpp | 118 | ||||
| -rw-r--r-- | src/declarative/qml/qmlengine_p.h | 1 |
4 files changed, 180 insertions, 118 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 diff --git a/src/declarative/qml/qmlengine.cpp b/src/declarative/qml/qmlengine.cpp index 6c303e3..8581751 100644 --- a/src/declarative/qml/qmlengine.cpp +++ b/src/declarative/qml/qmlengine.cpp @@ -121,6 +121,8 @@ QmlEnginePrivate::QmlEnginePrivate(QmlEngine *e) nodeListClass(0), namedNodeMapClass(0), sqlQueryClass(0), cleanup(0), scriptEngine(this), componentAttacheds(0), rootComponent(0), networkAccessManager(0), typeManager(e), uniqueId(1) { + // Note that all documentation for stuff put on the global object goes in + // doc/src/declarative/globalobject.qdoc QScriptValue qtObject = scriptEngine.newQMetaObject(StaticQtMetaObject::get()); scriptEngine.globalObject().setProperty(QLatin1String("Qt"), qtObject); @@ -584,59 +586,6 @@ QmlContext *QmlEnginePrivate::getContext(QScriptContext *ctxt) return contextClass->contextFromValue(scopeNode); } -/*! - This function is intended for use inside QML only. In C++ just create a - component object as usual. - - 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 QmlJS 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. -*/ QScriptValue QmlEnginePrivate::createComponent(QScriptContext *ctxt, QScriptEngine *engine) { @@ -659,31 +608,6 @@ QScriptValue QmlEnginePrivate::createComponent(QScriptContext *ctxt, return engine->newQObject(c); } -/*! - 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 - 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. -*/ QScriptValue QmlEnginePrivate::createQmlObject(QScriptContext *ctxt, QScriptEngine *engine) { QmlEnginePrivate *activeEnginePriv = @@ -736,32 +660,6 @@ QScriptValue QmlEnginePrivate::createQmlObject(QScriptContext *ctxt, QScriptEngi return engine->nullValue(); } -/*! - 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 -*/ QScriptValue QmlEnginePrivate::vector(QScriptContext *ctxt, QScriptEngine *engine) { if(ctxt->argumentCount() < 3) @@ -894,19 +792,7 @@ QScriptValue QmlEnginePrivate::desktopOpenUrl(QScriptContext *ctxt, QScriptEngin bool ret = QDesktopServices::openUrl(QUrl(ctxt->argument(0).toString())); return e->newVariant(QVariant(ret)); } -/*! - 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. -*/ QScriptValue QmlEnginePrivate::tint(QScriptContext *ctxt, QScriptEngine *engine) { if(ctxt->argumentCount() < 2) diff --git a/src/declarative/qml/qmlengine_p.h b/src/declarative/qml/qmlengine_p.h index 7629dc1..f5bc015 100644 --- a/src/declarative/qml/qmlengine_p.h +++ b/src/declarative/qml/qmlengine_p.h @@ -250,6 +250,7 @@ public: QVariant scriptValueToVariant(const QScriptValue &); static QScriptValue qmlScriptObject(QObject*, QmlEngine*); + static QScriptValue createComponent(QScriptContext*, QScriptEngine*); static QScriptValue createQmlObject(QScriptContext*, QScriptEngine*); static QScriptValue vector(QScriptContext*, QScriptEngine*); |