diff options
author | Frederik Gladhorn <frederik.gladhorn@theqtcompany.com> | 2015-03-31 10:19:05 +0200 |
---|---|---|
committer | Frederik Gladhorn <frederik.gladhorn@theqtcompany.com> | 2015-03-31 10:20:34 +0200 |
commit | efac3cd245e2610924133e304d15bf726f5864f5 (patch) | |
tree | c872124a0ea7c40056b69babaf14478f0cb02ce4 /examples/enginio/widgets/todos-cpp/doc/src/todos-cpp.qdoc | |
parent | 99c09ff33b7516a568455c6980f0f81c59a4fb3a (diff) | |
parent | 30ee95cd19f9a435ce337b4f651175ed2e8ba2e5 (diff) | |
download | qtenginio-efac3cd245e2610924133e304d15bf726f5864f5.tar.gz |
Merge remote-tracking branch 'origin/1.1' into '1.2'v1.2.0-beta1v1.2.01.2.0
Conflicts:
.qmake.conf
LICENSE.LGPLv21
LICENSE.LGPLv3
src/enginio_client/chunkdevice_p.h
src/enginio_client/enginio.h
src/enginio_client/enginiobackendconnection.cpp
src/enginio_client/enginiobackendconnection_p.h
src/enginio_client/enginiobasemodel.h
src/enginio_client/enginiobasemodel_p.h
src/enginio_client/enginioclient.cpp
src/enginio_client/enginioclient.h
src/enginio_client/enginioclient_global.h
src/enginio_client/enginioclient_p.h
src/enginio_client/enginioclientconnection.h
src/enginio_client/enginiodummyreply.cpp
src/enginio_client/enginiodummyreply_p.h
src/enginio_client/enginiofakereply.cpp
src/enginio_client/enginiofakereply_p.h
src/enginio_client/enginioidentity.cpp
src/enginio_client/enginioidentity.h
src/enginio_client/enginiomodel.cpp
src/enginio_client/enginiomodel.h
src/enginio_client/enginiooauth2authentication.h
src/enginio_client/enginioobjectadaptor_p.h
src/enginio_client/enginioreply.cpp
src/enginio_client/enginioreply.h
src/enginio_client/enginioreply_p.h
src/enginio_client/enginioreplystate.h
src/enginio_client/enginiostring.cpp
src/enginio_client/enginiostring_p.h
src/enginio_plugin/enginioplugin.cpp
src/enginio_plugin/enginioplugin_p.h
src/enginio_plugin/enginioqmlclient.cpp
src/enginio_plugin/enginioqmlclient_p.h
src/enginio_plugin/enginioqmlclient_p_p.h
src/enginio_plugin/enginioqmlmodel.cpp
src/enginio_plugin/enginioqmlmodel_p.h
src/enginio_plugin/enginioqmlobjectadaptor_p.h
src/enginio_plugin/enginioqmlreply.cpp
src/enginio_plugin/enginioqmlreply_p.h
tests/auto/common/common.cpp
tests/auto/common/common.h
tests/auto/enginioclient/tst_enginioclient.cpp
tests/auto/enginiomodel/tst_enginiomodel.cpp
tests/auto/files/tst_files.cpp
tests/auto/identity/common/identitycommon.h
tests/auto/identity/oauth2authentication/tst_oauth2authentication.cpp
tests/auto/notifications/tst_notifications.cpp
tests/auto/qmltests/tst_enginioclient.qml
tests/auto/qmltests/tst_enginioreply.qml
tests/auto/qmltests/tst_files.qml
tests/auto/qmltests/tst_identity.qml
tests/auto/qmltests/tst_model.qml
tests/auto/qmltests/tst_qmltest.cpp
tests/auto/qmltests/tst_query.qml
Change-Id: Icb6a167ba58b41e1a8e4d2c8f78213eae9472864
Diffstat (limited to 'examples/enginio/widgets/todos-cpp/doc/src/todos-cpp.qdoc')
-rw-r--r-- | examples/enginio/widgets/todos-cpp/doc/src/todos-cpp.qdoc | 119 |
1 files changed, 80 insertions, 39 deletions
diff --git a/examples/enginio/widgets/todos-cpp/doc/src/todos-cpp.qdoc b/examples/enginio/widgets/todos-cpp/doc/src/todos-cpp.qdoc index 2b40b65..4852c38 100644 --- a/examples/enginio/widgets/todos-cpp/doc/src/todos-cpp.qdoc +++ b/examples/enginio/widgets/todos-cpp/doc/src/todos-cpp.qdoc @@ -27,21 +27,25 @@ /*! \title Enginio C++ Examples - Todos \example todos-cpp - \brief The Todo example shows how to use the \l {EnginioModelCpp}{EnginioModel} with Qt Widgets. + \brief The Todo example shows how to use the \l {EnginioModel} with Qt Widgets. \ingroup enginio-examples \inmodule enginio-qt - In this example, a simple list of objects is displayed in a \l QListView. - Each item in the list is a "To Do" object which can be "done" or "not yet done". - Todos can be added, removed, or altered. + In this example, a list of objects is displayed in a \l QTreeView. + Each item in the list is a \c {Todo} object, which can be marked + \c {Done} or \c {Not done}. A \c {Todo} can be added, removed, + or altered. We will be using the classes and concepts duscussed in + \l {Model/View Programming} {Model/View Programming}. + \image todo-example.png - In this simple schema the objects will have two properties that are added - to the default properties (such as creation date which always exists): - a string "title" and a bool "completed". The object type will be created - when a call to create, or in this case EnginoModel::append(), is made. + In this simple schema, each \c {ToDo} object will have two properties: + a \c {string} named \c {title} and a \c {bool} named \c {completed}. + These properties are added to the default properties e.g.: creation date, + which always exist. + + A \c {Todo} object will look like this in \l {http://json.org} {JSON}: - A todo object will look like this (in JSON): \code { "title": "Buy Milk", @@ -49,54 +53,91 @@ } \endcode - The first step is to create a TodosModel which inherits \l {EnginioModelCpp}{EnginioModel}, - and defines the main roles which will be used. As we are interested in the To Do \c title - and the \c completed information we need to define these two roles. - \snippet todos-cpp/todosmodel.h definition - - By default, views (for example \l QListView) use the \l{Qt::ItemDataRole} role to display or edit the content. - The newly created \l{EnginioModelCpp}{EnginioModel} is empty and defines basic roles. Most roles are created - dynamically, based on the JSON datastructure. They have no predefined value in the \l Qt::ItemDataRole enum. - \l{EnginioModelCpp}{EnginioModel} automatically populates itself as soon as the - \l{EnginioModel::query}{query} and \l{EnginioModel::client}{client} properties have been set. - When the data is downloaded, the model resets itself, and sets up the internal data cache and roles names. - \l{EnginioModelCpp}{EnginioModel} guesses the role names based on heuristics. It may be wrong if not all - objects received from the backend have exactly the same structure. For example, a property can be missing - in certain objects. To protect against such cases, we overload \l{EnginioModel::roleNames()}{roleNames()}. - Overriding \l{EnginioModel::roleNames()}{roleNames()} can also be used to match default Qt roles to the named - ones. + A ToDo object can be created and appended to an EnginioModel using + \l {EnginioModel::append()} {append()}, as shown in + \l {mainwindow_appenditem} {MainWindow::appendItem()}. Alternatively, + if many ToDo objects are to be added to the model all at once, they + can be inserted directly into the server database via the model's + \l {EnginioClient} {Enginio client}. The client is obtained from + the model with \l {EnginioModel::client()} {client()}. Then the + ToDo objects are inserted into the server database with the client's + \l {EnginioClient::create()} {create()} function. The model can then + be reloaded from the server with \l {EnginioModel::reload()} {reload()}. + + But first we must create some infrastructure. Our \c{TodosModel} + class is declared in \l{todos-cpp/todosmodel.h}. It inherits + \l[CPP]{EnginioModel}, which is a \l{QAbstractListModel}{list + model}. We add two roles to the \l {Enginio::Role} {Enginio::Role + enum}, chosen for the new properties, one for the ToDo \c title + and one for marking a ToDo as \c{completed}. We assign enum values + to the new roles, equating \c{TitleRole} to + \l{Enginio::CustomPropertyRole}, which is itself equated to + \l{Qt::UserRole} + 10. \snippet todos-cpp/todosmodel.h definition + + The new roles can be used for displaying and editing the values of + the new properties. Views of the model also use roles from in + \l{Qt::ItemDataRole} enum. The example's view is a \l {QTreeView}, + as shown in the \l{todos-cpp/mainwindow.h} {MainWindow class}, + which holds a pointer to the view, a pointer to the + \l{EnginioClient} {client}, and a pointer to the + \l{todos-cpp/todosmodel.h} {model}. + + A new \l [CPP] {EnginioModel} is empty. It automatically populates itself + from the server, when its \l{EnginioModel::query}{query} and + \l{EnginioModel::client}{client} properties have both been set. In the + example, these properties are set in the constructor for the + \l {todos-cpp/mainwindow.cpp} {main window}. The \l {EnginioClient} is + created first. Then an instance of the \c ToDosModel is created, and its + client is set using EnginioModel::setClient(). Then the query is created + as a QJsonObject, and the model's query is set using EnginioModel::setQuery(). + + Once the ToDo data has been downloaded, the model resets itself, and sets up + the internal data cache and roles names. \l [CPP] {EnginioModel} guesses the + role names based on heuristics. It may be wrong if not all objects received + from the backend have exactly the same structure. For example, a property can + be missing in certain objects. To protect against such cases, we overload + \l{EnginioModel::roleNames()}{roleNames()}. Overriding + \l{EnginioModel::roleNames()}{roleNames()} can also be used to + match default Qt roles to the named ones. \snippet todos-cpp/todosmodel.cpp roleNames - In this example we map the \l Qt::DisplayRole and \l Qt::EditRole to the \c title property in the JSON. - This way the right string is shown by default and editing works as expected. + In this example, we map the \l Qt::DisplayRole and \l Qt::EditRole + to the \c title property in the JSON. This way the right string + is shown by default and editing works as expected. - Remember to always call the base class implementation to avoid situations in which the internal cache is not in sync. + Remember to always call the base class implementation to avoid + situations in which the internal cache is not in sync. - By default \l {EnginioModelCpp}{EnginioModel} operates on \l{QJsonValue}, and that is - what the \l{EnginioModel::data()}{data()} function returns inside the \l QVariant, but standard - views, such as \l QListView, use predefined roles which do not map directly to our roles. - That is why we need to write a mapping between them: + By default \l [CPP] {EnginioModel} operates on \l{QJsonValue}, and + that is what the \l{EnginioModel::data()}{data()} function returns + inside the \l QVariant, but standard views, such as \l QListView, + use predefined roles which do not map directly to our roles. That + is why we need to write a mapping between them: \snippet todos-cpp/todosmodel.cpp data - As we have our model defined, we need to create an instance of \l EnginioClient: + As we have our model defined, we need to create an instance of \l {EnginioClient}: \snippet todos-cpp/mainwindow.cpp client - It is used by the model to connect to the Enginio backend. Next we need to construct - and configure our model too. The configuration is based on two steps, assigning - an \l EnginioClient instance and by creating a query. + It is used by the model to connect to the Enginio backend. Next we + need to construct and configure our model too. The configuration + is based on two steps, assigning an \l {EnginioClient} instance + and by creating a query. \snippet todos-cpp/mainwindow.cpp model - The model has to be assigned to a view. In our case it is a \l QListView. + The model has to be assigned to a view. In this example it is a + \l QTreeView. \snippet todos-cpp/mainwindow.cpp assignModel - To make the application fully functional, a way to add and remove "To Dos" is needed. - To do so, we need to connect the correct buttons to slots for adding a new item: + To make the application fully functional, a way to add and remove + a Todo is needed. To do so, we need to connect the correct + buttons to slots for adding a new item: + \target mainwindow_appenditem \snippet todos-cpp/mainwindow.cpp appendItem and for removing it: |