From 77cddec6ea642b073d1d9c017c865e740c0c60bc Mon Sep 17 00:00:00 2001 From: Bea Lam Date: Fri, 30 Apr 2010 15:26:55 +1000 Subject: Doc fixes --- doc/src/declarative/codingconventions.qdoc | 6 +- doc/src/declarative/dynamicobjects.qdoc | 65 +++++++++++-------- doc/src/declarative/globalobject.qdoc | 76 +++++++++++------------ doc/src/snippets/declarative/componentCreation.js | 48 +++++++------- src/declarative/qml/qdeclarativecomponent.cpp | 6 +- 5 files changed, 106 insertions(+), 95 deletions(-) diff --git a/doc/src/declarative/codingconventions.qdoc b/doc/src/declarative/codingconventions.qdoc index 7ca206b..d0f873d 100644 --- a/doc/src/declarative/codingconventions.qdoc +++ b/doc/src/declarative/codingconventions.qdoc @@ -57,7 +57,7 @@ Through our documentation and examples, QML objects are always structured in the \o id \o property declarations \o signal declarations -\o javascript functions +\o JavaScript functions \o object properties \o child objects \o states @@ -102,7 +102,7 @@ we will write this: \snippet doc/src/snippets/declarative/codingconventions/lists.qml 1 -\section1 Javascript code +\section1 JavaScript code If the script is a single expression, we recommend writing it inline: @@ -116,7 +116,7 @@ If the script is more than a couple of lines long or can be used by different ob \snippet doc/src/snippets/declarative/codingconventions/javascript.qml 2 -For long scripts, we will put the functions in their own javascript file and import it like this: +For long scripts, we will put the functions in their own JavaScript file and import it like this: \snippet doc/src/snippets/declarative/codingconventions/javascript-imports.qml 0 diff --git a/doc/src/declarative/dynamicobjects.qdoc b/doc/src/declarative/dynamicobjects.qdoc index a2b65a8..c376266 100644 --- a/doc/src/declarative/dynamicobjects.qdoc +++ b/doc/src/declarative/dynamicobjects.qdoc @@ -43,23 +43,25 @@ \page qdeclarativedynamicobjects.html \title Dynamic Object Management -QML has some support for dynamically loading and managing QML objects from -within Javascript blocks. It is preferable to use the existing QML elements for -dynamic object management wherever possible; these are \l{Loader}, -\l{Repeater}, \l{ListView}, \l{GridView} and \l{PathView}. It is also possible -to dynamically create and manage objects from C++, and this is preferable for -hybrid QML/C++ applications - see \l{Using QML in C++ Applications}. -Dynamically creating and managing objects from -within Javascript blocks is intended for when none of the existing QML elements -fit the needs of your application, and you do not desire for your application -to involve C++ code. +QML provides a number of ways to dynamically create and manage QML objects. +The \l{Loader}, \l{Repeater}, \l{ListView}, \l{GridView} and \l{PathView} elements +all support dynamic object management. Objects can also be created and managed +from C++, and this is the preferred method for hybrid QML/C++ applications +(see \l{Using QML in C++ Applications}). + +QML also supports the dynamic creation of objects from within JavaScript +code. This is useful if the existing QML elements do not fit the needs of your +application, and there are no C++ components involved. + \section1 Creating Objects Dynamically -There are two ways of creating objects dynamically. You can either create -a component which instantiates items, or create an item from a string of QML. -Creating a component is better for the situation where you have a predefined -item which you want to manage dynamic instances of, and creating an item from -a string of QML is intended for when the QML itself is generated at runtime. +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()} +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}. @@ -69,7 +71,7 @@ a component object which can be used to create and load that QML file. Once you have a component you can use its \c createObject() method to create an instance of the component. -Here is an example. Here is a simple QML component defined in \c Sprite.qml: +Here is an example. Here is a \c Sprite.qml, which defines a simple QML component: \quotefile doc/src/snippets/declarative/Sprite.qml @@ -84,14 +86,10 @@ over the network cannot be expected to be ready immediately: \snippet doc/src/snippets/declarative/componentCreation.js 0 \codeline \snippet doc/src/snippets/declarative/componentCreation.js 1 -\snippet doc/src/snippets/declarative/componentCreation.js 2 -\snippet doc/src/snippets/declarative/componentCreation.js 4 -\codeline -\snippet doc/src/snippets/declarative/componentCreation.js 5 If you are certain the files will be local, you could simplify to: -\snippet doc/src/snippets/declarative/componentCreation.js 3 +\snippet doc/src/snippets/declarative/componentCreation.js 2 Notice that once a \c Sprite object is created, its parent is set to \c appWindow (defined in \c main.qml). After creating an item, you must set its parent to an item within the scene. @@ -114,8 +112,22 @@ item, which is used for error reporting. \section1 Maintaining Dynamically Created Objects -Dynamically created objects may be used the same as other objects, however they -will not have an id in QML. +When managing dynamically created items, you must ensure the creation context +outlives the created item. Otherwise, if the creation context is destroyed first, +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 + is the QDeclarativeContext in which this method is called +\o If \l{Qt.createQmlObject(string qml, object parent, string filepath)}{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 \c {Component::}{createObject()} is called, + it is the context in which the \c Component item is defined + +Also, note that while dynamically created objects may be used the same as other objects, they +do not have an id in QML. A restriction which you need to manage with dynamically created items, is that the creation context must outlive the @@ -134,7 +146,7 @@ a worthwhile performance benefit. Note that you should never manually delete items which were dynamically created by QML Elements such as \l{Loader}. To manually delete a QML item, call its destroy method. This method has one -argument, which is an approximate delay in ms and which defaults to zero. This +argument, which is an approximate delay in milliseconds and which defaults to zero. This allows you to wait until the completion of an animation or transition. An example: \code @@ -153,8 +165,9 @@ allows you to wait until the completion of an animation or transition. An exampl object.parent = parentItem; } \endcode -In the above example, the dynamically created rectangle calls destroy as soon as it's created, - but delays long enough for its fade out animation to play. + +In the above example, the dynamically created rectangle calls destroy as soon as it is created, + but delays long enough for its fade out animation to be played. */ diff --git a/doc/src/declarative/globalobject.qdoc b/doc/src/declarative/globalobject.qdoc index 85cbde2..47460cf 100644 --- a/doc/src/declarative/globalobject.qdoc +++ b/doc/src/declarative/globalobject.qdoc @@ -234,58 +234,58 @@ 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 Qt.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. - Here is an example. Remember that QML files that might be loaded - over the network cannot be expected to be ready immediately. +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. + +Here is an example. Remember that QML files that might be loaded +over the network cannot be expected to be ready immediately. - \snippet doc/src/snippets/declarative/componentCreation.js 0 - \codeline - \snippet doc/src/snippets/declarative/componentCreation.js 1 - \snippet doc/src/snippets/declarative/componentCreation.js 2 - \snippet doc/src/snippets/declarative/componentCreation.js 4 - \codeline - \snippet doc/src/snippets/declarative/componentCreation.js 5 +\snippet doc/src/snippets/declarative/componentCreation.js 0 +\codeline +\snippet doc/src/snippets/declarative/componentCreation.js 1 - If you are certain the files will be local, you could simplify to: +If you are certain the files will be local, you could simplify to: - \snippet doc/src/snippets/declarative/componentCreation.js 3 +\snippet doc/src/snippets/declarative/componentCreation.js 2 - 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. - \c Component.createObject() returns the created object or \c null if there is an error. - If there is an error, \l {Component::errorsString()}{Component.errorsString()} describes - the error that occurred. +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. +\c Component.createObject() returns the created object or \c null if there is an error. +If there is an error, \l {Component::errorsString()}{Component.errorsString()} describes +the error that occurred. + +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. - 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. \section2 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. - Example (where \c targetItem is the id of an existing QML item): +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 \c targetItem is the id of an existing QML item): - \snippet doc/src/snippets/declarative/createQmlObject.qml 0 +\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. +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. +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. - 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. +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. \section1 XMLHttpRequest diff --git a/doc/src/snippets/declarative/componentCreation.js b/doc/src/snippets/declarative/componentCreation.js index 814545e..be928f0 100644 --- a/doc/src/snippets/declarative/componentCreation.js +++ b/doc/src/snippets/declarative/componentCreation.js @@ -20,38 +20,32 @@ function finishCreation() { } //![0] -//![1] function createSpriteObjects() { -//![1] - - //![2] - component = Qt.createComponent("Sprite.qml"); - if (component.status == Component.Ready) - finishCreation(); - else - component.statusChanged.connect(finishCreation); - //![2] - //![3] - component = Qt.createComponent("Sprite.qml"); - sprite = component.createObject(); +//![1] +component = Qt.createComponent("Sprite.qml"); +if (component.status == Component.Ready) + finishCreation(); +else + component.statusChanged.connect(finishCreation); +//![1] - if (sprite == null) { - // Error Handling - console.log("Error loading component:", component.errorsString()); - } else { - sprite.parent = appWindow; - sprite.x = 100; - sprite.y = 100; - // ... - } - //![3] +//![2] +component = Qt.createComponent("Sprite.qml"); +sprite = component.createObject(); + +if (sprite == null) { + // Error Handling + console.log("Error loading component:", component.errorsString()); +} else { + sprite.parent = appWindow; + sprite.x = 100; + sprite.y = 100; + // ... +} +//![2] -//![4] } -//![4] -//![5] createSpriteObjects(); -//![5] diff --git a/src/declarative/qml/qdeclarativecomponent.cpp b/src/declarative/qml/qdeclarativecomponent.cpp index 6ebf470..3ca0707 100644 --- a/src/declarative/qml/qdeclarativecomponent.cpp +++ b/src/declarative/qml/qdeclarativecomponent.cpp @@ -547,7 +547,11 @@ QDeclarativeComponent::QDeclarativeComponent(QDeclarativeComponentPrivate &dd, Q \qmlmethod object Component::createObject() Returns an object instance from this component, or null if object creation fails. - The object will be created in the same context as the component was created in. + The object will be created in the same context as the one in which the component + was created. + + Note that if the returned object is to be displayed, its \c parent must be set to + an existing item in a scene, or else the object will not be visible. */ /*! -- cgit v0.12