From 422033971f5d74b8ed7dcf3492379403d4d0eb3d Mon Sep 17 00:00:00 2001 From: Bea Lam Date: Tue, 3 Jul 2012 11:45:26 +1000 Subject: Reorganize "concept" pages in QtQuick docs This removes concepts/topic.qdoc and move this content into individual concept topic pages under individual directories for each concept to avoid having a really long "concepts" index page. This change also: - Moves components.qdoc ("Defining reusable components") into the appdevguide/ since it's not specific to QtQuick features - it's more about how to use a QtQml feature to build QML apps. - Moves the part of qtqml/doc/src/cppintegration/data.qdoc that discusses how to use C++ models with QtQuick views into quick/doc/src/concepts/modelviewsdata/data-cppmodels.qdoc. Change-Id: Id18a1d56acaaac41714c13cbc94bb3b80f337355 Reviewed-by: Chris Adams --- src/qml/doc/src/cppintegration/data.qdoc | 181 ------------------------------- 1 file changed, 181 deletions(-) (limited to 'src/qml/doc/src/cppintegration/data.qdoc') diff --git a/src/qml/doc/src/cppintegration/data.qdoc b/src/qml/doc/src/cppintegration/data.qdoc index cb7af045ab..ef388a1ed5 100644 --- a/src/qml/doc/src/cppintegration/data.qdoc +++ b/src/qml/doc/src/cppintegration/data.qdoc @@ -276,187 +276,6 @@ pointer to a QObject-derived type), the QML engine will assume ownership of it unless the object has had its ownership previously explicitly set (to QQmlEngine::CppOwnership). -\section1 Data Provided In A Custom C++ Model - -Models can be defined in C++ and then made available to QML. This is useful -for exposing existing C++ data models or otherwise complex datasets to QML. - -A C++ model class can be defined as a \l QStringList, a QObjectList or a -\l QAbstractItemModel. The first two are useful for exposing simpler datasets, -while QAbstractItemModel provides a more flexible solution for more complex -models. - -\section2 QStringList-based Model - -A model may be a simple \l QStringList, which provides the contents of the list -via the \e modelData role. - -Here is a ListView with a delegate that references its model item's -value using the \c modelData role: - -\snippet examples/quick/modelviews/stringlistmodel/view.qml 0 - -A Qt application can load this QML document and set the value of \c myModel -to a QStringList: - -\snippet examples/quick/modelviews/stringlistmodel/main.cpp 0 - -The complete example is available in Qt's \l {quick/modelviews/stringlistmodel}{examples/quick/modelviews/stringlistmodel} directory. - -\b{Note:} There is no way for the view to know that the contents of a QStringList -have changed. If the QStringList changes, it will be necessary to reset -the model by calling QQmlContext::setContextProperty() again. - - -\section2 QObjectList-based model - -A list of QObject* values can also be used as a model. A QList provides -the properties of the objects in the list as roles. - -The following application creates a \c DataObject class that with -Q_PROPERTY values that will be accessible as named roles when a -QList is exposed to QML: - -\snippet examples/quick/modelviews/objectlistmodel/dataobject.h 0 -\dots 4 -\snippet examples/quick/modelviews/objectlistmodel/dataobject.h 1 -\codeline -\snippet examples/quick/modelviews/objectlistmodel/main.cpp 0 -\dots - -The QObject* is available as the \c modelData property. As a convenience, -the properties of the object are also made available directly in the -delegate's context. Here, \c view.qml references the \c DataModel properties in -the ListView delegate: - -\snippet examples/quick/modelviews/objectlistmodel/view.qml 0 - -Note the use of the fully qualified access to the \c color property. -The properties of the object are not replicated in the \c model -object, since they are easily available via the \c modelData -object. - -The complete example is available in Qt's \l {quick/modelviews/objectlistmodel}{examples/quick/modelviews/objectlistmodel} directory. - -Note: There is no way for the view to know that the contents of a QList -have changed. If the QList changes, it will be necessary to reset -the model by calling QQmlContext::setContextProperty() again. - - -\section2 QAbstractItemModel - -A model can be defined by subclassing QAbstractItemModel. This is the -best approach if you have a more complex model that cannot be supported -by the other approaches. A QAbstractItemModel can also automatically -notify a QML view when the model data has changed. - -The roles of a QAbstractItemModel subclass can be exposed to QML by calling -QAbstractItemModel::setRoleNames(). The default role names set by Qt are: - -\table -\header -\li Qt Role -\li QML Role Name -\row -\li Qt::DisplayRole -\li display -\row -\li Qt::DecorationRole -\li decoration -\endtable - -Here is an application with a QAbstractListModel subclass named \c AnimalModel -that has \e type and \e size roles. It calls QAbstractItemModel::setRoleNames() to set the -role names for accessing the properties via QML: - -\snippet examples/quick/modelviews/abstractitemmodel/model.h 0 -\dots -\snippet examples/quick/modelviews/abstractitemmodel/model.h 1 -\dots -\snippet examples/quick/modelviews/abstractitemmodel/model.h 2 -\codeline -\snippet examples/quick/modelviews/abstractitemmodel/model.cpp 0 -\codeline -\snippet examples/quick/modelviews/abstractitemmodel/main.cpp 0 -\dots - -This model is displayed by a ListView delegate that accesses the \e type and \e size -roles: - -\snippet examples/quick/modelviews/abstractitemmodel/view.qml 0 - -QML views are automatically updated when the model changes. Remember the model -must follow the standard rules for model changes and notify the view when -the model has changed by using QAbstractItemModel::dataChanged(), -QAbstractItemModel::beginInsertRows(), etc. See the \l {Model subclassing reference} for -more information. - -The complete example is available in Qt's \l {quick/modelviews/abstractitemmodel}{examples/quick/modelviews/abstractitemmodel} directory. - -QAbstractItemModel presents a hierarchy of tables, but the views currently provided by QML -can only display list data. -In order to display child lists of a hierarchical model -the VisualDataModel element provides several properties and functions for use -with models of type QAbstractItemModel: - -\list -\li \e hasModelChildren role property to determine whether a node has child nodes. -\li \l VisualDataModel::rootIndex allows the root node to be specified -\li \l VisualDataModel::modelIndex() returns a QModelIndex which can be assigned to VisualDataModel::rootIndex -\li \l VisualDataModel::parentModelIndex() returns a QModelIndex which can be assigned to VisualDataModel::rootIndex -\endlist - -\section2 Exposing C++ Data Models to QML - -The above examples use QQmlContext::setContextProperty() to set -model values directly in QML components. An alternative to this is to -register the C++ model class as a QML type (either -\l{qtqml-registercpptypes.html}{directly} from a C++ entry-point, or within -the initialization function of a \l{qtqml-modules-cppplugins.html} -{QML C++ plugin}, as shown below). This would allow the model classes to be -created directly as elements within QML: - -\table -\row - -\li -\code -class MyModelPlugin : public QQmlExtensionPlugin -{ -public: - void registerTypes(const char *uri) - { - qmlRegisterType(uri, 1, 0, - "MyModel"); - } -} - -Q_EXPORT_PLUGIN2(mymodelplugin, MyModelPlugin); -\endcode - -\li -\qml -MyModel { - id: myModel - ListElement { someProperty: "some value" } -} -\endqml - -\qml -ListView { - width: 200; height: 250 - model: myModel - delegate: Text { text: someProperty } -} -\endqml - -\endtable - -See \l {Tutorial: Extending QML with C++} for details on writing QML C++ -plugins. - - - -- cgit v1.2.3