diff options
| -rw-r--r-- | doc/src/getting-started/tutorials.qdoc | 12 | ||||
| -rwxr-xr-x | doc/src/images/treeview_sml.png | bin | 0 -> 17419 bytes | |||
| -rwxr-xr-x | doc/src/tutorials/modelview.qdoc | 115 |
3 files changed, 118 insertions, 9 deletions
diff --git a/doc/src/getting-started/tutorials.qdoc b/doc/src/getting-started/tutorials.qdoc index 6e1cee8..0a83170 100644 --- a/doc/src/getting-started/tutorials.qdoc +++ b/doc/src/getting-started/tutorials.qdoc @@ -71,6 +71,18 @@ A guided tour through the translations process, explaining the tools provided for developers, translators and release managers. + + \row + \o{2,1} \l{modelview.html}{\bold{ModelView}} + \o{2,1} + + \row + \o \image treeview_sml.png ModelView + \o This tutorial gives an introduction to ModelView programming using the Qt cross-platform framework + + \o + \o + \row \o{2,1} \l{QTestLib Tutorial}{\bold QTestLib} \o{2,1} \l{qmake Tutorial}{\bold qmake} diff --git a/doc/src/images/treeview_sml.png b/doc/src/images/treeview_sml.png Binary files differnew file mode 100755 index 0000000..fb6de1d --- /dev/null +++ b/doc/src/images/treeview_sml.png diff --git a/doc/src/tutorials/modelview.qdoc b/doc/src/tutorials/modelview.qdoc index 67908b9..bc03f44 100755 --- a/doc/src/tutorials/modelview.qdoc +++ b/doc/src/tutorials/modelview.qdoc @@ -1,12 +1,63 @@ /*! - - \contentspage{modelview.html}{Crash Course in Model/View Programming} \page modelview.html -\title An Introduction to Model/View Programming -Contents: -\tableofcontents + \startpage {index.html}{Qt Reference Documentation} + \contentspage {modelview-index.html}{ModelView Contents} + \nextpage {modelview-part1.html}{Introduction} + \title ModelView Contents Page + \brief An introduction to ModelView programming + + This tutorial gives an introduction to ModelView programming using the Qt + cross-platform framework. + + \image treeview.png + + \omit + It doesn't cover everything; the emphasis is on teaching the programming + philosophy of ModelView programming, and Qt's features are introduced as needed. + Some commonly used features are never used in this tutorial. + \endomit + + In the process, we will learn about some basic technologies provided by Qt, + such as: + + \list + \o The difference between standard and modelview widgets + \o Adapters betweeen forms and models + \o Developing a simple Model/View application + \o Intermediate topics such as: + \list + \o Tree views + \o Selection + \o Predefined models + \o Delegates + \o Debugging with model test + \endlist + \endlist + + If you are completely new to Qt, please read \l{How to Learn Qt} if you + have not already done so. + + The tutorial's source code is located in Qt's \c examples/tutorials/modelview + directory. + + \list 1 + \o \l{modelview-part1.html}{Introduction} + \o \l{modelview-part2.html}{Developing a simple ModelView application} + \o \l{modelview-part3.html}{Intermediate Topics} + \o \l{modelview-part4.html}{Good Sources for Additional Information} + \endlist + +*/ + +/*! + \page modelview-part1.html + \title An Introduction to Model/View Programming + + \raw HTML + <br> + \endraw \section1 1 Introduction Model/View is a technology used to separate data from views in widgets that handle data sets. Standard Widgets are not designed for separating data from views and this is why Qt 4 has two different types of widgets. Both types of widgets look the same, but they interact with data differently. \table @@ -64,6 +115,27 @@ We often prefer editing data stored in tables (e.g. in database tables) in forms Another example of an adapter is \l QCompleter. Qt has QCompleter for providing auto completions in Qt widgets such as \l QComboBox and, as shown below, \l QLineEdit. \l QCompleter uses a model as its data source, so \l QCompleter, in itself, is a very handy adapter. \image qcompleter.png + +*/ + +/*! + + + \page modelview-part2-main-cpp.html + \title main.cpp + \quotefile tutorials/modelview/1_readonly/main.cpp + + +*/ + +/*! + \page modelview-part2.html + \title ModelView Chapter 2 - A Simple Model/View Application + + \raw HTML + <br> + \endraw + \section1 2 A Simple Model/View Application If you want to develop a model/view application, where should you start? We recommend starting with a simple example and extending it step-by-step. This makes understanding the architecture a lot easier. Trying to understand the model/view architecture in detail before invoking the IDE has proven to be less convenient for many developers. It is substantially easier to start with a simple model/view application that has demo data. Give it a try! Simply replace the data in the examples below with your own. @@ -75,7 +147,7 @@ We start with an application that uses a \l QTableView to show data. We will add -------------------------------------------------------------main.cpp--------------------- \snippet examples/tutorials/modelview/1_readonly/main.cpp Quoting ModelView Tutorial -We have the usual \l {tutorials/modelview/1_readonly/main.cpp}{main()} function; +We have the usual \l {modelview-part2-main-cpp.html}{main()} function; -------------------------------------------------------------modelview.h--------------------- \snippet examples/tutorials/modelview/1_readonly/modelview.h Quoting ModelView Tutorial @@ -148,7 +220,7 @@ Each formatting property will be requested from the model with a separate call t \endtable -Refer to Qt documentation to learn more about enum Qt::ItemDataRole's capabilities. +Refer to Qt documentation to learn more about enum Qt::ItemDataRole's capabilities. Now we need to determine how using a seperated model impacts the application's performance, so let's trace how often the view calls the \l{QAbstractItemModel::data()}{data()} method. In order to track how often the view calls the model, we have put a debug statement in the \l{QAbstractItemModel::data()}{data()} method, which logs onto stdio. In our small example, \l{QAbstractItemModel::data()}{data()} will be called 42 times. Each time you hover the cursor over the field, \l{QAbstractItemModel::data()}{data()} will be called again - 7 times for each cell. That's why it is important to make sure that your data is available when \l{QAbstractItemModel::data()}{data()} is invoked and expensive lookup operations are cached. @@ -198,9 +270,20 @@ In the constructor, we fill \c QStringList gridData with 6 items. (one item for \l{QAbstractItemModel::setData()}{setData()} will be called each time the user edits a cell. The \c index parameter tells us which field has been edited and \c value provides the result of the editing process. The role will always be set to \c Qt::EditRole because our cells only contain text. If a checkbox were present and user permissions are set to allow the checkbox to be selected, calls would also be made with the role set to \c Qt::CheckStateRole. \snippet examples/tutorials/modelview/5_edit/mymodel.cpp quoting mymodel_f -Various properties of a cell can be adjusted with \l{QAbstractItemModel::flags()}{flags()}. Returning \c Qt::ItemIsEditable | Qt::ItemIsEnabled is enough to show an editor that a cell has been selected. If editing one cell modifies more data than the data in that particular cell, the model must emit a \l{QAbstractItemModel::dataChanged()}{dataChanged()} signal in order for the data that has been changed to be read. +Various properties of a cell can be adjusted with \l{QAbstractItemModel::flags()}{flags()}. Returning \c Qt::ItemIsEditable | \c Qt::ItemIsEnabled is enough to show an editor that a cell has been selected. If editing one cell modifies more data than the data in that particular cell, the model must emit a \l{QAbstractItemModel::dataChanged()}{dataChanged()} signal in order for the data that has been changed to be read. + +*/ +/*! + \page modelview-part3.html + \title ModelView Chapter 3 - Intermediate Topics + \raw HTML + <br> + \endraw \section1 3 Intermediate Topics + \raw HTML + <br> + \endraw \section2 3.1 TreeView You can convert the example above into an application with a tree view. Simply replace QTableView with QTreeView, which results in a read/write tree. No changes have to be made to the model. The tree won't have any hierarchies because there aren't any hierarchies in the model itself. @@ -288,7 +371,7 @@ The view has a method that replaces the default delegate and installs a custom d \endcode -\l{QStyledItemDelegate::paint()}{paint()} draws stars depending on the content of the underlying data. The data can be looked up with parameter \l{QModelIndex::data()}{index.data()}. \l{QGraphicsLayoutItem::sizeHint()}{sizeHint} specifies the stars dimensions so the the cell will provide enough height and width to accommodate the stars. +\l{QStyledItemDelegate::paint()}{paint()} draws stars depending on the content of the underlying data. The data can be looked up with parameter \l{QModelIndex::data()}{index.data()}. \l{QAbstractItemDelegate::sizeHint()}{sizeHint} specifies the stars dimensions so the the cell will provide enough height and width to accommodate the stars. Writing custom delegates is the right choice if you want to show your data with a custom graphical representation inside the grid of the view class. If you want to leave the grid, you can write a custom view class. @@ -342,7 +425,21 @@ Model/View NG is a research project. You are welcome to checkout the source code \raw HTML <br> \endraw + +*/ + +/*! + \page modelview-part4.html + + \title ModelView Chapter 4 - Good Sources for Additional Information + + \raw HTML + <br> + \endraw \section1 4 Good Sources for Additional Information +\raw HTML +<br> +\endraw \section2 4.1 Books Model/View programming is covered quite extensively in the documentation of Qt but also in several good books. \list 1 |
