From a392c012fda17313948f09574ec01672a8ed2f66 Mon Sep 17 00:00:00 2001 From: Bea Lam Date: Tue, 11 May 2010 17:23:11 +1000 Subject: Doc improvements --- doc/src/declarative/advtutorial.qdoc | 2 +- doc/src/declarative/codingconventions.qdoc | 1 - doc/src/declarative/extending-examples.qdoc | 8 +-- doc/src/declarative/qmlruntime.qdoc | 2 +- src/declarative/util/qdeclarativexmllistmodel.cpp | 68 +++++++++++++++++------ 5 files changed, 55 insertions(+), 26 deletions(-) diff --git a/doc/src/declarative/advtutorial.qdoc b/doc/src/declarative/advtutorial.qdoc index 8f95190..47504ae 100644 --- a/doc/src/declarative/advtutorial.qdoc +++ b/doc/src/declarative/advtutorial.qdoc @@ -105,7 +105,7 @@ is the \l SystemPalette item. This provides access to the Qt system palette and is used to give the button a more native look-and-feel. Notice the anchors for the \c Item, \c Button and \c Text elements are set using -\l {codingconventions.html#Grouped-properties}{group notation} for readability. +\l {qdeclarativeintroduction.html#dot-properties}{group notation} for readability. \section2 Adding \c Button and \c Block components diff --git a/doc/src/declarative/codingconventions.qdoc b/doc/src/declarative/codingconventions.qdoc index d0f873d..4fa7d0c 100644 --- a/doc/src/declarative/codingconventions.qdoc +++ b/doc/src/declarative/codingconventions.qdoc @@ -72,7 +72,6 @@ For example, a hypothetical \e photo QML object would look like this: \snippet doc/src/snippets/declarative/codingconventions/photo.qml 0 -\target Grouped properties \section1 Grouped properties If using multiple properties from a group of properties, diff --git a/doc/src/declarative/extending-examples.qdoc b/doc/src/declarative/extending-examples.qdoc index 307162e..611dac1 100644 --- a/doc/src/declarative/extending-examples.qdoc +++ b/doc/src/declarative/extending-examples.qdoc @@ -64,8 +64,8 @@ element, the C++ class can be named differently, or appear in a namespace. The Person class implementation is quite basic. The property accessors simply return members of the object instance. -The implementation must also be registered using the QML_REGISTER_TYPE() macro. This macro -registers the Person class with QML as a type in the People library version 1.0, +The \c main.cpp file also calls the \c qmlRegisterType() function to +register the \c Person type with QML as a type in the People library version 1.0, and defines the mapping between the C++ and QML class names. \section1 Running the example @@ -159,9 +159,7 @@ directly - an explicit Boy or Girl should be instantiated instead. While we want to disallow instantiating Person from within QML, it still needs to be registered with the QML engine, so that it can be used as a property type -and other types can be coerced to it. To register a type, without defining a -named mapping into QML, we call the QML_REGISTER_NOCREATE_TYPE() macro instead of -the QML_REGISTER_TYPE() macro used previously. +and other types can be coerced to it. \section2 Define Boy and Girl diff --git a/doc/src/declarative/qmlruntime.qdoc b/doc/src/declarative/qmlruntime.qdoc index 23c5c32..10aeac0 100644 --- a/doc/src/declarative/qmlruntime.qdoc +++ b/doc/src/declarative/qmlruntime.qdoc @@ -123,7 +123,7 @@ Such files can be created using \l{Qt Linguist}. - See \l{scripting.html#internationalization} for information about how to make + See the \l{scripting.html#internationalization}{Qt Internationalization} documentation for information about how to make the JavaScript in QML files use translatable strings. Additionally, the QML runtime will load translation files specified on the diff --git a/src/declarative/util/qdeclarativexmllistmodel.cpp b/src/declarative/util/qdeclarativexmllistmodel.cpp index b9afa1f..f02ed16 100644 --- a/src/declarative/util/qdeclarativexmllistmodel.cpp +++ b/src/declarative/util/qdeclarativexmllistmodel.cpp @@ -472,39 +472,71 @@ void QDeclarativeXmlListModelPrivate::clear_role(QDeclarativeListProperty + + ... + + + Item A + Sat, 07 Sep 2010 10:00:01 GMT + + + Item B + Sat, 07 Sep 2010 15:35:01 GMT + + + + \endcode + + Then it could be used to create the following model: - Here is an example of a model containing news from a Yahoo RSS feed: \qml XmlListModel { - source: "http://rss.news.yahoo.com/rss/oceania" + source: "http://www.mysite.com/feed.xml" query: "/rss/channel/item" XmlRole { name: "title"; query: "title/string()" } XmlRole { name: "pubDate"; query: "pubDate/string()" } - XmlRole { name: "description"; query: "description/string()" } } \endqml - You can also define certain roles as "keys" so that the model only adds data - that contains new values for these keys when reload() is called. + The \l {XmlListModel::query}{query} value of "/rss/channel/item" specifies that the XmlListModel should generate + a model item for each \c in the XML document. The XmlRole objects define the + model item attributes; here, each model item will have \c title and \c pubDate + attributes that match the \c title and \c pubDate values of its corresponding \c . - For example, if the roles above were defined like this: + + \section2 Using key XML roles + + You can define certain roles as "keys" so that when reload() is called, + the model will only add and refresh data that contains new values for + these keys. + + For example, if above role for "pubDate" was defined like this instead: \qml - XmlRole { name: "title"; query: "title/string()"; isKey: true } XmlRole { name: "pubDate"; query: "pubDate/string()"; isKey: true } \endqml - Then when reload() is called, the model will only add new items with a - "title" and "pubDate" value combination that is not already present in - the model. + Then when reload() is called, the model will only add and reload + items with a "pubDate" value that is not already + present in the model. - This is useful to provide incremental updates and avoid repainting an - entire model in a view. + This is useful when displaying the contents of XML documents that + are incrementally updated (such as RSS feeds) to avoid repainting the + entire contents of a model in a view. - \sa {QtDeclarative} + If multiple key roles are specified, the model only adds and reload items + with a combined value of all key roles that is not already present in + the model. + + \sa {declarative/xmldata}{XML data example} */ QDeclarativeXmlListModel::QDeclarativeXmlListModel(QObject *parent) @@ -625,8 +657,8 @@ void QDeclarativeXmlListModel::setXml(const QString &xml) /*! \qmlproperty string XmlListModel::query - An absolute XPath query representing the base query for the model items. The query should start with - '/' or '//'. + An absolute XPath query representing the base query for creating model items + from this model's XmlRole objects. The query should start with '/' or '//'. */ QString QDeclarativeXmlListModel::query() const { @@ -747,7 +779,7 @@ void QDeclarativeXmlListModel::componentComplete() Otherwise, items are only added if the model does not already contain items with matching key role values. - \sa XmlRole::isKey + \sa {Using key XML roles}, XmlRole::isKey */ void QDeclarativeXmlListModel::reload() { -- cgit v0.12