diff options
Diffstat (limited to 'doc/src/qml/c++models.qdoc')
| -rw-r--r-- | doc/src/qml/c++models.qdoc | 208 |
1 files changed, 0 insertions, 208 deletions
diff --git a/doc/src/qml/c++models.qdoc b/doc/src/qml/c++models.qdoc deleted file mode 100644 index e2f2f32b5c..0000000000 --- a/doc/src/qml/c++models.qdoc +++ /dev/null @@ -1,208 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ -/*! -\page qml-c++models.qdoc -\title Exposing C++ Models -\brief exposing Qt C++ models to the runtime - -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 \l QList<QObject*> or a -\l QAbstractItemModel. The first two are useful for exposing simpler datasets, -while QAbstractItemModel provides a more flexible solution for more complex -models. - - -\section1 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/declarative/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/declarative/modelviews/stringlistmodel/main.cpp 0 - - The complete example is available in Qt's \l {declarative/modelviews/stringlistmodel}{examples/declarative/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. - - -\section1 QObjectList-based model - - A list of QObject* values can also be used as a model. A QList<QObject*> 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<DataObject*> is exposed to QML: - - \snippet examples/declarative/modelviews/objectlistmodel/dataobject.h 0 - \dots 4 - \snippet examples/declarative/modelviews/objectlistmodel/dataobject.h 1 - \codeline - \snippet examples/declarative/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/declarative/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 {declarative/modelviews/objectlistmodel}{examples/declarative/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. - - -\section1 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/declarative/modelviews/abstractitemmodel/model.h 0 - \dots - \snippet examples/declarative/modelviews/abstractitemmodel/model.h 1 - \dots - \snippet examples/declarative/modelviews/abstractitemmodel/model.h 2 - \codeline - \snippet examples/declarative/modelviews/abstractitemmodel/model.cpp 0 - \codeline - \snippet examples/declarative/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/declarative/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 {declarative/modelviews/abstractitemmodel}{examples/declarative/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 - -\section1 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 from a QML C++ plugin using -QQmlExtensionPlugin. 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<MyModel>(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: Writing QML extensions with C++} for details on writing QML C++ -plugins. - -*/ |