From 2051459dd9a257c6492c755a583ff331e7009012 Mon Sep 17 00:00:00 2001 From: Bea Lam Date: Mon, 6 Dec 2010 17:49:04 +1000 Subject: Some doc clarification for components and javascript integration --- doc/src/declarative/javascriptblocks.qdoc | 5 ++--- src/declarative/qml/qdeclarativecomponent.cpp | 28 +++++++++++++++------------ 2 files changed, 18 insertions(+), 15 deletions(-) diff --git a/doc/src/declarative/javascriptblocks.qdoc b/doc/src/declarative/javascriptblocks.qdoc index 41b64da..155bd6e 100644 --- a/doc/src/declarative/javascriptblocks.qdoc +++ b/doc/src/declarative/javascriptblocks.qdoc @@ -94,9 +94,8 @@ Both relative and absolute JavaScript URLs can be imported. In the case of a relative URL, the location is resolved relative to the location of the \l {QML Document} that contains the import. If the script file is not accessible, an error will occur. If the JavaScript needs to be fetched from a network -resource, the QML document has a "Loading" -\l {QDeclarativeComponent::status()}{status} until the script has been -downloaded. +resource, the component's \l {QDeclarativeComponent::status()}{status} is set to +"Loading" until the script has been downloaded. Imported JavaScript files are always qualified using the "as" keyword. The qualifier for JavaScript files must be unique, so there is always a one-to-one diff --git a/src/declarative/qml/qdeclarativecomponent.cpp b/src/declarative/qml/qdeclarativecomponent.cpp index 63bde0f..77fc925 100644 --- a/src/declarative/qml/qdeclarativecomponent.cpp +++ b/src/declarative/qml/qdeclarativecomponent.cpp @@ -147,32 +147,36 @@ class QByteArray; Components are reusable, encapsulated QML elements with well-defined interfaces. Components are often defined by \l {qdeclarativedocuments.html}{component files} - - that is, \c .qml files. The \e Component element allows components to be defined - within QML items rather than in a separate file. This may be useful for reusing - a small component within a QML file, or for defining a component that logically - belongs with other QML components within a file. + that is, \c .qml files. The \e Component element essentially allows QML components + to be defined inline, within a \l {QML Document}{QML document}, rather than as a separate QML file. + This may be useful for reusing a small component within a QML file, or for defining + a component that logically belongs with other QML components within a file. For example, here is a component that is used by multiple \l Loader objects. - It contains a top level \l Rectangle item: + It contains a single item, a \l Rectangle: \snippet doc/src/snippets/declarative/component.qml 0 Notice that while a \l Rectangle by itself would be automatically rendered and displayed, this is not the case for the above rectangle because it is defined inside a \c Component. The component encapsulates the - QML elements within, as if they were defined in a separate \c .qml + QML elements within, as if they were defined in a separate QML file, and is not loaded until requested (in this case, by the two \l Loader objects). - A Component cannot contain anything other - than an \c id and a single top level item. While the \c id is optional, - the top level item is not; you cannot define an empty component. + Defining a \c Component is similar to defining a \l {QML Document}{QML document}. + A QML document has a single top-level item that defines the behaviors and + properties of that component, and cannot define properties or behaviors outside + of that top-level item. In the same way, a \c Component definition contains a single + top level item (which in the above example is a \l Rectangle) and cannot define any + data outside of this item, with the exception of an \e id (which in the above example + is \e redSquare). - The Component element is commonly used to provide graphical components - for views. For example, the ListView::delegate property requires a Component + The \c Component element is commonly used to provide graphical components + for views. For example, the ListView::delegate property requires a \c Component to specify how each list item is to be displayed. - Component objects can also be dynamically created using + \c Component objects can also be created dynamically using \l{QML:Qt::createComponent()}{Qt.createComponent()}. */ -- cgit v0.12