From cf5d53ac1dc1fa71d32ba199717fcf12fdef185c Mon Sep 17 00:00:00 2001 From: David Boddie Date: Mon, 13 Sep 2010 15:45:25 +0200 Subject: Doc: More work on the declarative API documentation. --- .../graphicsitems/qdeclarativeflickable.cpp | 5 +- .../graphicsitems/qdeclarativegridview.cpp | 40 +++++--- .../graphicsitems/qdeclarativelistview.cpp | 13 ++- .../graphicsitems/qdeclarativeloader.cpp | 8 +- .../graphicsitems/qdeclarativepathview.cpp | 4 +- src/declarative/util/qdeclarativelistmodel.cpp | 107 +++++++++++++++------ 6 files changed, 123 insertions(+), 54 deletions(-) diff --git a/src/declarative/graphicsitems/qdeclarativeflickable.cpp b/src/declarative/graphicsitems/qdeclarativeflickable.cpp index 062bbfb..477c511 100644 --- a/src/declarative/graphicsitems/qdeclarativeflickable.cpp +++ b/src/declarative/graphicsitems/qdeclarativeflickable.cpp @@ -372,11 +372,12 @@ void QDeclarativeFlickablePrivate::updateBeginningEnd() \inlineimage flickable.gif \endfloat - The following example shows a large + The following example shows a small view onto a large image in which the + user can drag or flick the image in order to view different parts of it. - \clearfloat \snippet doc/src/snippets/declarative/flickable.qml document + \clearfloat \section1 Limitations \note Due to an implementation detail, items placed inside a Flickable cannot anchor to it by diff --git a/src/declarative/graphicsitems/qdeclarativegridview.cpp b/src/declarative/graphicsitems/qdeclarativegridview.cpp index a0faf14..f152d0d 100644 --- a/src/declarative/graphicsitems/qdeclarativegridview.cpp +++ b/src/declarative/graphicsitems/qdeclarativegridview.cpp @@ -1070,27 +1070,41 @@ void QDeclarativeGridViewPrivate::flick(AxisData &data, qreal minExtent, qreal m GridView are laid out horizontally or vertically. Grid views are inherently flickable as GridView inherits from \l Flickable. - For example, if there is a simple list model defined in a file \c ContactModel.qml like this: + \section1 Example Usage + + The following example shows the definition of a simple list model defined + in a file called \c ContactModel.qml: \snippet doc/src/snippets/declarative/gridview/ContactModel.qml 0 - Another component can display this model data in a GridView, like this: + \beginfloatright + \inlineimage gridview-simple.png + \endfloat + + This model can be referenced as \c ContactModel in other QML files. See \l{QML Modules} + for more information about creating reusable components like this. + + Another component can display this model data in a GridView, as in the following + example, which creates a \c ContactModel component for its model, and a \l Column element + (containing \l Image and \l Text elements) for its delegate. + \clearfloat \snippet doc/src/snippets/declarative/gridview/gridview.qml import \codeline \snippet doc/src/snippets/declarative/gridview/gridview.qml classdocs simple - \image gridview-simple.png - Here, the GridView creates a \c ContactModel component for its model, and a \l Column element - (containing \l Image and \ Text elements) for its delegate. The view will create a new delegate - for each item in the model. Notice the delegate is able to access the model's \c name and - \c portrait data directly. + \beginfloatright + \inlineimage gridview-highlight.png + \endfloat + + The view will create a new delegate for each item in the model. Note that the delegate + is able to access the model's \c name and \c portrait data directly. An improved grid view is shown below. The delegate is visually improved and is moved into a separate \c contactDelegate component. - + + \clearfloat \snippet doc/src/snippets/declarative/gridview/gridview.qml classdocs advanced - \image gridview-highlight.png The currently selected item is highlighted with a blue \l Rectangle using the \l highlight property, and \c focus is set to \c true to enable keyboard navigation for the grid view. @@ -1099,10 +1113,10 @@ void QDeclarativeGridViewPrivate::flick(AxisData &data, qreal minExtent, qreal m Delegates are instantiated as needed and may be destroyed at any time. State should \e never be stored in a delegate. - \note Views do not enable \e clip automatically. If the view - is not clipped by another item or the screen, it will be necessary - to set \e {clip: true} in order to have the out of view items clipped - nicely. + \note Views do not set the \l{Item::}{clip} property automatically. + If the view is not clipped by another item or the screen, it will be necessary + to set this property to true in order to clip the items that are partially or + fully outside the view. \sa {declarative/modelviews/gridview}{GridView example} */ diff --git a/src/declarative/graphicsitems/qdeclarativelistview.cpp b/src/declarative/graphicsitems/qdeclarativelistview.cpp index 177c5b3..8382970 100644 --- a/src/declarative/graphicsitems/qdeclarativelistview.cpp +++ b/src/declarative/graphicsitems/qdeclarativelistview.cpp @@ -1394,11 +1394,14 @@ void QDeclarativeListViewPrivate::flick(AxisData &data, qreal minExtent, qreal m QAbstractListModel. A ListView has a \l model, which defines the data to be displayed, and - a \l delegate, which defines how the data should be displayed. Items in a - ListView are laid out horizontally or vertically. List views are inherently flickable - as ListView inherits from \l Flickable. + a \l delegate, which defines how the data should be displayed. Items in a + ListView are laid out horizontally or vertically. List views are inherently + flickable because ListView inherits from \l Flickable. - For example, if there is a simple list model defined in a file \c ContactModel.qml like this: + \section1 Example Usage + + The following example shows the definition of a simple list model defined + in a file called \c ContactModel.qml: \snippet doc/src/snippets/declarative/listview/ContactModel.qml 0 @@ -1416,7 +1419,7 @@ void QDeclarativeListViewPrivate::flick(AxisData &data, qreal minExtent, qreal m An improved list view is shown below. The delegate is visually improved and is moved into a separate \c contactDelegate component. - + \snippet doc/src/snippets/declarative/listview/listview.qml classdocs advanced \image listview-highlight.png diff --git a/src/declarative/graphicsitems/qdeclarativeloader.cpp b/src/declarative/graphicsitems/qdeclarativeloader.cpp index 5d71625..1066c2b 100644 --- a/src/declarative/graphicsitems/qdeclarativeloader.cpp +++ b/src/declarative/graphicsitems/qdeclarativeloader.cpp @@ -212,8 +212,8 @@ QDeclarativeLoader::~QDeclarativeLoader() \qmlproperty url Loader::source This property holds the URL of the QML component to instantiate. - Note the QML component must be an \l Item-based component. Loader cannot - load non-visual components. + Note the QML component must be an \l{Item}-based component. The loader + cannot load non-visual components. To unload the currently loaded item, set this property to an empty string, or set \l sourceComponent to \c undefined. @@ -275,8 +275,8 @@ void QDeclarativeLoader::setSource(const QUrl &url) } \endqml - To unload the currently loaded item, set this property to an empty string, - or set \l sourceComponent to \c undefined. + To unload the currently loaded item, set this property to an empty string + or \c undefined. \sa source, progress */ diff --git a/src/declarative/graphicsitems/qdeclarativepathview.cpp b/src/declarative/graphicsitems/qdeclarativepathview.cpp index de3f9fa..dad547f 100644 --- a/src/declarative/graphicsitems/qdeclarativepathview.cpp +++ b/src/declarative/graphicsitems/qdeclarativepathview.cpp @@ -404,14 +404,14 @@ QDeclarativePathView::~QDeclarativePathView() be instantiated, but not considered to be currently on the path. Usually, these items would be set invisible, for example: - \code + \qml Component { Rectangle { visible: PathView.onPath ... } } - \endcode + \endqml It is attached to each instance of the delegate. */ diff --git a/src/declarative/util/qdeclarativelistmodel.cpp b/src/declarative/util/qdeclarativelistmodel.cpp index 60d8aa9..d3cf9c8 100644 --- a/src/declarative/util/qdeclarativelistmodel.cpp +++ b/src/declarative/util/qdeclarativelistmodel.cpp @@ -69,49 +69,67 @@ QDeclarativeListModelParser::ListInstruction *QDeclarativeListModelParser::ListM \since 4.7 \brief The ListModel element defines a free-form list data source. - The ListModel is a simple hierarchy of elements containing data roles. The contents can - be defined dynamically, or explicitly in QML: + The ListModel is a simple container of ListElement definitions, each containing data roles. + The contents can be defined dynamically, or explicitly in QML. - For example: + The number of elements in the model can be obtained from its \l count property. + A number of familiar methods are also provided to manipulate the contents of the + model, including append(), insert(), move(), remove() and set(). These methods + accept dictionaries as their arguments; these are translated to ListElement objects + by the model. - \snippet doc/src/snippets/declarative/listmodel.qml 0 + Elements can be manipulated via the model using the setProperty() method, which + allows the roles of the specified element to be set and changed. + + \section1 Example Usage + + The following example shows a ListModel containing three elements, with the roles + "name" and "cost". - Roles (properties) must begin with a lower-case letter. The above example defines a - ListModel containing three elements, with the roles "name" and "cost". + \beginfloatright + \inlineimage listmodel.png + \endfloat + + \snippet doc/src/snippets/declarative/listmodel.qml 0 - Values must be simple constants - either strings (quoted and optionally within a call to QT_TR_NOOP), - bools (true, false), numbers, or enum values (like Text.AlignHCenter). + \clearfloat + Roles (properties) in each element must begin with a lower-case letter and + should be common to all elements in a model. The ListElement documentation + provides more guidelines for how elements should be defined. - The defined model can be used in views such as ListView: + Since the example model contains an \c id property, it can be referenced + by views, such as the ListView in this example: \snippet doc/src/snippets/declarative/listmodel-simple.qml 0 \dots 8 \snippet doc/src/snippets/declarative/listmodel-simple.qml 1 - \image listmodel.png - It is possible for roles to contain list data. In the example below we create a list of fruit attributes: + It is possible for roles to contain list data. In the following example we + create a list of fruit attributes: \snippet doc/src/snippets/declarative/listmodel-nested.qml model - The delegate below displays all the fruit attributes: + The delegate displays all the fruit attributes: - \snippet doc/src/snippets/declarative/listmodel-nested.qml delegate - \image listmodel-nested.png + \beginfloatright + \inlineimage listmodel-nested.png + \endfloat + \snippet doc/src/snippets/declarative/listmodel-nested.qml delegate - \section2 Modifying list models + \clearfloat + \section1 Modifying List Models The content of a ListModel may be created and modified using the clear(), append(), set() and setProperty() methods. For example: - - \snippet doc/src/snippets/declarative/listmodel-modify.qml delegate - Note that when creating content dynamically the set of available properties cannot be changed - once set. Whatever properties are first added to the model are the - only permitted properties in the model. + \snippet doc/src/snippets/declarative/listmodel-modify.qml delegate + Note that when creating content dynamically the set of available properties + cannot be changed once set. Whatever properties are first added to the model + are the only permitted properties in the model. - \section2 Using threaded list models with WorkerScript + \section1 Using Threaded List Models with WorkerScript ListModel can be used together with WorkerScript access a list model from multiple threads. This is useful if list modifications are @@ -127,16 +145,16 @@ QDeclarativeListModelParser::ListInstruction *QDeclarativeListModelParser::ListM \snippet examples/declarative/threading/threadedlistmodel/dataloader.js 0 -working-with-data - worker script by calling \l WorkerScript::sendMessage(). When this message - is received, \l {WorkerScript::onMessage}{WorkerScript.onMessage()} is invoked in - \tt dataloader.js, which appends the current time to the list model. + The timer in the main example sends messages to the worker script by calling + \l WorkerScript::sendMessage(). When this message is received, + \l{WorkerScript::onMessage}{WorkerScript.onMessage()} is invoked in \c dataloader.js, + which appends the current time to the list model. - Note the call to sync() from the \l {WorkerScript::onMessage}{WorkerScript.onMessage()} handler. - You must call sync() or else the changes made to the list from the external + Note the call to sync() from the \l{WorkerScript::onMessage}{WorkerScript.onMessage()} + handler. You must call sync() or else the changes made to the list from the external thread will not be reflected in the list model in the main thread. - \section3 Limitations + \section1 Limitations If a list model is to be accessed from a WorkerScript, it \bold cannot contain list data. So, the following model cannot be used from a WorkerScript @@ -771,6 +789,39 @@ bool QDeclarativeListModelParser::definesEmptyList(const QString &s) \since 4.7 \brief The ListElement element defines a data item in a ListModel. + List elements are defined inside ListModel definitions, and represent items in a + list that will be displayed using ListView or \l Repeater items. + + List elements are defined like other QML elements except that they contain + a collection of \e role definitions instead of properties. Using the same + syntax as property definitions, roles both define how the data is accessed + and include the data itself. + + The names used for roles must begin with a lower-case letter and should be + common to all elements in a given model. Values must be simple constants; either + strings (quoted and optionally within a call to QT_TR_NOOP), boolean values + (true, false), numbers, or enumeration values (such as AlignText.AlignHCenter). + + \section1 Referencing Roles + + The role names are used by delegates to obtain data from list elements. + Each role name is accessible in the delegate's scope, and refers to the + corresponding role in the current element. Where a role name would be + ambiguous to use, it can be accessed via the \l{ListView::}{model} + property (e.g., \c{model.cost} instead of \c{cost}). + + \section1 Example Usage + + The following model defines a series of list elements, each of which + contain "name" and "cost" roles and their associated values. + + \snippet doc/src/snippets/declarative/qml-data-models/listelements.qml model + + The delegate obtains the name and cost for each element by simply referring + to \c name and \c cost: + + \snippet doc/src/snippets/declarative/qml-data-models/listelements.qml view + \sa ListModel */ -- cgit v0.12