From b08165d372e60c0c61b25dbaf5d0340ce8f985bc Mon Sep 17 00:00:00 2001 From: Bea Lam Date: Wed, 26 May 2010 17:23:41 +1000 Subject: Doc fixes, improvements --- doc/src/declarative/advtutorial.qdoc | 4 +- doc/src/declarative/dynamicobjects.qdoc | 14 +-- doc/src/declarative/examples.qdoc | 23 +++-- doc/src/declarative/globalobject.qdoc | 2 +- doc/src/declarative/qtdeclarative.qdoc | 4 +- .../ui-components/dialcontrol/dial.qmlproject | 16 ---- .../dialcontrol/dialcontrol.qmlproject | 16 ++++ src/declarative/qml/qdeclarativeengine.cpp | 102 +++++++++------------ 8 files changed, 88 insertions(+), 93 deletions(-) delete mode 100644 examples/declarative/ui-components/dialcontrol/dial.qmlproject create mode 100644 examples/declarative/ui-components/dialcontrol/dialcontrol.qmlproject diff --git a/doc/src/declarative/advtutorial.qdoc b/doc/src/declarative/advtutorial.qdoc index 47504ae..abfeadb 100644 --- a/doc/src/declarative/advtutorial.qdoc +++ b/doc/src/declarative/advtutorial.qdoc @@ -178,7 +178,7 @@ The \c createBlock() function creates a block from the \c Block.qml file and moves the new block to its position on the game canvas. This involves several steps: \list -\o \l {Qt.createComponent(url file)}{Qt.createComponent()} is called to generate an element from \c Block.qml. +\o \l {Qt::createComponent()}{Qt.createComponent()} is called to generate an element from \c Block.qml. If the component is ready, we can call \c createObject() to create an instance of the \c Block item. \o If \c createObject() returned null (i.e. if there was an error while loading the object), print the error information. @@ -468,6 +468,6 @@ By following this tutorial you've seen how you can write a fully functional appl \endlist There is so much more to learn about QML that we haven't been able to cover in this tutorial. Check out all the -demos and examples and the \l {Declarative UI Using QML}{documentation} to find out all the things you can do with QML! +demos and examples and the \l {Qt Quick}{documentation} to find out all the things you can do with QML! */ diff --git a/doc/src/declarative/dynamicobjects.qdoc b/doc/src/declarative/dynamicobjects.qdoc index 633489b..5e606f4 100644 --- a/doc/src/declarative/dynamicobjects.qdoc +++ b/doc/src/declarative/dynamicobjects.qdoc @@ -56,15 +56,15 @@ application, and there are no C++ components involved. \section1 Creating Objects Dynamically There are two ways to create objects dynamically from JavaScript. You can either call -\l {Qt.createComponent(url file)}{Qt.createComponent()} to create -a component which instantiates items, or use \l{Qt.createQmlObject(string qml, object parent, string filepath)}{Qt.createQmlObject()} +\l {Qt::createComponent()}{Qt.createComponent()} to create +a component which instantiates items, or use \l{Qt::createQmlObject()}{Qt.createQmlObject()} to create an item from a string of QML. Creating a component is better if you have a predefined item, and you want to create dynamic instances of that item; creating an item from a string of QML is useful when the item QML itself is generated at runtime. If you have a component specified in a QML file, you can dynamically load it with -the \l {Qt.createComponent(url file)}{Qt.createComponent()} function on the \l{QML Global Object}. +the \l {Qt::createComponent()}{Qt.createComponent()} function on the \l{QML Global Object}. This function takes the URL of the QML file as its only argument and returns a component object which can be used to create and load that QML file. @@ -98,10 +98,10 @@ in \c main.qml). After creating an item, you must set its parent to an item with Otherwise your dynamically created item will not appear in the scene. When using files with relative paths, the path should -be relative to the file where \l {Qt.createComponent(url file)}{Qt.createComponent()} is executed. +be relative to the file where \l {Qt::createComponent()}{Qt.createComponent()} is executed. If the QML component does not exist until runtime, you can create a QML item from -a string of QML using the \l{Qt.createQmlObject(string qml, object parent, string filepath)}{Qt.createQmlObject()} function, as in the following example: +a string of QML using the \l{Qt::createQmlObject()}{Qt.createQmlObject()} function, as in the following example: \snippet doc/src/snippets/declarative/createQmlObject.qml 0 @@ -121,9 +121,9 @@ the bindings in the dynamic item will no longer work. The actual creation context depends on how an item is created: \list -\o If \l {Qt.createComponent(url file)}{Qt.createComponent()} is used, the creation context +\o If \l {Qt::createComponent()}{Qt.createComponent()} is used, the creation context is the QDeclarativeContext in which this method is called -\o If \l{Qt.createQmlObject(string qml, object parent, string filepath)}{Qt.createQmlObject()} +\o If \l{Qt::createQmlObject()}{Qt.createQmlObject()} if called, it is the context of the item used as the second argument to this method \o If a \c {Component{}} item is defined and \l {Component::createObject()}{createObject()} is called on that item, it is the context in which the \c Component is defined diff --git a/doc/src/declarative/examples.qdoc b/doc/src/declarative/examples.qdoc index 6e0426c..5cb83fa 100644 --- a/doc/src/declarative/examples.qdoc +++ b/doc/src/declarative/examples.qdoc @@ -84,7 +84,10 @@ For example, from your build directory, run: \o \l{declarative/imageelements/borderimage}{BorderImage} \endlist -\section2 \l{declarative/positioners}{Positioners} +\section2 Positioners +\list +\o \l{declarative/positioners}{Example} +\endlist \section2 Key Interaction \list @@ -99,6 +102,7 @@ For example, from your build directory, run: \section2 UI Components \list +\o \l{declarative/ui-components/dialcontrol}{Dial control} \o \l{declarative/ui-components/flipable}{Flipable} \o \l{declarative/ui-components/progressbar}{Progress bar} \o \l{declarative/ui-components/scrollbar}{Scroll bar} @@ -112,10 +116,10 @@ For example, from your build directory, run: \list \o \l{declarative/modelviews/gridview}{GridView} \o \l{declarative/modelviews/listview}{ListView} -\o \l{declarative/modelviews/objectlistmodel}{Object list model} +\o \l{declarative/modelviews/objectlistmodel}{Object ListModel} \o \l{declarative/modelviews/package}{Package} \o \l{declarative/modelviews/parallax}{Parallax} -\o \l{declarative/modelviews/stringlistmodel}{String list model} +\o \l{declarative/modelviews/stringlistmodel}{String ListModel} \o \l{declarative/modelviews/webview}{WebView} \endlist @@ -124,7 +128,10 @@ For example, from your build directory, run: \o \l{declarative/xml/xmlhttprequest}{XmlHttpRequest} \endlist -\section2 \l{declarative/i18n}{Internationalization (i18n)} +\section2 Internationalization (i18n) +\list +\o \l{declarative/i18n}{Example} +\endlist \section2 Threading \list @@ -132,11 +139,14 @@ For example, from your build directory, run: \o \l{declarative/threading/workerscript}{WorkerScript} \endlist -\section2 \l{declarative/sqllocalstorage}{SQL Local Storage} +\section2 SQL Local Storage +\list +\o \l{declarative/sqllocalstorage}{Example} +\endlist \section2 C++ Extensions \list -\o \l{declarative-cppextensions-reference.html}{Reference examples} (discussed in \l {Extending QML in C++}) +\o \l{declarative-cppextensions-reference.html}{Reference examples} \o \l{declarative/cppextensions/plugins}{Plugins} \o \l{declarative-cppextensions-qgraphicslayouts.html}{QGraphicsLayouts} \o \l{declarative/cppextensions/qwidgets}{QWidgets} @@ -148,7 +158,6 @@ For example, from your build directory, run: \list \o \l{declarative/toys/clocks}{Clocks} \o \l{declarative/toys/corkboards}{Corkboards} -\o \l{declarative/toys/dial}{Dial} \o \l{declarative/toys/dynamicscene}{Dynamic Scene} \o \l{declarative/toys/tic-tac-toe}{Tic Tac Toe} \o \l{declarative/toys/tvtennis}{TV Tennis} diff --git a/doc/src/declarative/globalobject.qdoc b/doc/src/declarative/globalobject.qdoc index 2885dd5..3a2ad81 100644 --- a/doc/src/declarative/globalobject.qdoc +++ b/doc/src/declarative/globalobject.qdoc @@ -49,7 +49,7 @@ Contains all the properties of the JavaScript global object, plus: \section1 Qt Object -The \l{qt-qml.html}{Qt object} provides useful enums and functions from Qt, for use in all QML +The \l{qml-qt.html}{Qt object} provides useful enums and functions from Qt, for use in all QML files. \section1 XMLHttpRequest diff --git a/doc/src/declarative/qtdeclarative.qdoc b/doc/src/declarative/qtdeclarative.qdoc index c47ab23..f7cb722 100644 --- a/doc/src/declarative/qtdeclarative.qdoc +++ b/doc/src/declarative/qtdeclarative.qdoc @@ -112,7 +112,7 @@ Returns the QML type id. - \sa qmlRegisterTypeNotAvailable + \sa qmlRegisterTypeNotAvailable() */ /*! @@ -147,7 +147,7 @@ fun.qml: Get back to work, slacker! Without this, a generic "Game is not a type" message would be given. - \sa qmlRegisterUncreatableType + \sa qmlRegisterUncreatableType() */ /*! diff --git a/examples/declarative/ui-components/dialcontrol/dial.qmlproject b/examples/declarative/ui-components/dialcontrol/dial.qmlproject deleted file mode 100644 index d4909f8..0000000 --- a/examples/declarative/ui-components/dialcontrol/dial.qmlproject +++ /dev/null @@ -1,16 +0,0 @@ -import QmlProject 1.0 - -Project { - /* Include .qml, .js, and image files from current directory and subdirectories */ - QmlFiles { - directory: "." - } - JavaScriptFiles { - directory: "." - } - ImageFiles { - directory: "." - } - /* List of plugin directories passed to QML runtime */ - // importPaths: [ " ../exampleplugin " ] -} diff --git a/examples/declarative/ui-components/dialcontrol/dialcontrol.qmlproject b/examples/declarative/ui-components/dialcontrol/dialcontrol.qmlproject new file mode 100644 index 0000000..d4909f8 --- /dev/null +++ b/examples/declarative/ui-components/dialcontrol/dialcontrol.qmlproject @@ -0,0 +1,16 @@ +import QmlProject 1.0 + +Project { + /* Include .qml, .js, and image files from current directory and subdirectories */ + QmlFiles { + directory: "." + } + JavaScriptFiles { + directory: "." + } + ImageFiles { + directory: "." + } + /* List of plugin directories passed to QML runtime */ + // importPaths: [ " ../exampleplugin " ] +} diff --git a/src/declarative/qml/qdeclarativeengine.cpp b/src/declarative/qml/qdeclarativeengine.cpp index a7384a9..8679e76 100644 --- a/src/declarative/qml/qdeclarativeengine.cpp +++ b/src/declarative/qml/qdeclarativeengine.cpp @@ -153,11 +153,11 @@ void QDeclarativeEnginePrivate::defineModule() /*! \qmlclass Qt QDeclarativeEnginePrivate -\brief The QML Global Qt Object +\brief The QML global Qt object provides useful enums and functions from Qt. -The Qt object provides useful enums and functions from Qt, for use in all QML -files. Note that you do note create instances of this type, but instead use -the members of the global "Qt" object. +The Qt object provides useful enums and functions from Qt, for use in all QML files. + +You do not create instances of this type, but instead use the members of the global "Qt" object. \section1 Enums @@ -172,23 +172,23 @@ 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 +\o \c color - use \l{Qt::rgba()}{Qt.rgba()}, \l{Qt::darker()}{Qt.darker()}, \l{Qt::lighter()}{Qt.lighter()} or \l{Qt::tint()}{Qt.tint()} +\o \c rect - use \l{Qt::rect()}{Qt.rect()} +\o \c point - use \l{Qt::point()}{Qt.point()} +\o \c size - use \l{Qt::size()}{Qt.size()} +\o \c vector3d - use \l{Qt::vector3d()}{Qt.vector3d()} \endlist -There are also string based constructors for these types, see \l{qdeclarativebasictypes.html}{Qml Types}. +There are also string based constructors for these types, see \l{qdeclarativebasictypes.html}{QML Basic Types}. \section1 Date/Time Formatters The Qt object contains several functions for formatting dates and times. \list - \o \l{Qt::formatDateTime}{string Qt.formatDateTime(datetime date, variant format) - \o \l{Qt::formatDate}{string Qt.formatDate(datetime date, variant format) - \o \l{Qt::formatTime}{string Qt.formatTime(datetime date, variant format) + \o \l{Qt::formatDateTime}{string Qt.formatDateTime(datetime date, variant format)} + \o \l{Qt::formatDate}{string Qt.formatDate(datetime date, variant format)} + \o \l{Qt::formatTime}{string Qt.formatTime(datetime date, variant format)} \endlist The format specification is described at \l{Qt::formatDateTime}{Qt.formatDateTime}. @@ -226,8 +226,7 @@ QDeclarativeEnginePrivate::QDeclarativeEnginePrivate(QDeclarativeEngine *e) /*! \qmlmethod url Qt::resolvedUrl(url) -This function returns \c url resolved relative to the URL of the -caller. +Returns \c url resolved relative to the URL of the caller. */ QUrl QDeclarativeScriptEngine::resolvedUrl(QScriptContext *context, const QUrl& url) { @@ -1035,8 +1034,11 @@ QString QDeclarativeEnginePrivate::urlToLocalFileOrQrc(const QUrl& url) /*! \qmlmethod object Qt::createComponent(url) -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. +Returns a \l Component object created from the QML file at the specified \a url, +or \c null if there was an error in creating the component. + +Call \l {Component::createObject()}{Component.createObject()} on the returned +component to create an object instance of the component. Here is an example. Remember that QML files that might be loaded over the network cannot be expected to be ready immediately. @@ -1049,17 +1051,8 @@ If you are certain the files will be local, you could simplify to: \snippet doc/src/snippets/declarative/componentCreation.js 2 -The methods and properties of the \l {Component} element are defined in its own -page, but when using it dynamically only two methods are usually used. - \l {Component::createObject()}{Component.createObject()} returns the created object or \c null if there is an error. -If there is an error, \l {Component::errorString()}{Component.errorString()} describes -the error that occurred. Note that createObject() takes exactly one argument, which is set -to the parent of the created object. Graphical objects without a parent will not appear -on the scene, but if you do not wish to parent the item at this point you can safely pass -in null. - -If you want to just create an arbitrary string of QML, instead of -loading a QML file, consider the \l{Qt.createQmlObject(string qml, object parent, string filepath)}{Qt.createQmlObject()} function. +To create a QML object from an arbitrary string of QML (instead of a file), +use \l{Qt::createQmlObject()}{Qt.createQmlObject()}. */ QScriptValue QDeclarativeEnginePrivate::createComponent(QScriptContext *ctxt, QScriptEngine *engine) @@ -1088,29 +1081,22 @@ QScriptValue QDeclarativeEnginePrivate::createComponent(QScriptContext *ctxt, QS /*! \qmlmethod object Qt::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. +Returns a new object created from the given \a string of QML with the specified \a parent, +or \c null if there was an error in creating the object. + +If \a filepath is specified, it will be used for error reporting for the created object. Example (where \c targetItem is the id of an existing QML item): \snippet doc/src/snippets/declarative/createQmlObject.qml 0 -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, \c 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 \c lineNumber, \c columnNumber, \c fileName and \c message. +In the case of an error, a QtScript Error object is thrown. This object has an additional property, +\c qmlErrors, which is an array of the errors encountered. +Each object in this array has the members \c lineNumber, \c columnNumber, \c fileName and \c 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 \l{Qt.createComponent(url file)}{Qt.createComponent()} function -instead. 'New components' refers to external QML files that have not yet -been loaded, and so it is safe to use \c Qt.createQmlObject() to load built-in -components. +the \a qml string loads new components (that is, external QML files that have not yet been loaded). +If this is the case, consider using \l{Qt::createComponent()}{Qt.createComponent()} instead. */ QScriptValue QDeclarativeEnginePrivate::createQmlObject(QScriptContext *ctxt, QScriptEngine *engine) @@ -1217,7 +1203,7 @@ QScriptValue QDeclarativeEnginePrivate::isQtObject(QScriptContext *ctxt, QScript /*! \qmlmethod Qt::vector3d(real x, real y, real z) -This function returns a Vector3D with the specified \c x, \c y and \c z. +Returns a Vector3D with the specified \c x, \c y and \c z. */ QScriptValue QDeclarativeEnginePrivate::vector3d(QScriptContext *ctxt, QScriptEngine *engine) { @@ -1231,7 +1217,7 @@ QScriptValue QDeclarativeEnginePrivate::vector3d(QScriptContext *ctxt, QScriptEn /*! \qmlmethod string Qt::formatDate(datetime date, variant format) -This function returns the string representation of \c date, formatted according to \c format. +Returns the string representation of \c date, formatted according to \c format. */ QScriptValue QDeclarativeEnginePrivate::formatDate(QScriptContext*ctxt, QScriptEngine*engine) { @@ -1256,7 +1242,7 @@ QScriptValue QDeclarativeEnginePrivate::formatDate(QScriptContext*ctxt, QScriptE /*! \qmlmethod string Qt::formatTime(datetime time, variant format) -This function returns the string representation of \c time, formatted according to \c format. +Returns the string representation of \c time, formatted according to \c format. See Qt::formatDateTime for how to define \c format. */ @@ -1283,7 +1269,7 @@ QScriptValue QDeclarativeEnginePrivate::formatTime(QScriptContext*ctxt, QScriptE /*! \qmlmethod string Qt::formatDateTime(datetime dateTime, variant format) -This function returns the string representation of \c dateTime, formatted according to \c format. +Returns the string representation of \c dateTime, formatted according to \c format. \c format for the date/time formatting functions is be specified as follows. @@ -1374,7 +1360,7 @@ QScriptValue QDeclarativeEnginePrivate::formatDateTime(QScriptContext*ctxt, QScr /*! \qmlmethod color Qt::rgba(real red, real green, real blue, real alpha) -This function returns a Color with the specified \c red, \c green, \c blue and \c alpha components. +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. */ QScriptValue QDeclarativeEnginePrivate::rgba(QScriptContext *ctxt, QScriptEngine *engine) @@ -1402,7 +1388,7 @@ QScriptValue QDeclarativeEnginePrivate::rgba(QScriptContext *ctxt, QScriptEngine /*! \qmlmethod color Qt::hsla(real hue, real saturation, real lightness, real alpha) -This function returns a Color with the specified \c hue, \c saturation, \c lightness and \c alpha components. +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. */ QScriptValue QDeclarativeEnginePrivate::hsla(QScriptContext *ctxt, QScriptEngine *engine) @@ -1430,7 +1416,7 @@ QScriptValue QDeclarativeEnginePrivate::hsla(QScriptContext *ctxt, QScriptEngine /*! \qmlmethod rect 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. +Returns a Rect with the top-left corner at \c x, \c y and the specified \c width and \c height. */ QScriptValue QDeclarativeEnginePrivate::rect(QScriptContext *ctxt, QScriptEngine *engine) { @@ -1450,7 +1436,7 @@ QScriptValue QDeclarativeEnginePrivate::rect(QScriptContext *ctxt, QScriptEngine /*! \qmlmethod point Qt::point(int x, int y) -This function returns a Point with the specified \c x and \c y coordinates. +Returns a Point with the specified \c x and \c y coordinates. */ QScriptValue QDeclarativeEnginePrivate::point(QScriptContext *ctxt, QScriptEngine *engine) { @@ -1463,7 +1449,7 @@ QScriptValue QDeclarativeEnginePrivate::point(QScriptContext *ctxt, QScriptEngin /*! \qmlmethod Qt::size(int width, int height) -This function returns as Size with the specified \c width and \c height. +Returns a Size with the specified \c width and \c height. */ QScriptValue QDeclarativeEnginePrivate::size(QScriptContext *ctxt, QScriptEngine *engine) { @@ -1476,7 +1462,7 @@ QScriptValue QDeclarativeEnginePrivate::size(QScriptContext *ctxt, QScriptEngine /*! \qmlmethod color Qt::lighter(color baseColor, real factor) -This function returns a color lighter than \c baseColor by the \c factor provided. +Returns a color lighter than \c baseColor by the \c factor provided. If the factor is greater than 1.0, this functions returns a lighter color. Setting factor to 1.5 returns a color that is 50% brighter. If the factor is less than 1.0, @@ -1512,7 +1498,7 @@ QScriptValue QDeclarativeEnginePrivate::lighter(QScriptContext *ctxt, QScriptEng /*! \qmlmethod color Qt::darker(color baseColor, real factor) -This function returns a color darker than \c baseColor by the \c factor provided. +Returns a color darker than \c baseColor by the \c factor provided. If the factor is greater than 1.0, this function returns a darker color. Setting factor to 3.0 returns a color that has one-third the brightness. @@ -1549,7 +1535,7 @@ QScriptValue QDeclarativeEnginePrivate::darker(QScriptContext *ctxt, QScriptEngi /*! \qmlmethod bool 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. +Attempts to open the specified \c target url in an external application, based on the user's desktop preferences. Returns true if it succeeds, and false otherwise. */ QScriptValue QDeclarativeEnginePrivate::desktopOpenUrl(QScriptContext *ctxt, QScriptEngine *e) { @@ -1564,7 +1550,7 @@ QScriptValue QDeclarativeEnginePrivate::desktopOpenUrl(QScriptContext *ctxt, QSc /*! \qmlmethod list Qt::fontFamilies() -This function returns a list of the font families available to the application. +Returns a list of the font families available to the application. */ QScriptValue QDeclarativeEnginePrivate::fontFamilies(QScriptContext *ctxt, QScriptEngine *e) @@ -1579,7 +1565,7 @@ QScriptValue QDeclarativeEnginePrivate::fontFamilies(QScriptContext *ctxt, QScri /*! \qmlmethod string Qt::md5(data) -This function returns a hex string of the md5 hash of \c data. +Returns a hex string of the md5 hash of \c data. */ QScriptValue QDeclarativeEnginePrivate::md5(QScriptContext *ctxt, QScriptEngine *) { -- cgit v0.12