diff options
Diffstat (limited to 'doc/src/porting/qt4-interview.qdoc')
| -rw-r--r-- | doc/src/porting/qt4-interview.qdoc | 279 |
1 files changed, 279 insertions, 0 deletions
diff --git a/doc/src/porting/qt4-interview.qdoc b/doc/src/porting/qt4-interview.qdoc new file mode 100644 index 0000000..af070ba --- /dev/null +++ b/doc/src/porting/qt4-interview.qdoc @@ -0,0 +1,279 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** 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. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page qt4-interview.html + \title The Interview Framework + + \contentspage {What's New in Qt 4}{Home} + \previouspage The Tulip Container Classes + \nextpage The Arthur Paint System + + The Interview classes provide a model/view framework for Qt + applications based on the well known Model-View-Controller design + pattern. In this document, we will describe Qt's model/view + architecture, provide some examples, and show the improvements + offered over Qt 3's item view classes. + + \tableofcontents + + \section1 Overview of The Model/View Architecture + + The model/view architecture is a variation of the Model-View-Controller + (MVC) design pattern, originating from Smalltalk, that is often used when + building user interfaces. + + In the model/view architecture, the view and the controller objects are + combined. This still separates the way that data is stored from the way + that it is presented to the user, but provides a simpler framework based + on the same principles. This separation makes it possible to display the + same data in several different views, and to implement new types of views, + without changing the underlying data structures. + + User input is handled by \e delegates. The advantage of this approach is + that it allows rendering and editing of individual items of data to be + customized to suit each data type in use. + + \table + \row \i \inlineimage modelview-overview.png + \i \bold{The model/view architecture} + + The model communicates with a source of data, providing an \e interface + for the other components in the architecture. The nature of the + communication depends on the type of data source, and the way the model + is implemented. + + The view obtains \e{model indexes} from the model; these are references + to items of data. By supplying model indexes to the model, the view can + retrieve items of data from the data source. + + In standard views, a \e delegate renders the items of data. When an item + is edited, the delegate communicates with the model directly using + model indexes. + \endtable + + \section1 Model/View Classes + + On a fundamental level, the Interview classes define the interfaces and + common functionality for models, views, and delegates. All implemented + components subclass QAbstractItemModel, QAbstractItemView, or + QAbstractItemDelegate. The use of a common API ensures a level of + interoperability between the components. + + \image standard-views.png + + Interview provides ready-to-use implementations of views for table, + tree, and list widgets: QTableView, QTreeView, and QListView. + These standard views are suitable for displaying the most common + types of data structures used in applications, and can be used with + the ready-made models supplied with Qt: + + \list + \o QStandardItemModel is a minimal convenience model that developers + can use to manage items of data. + \o QFileSystemModel provides directory information for use with QListView + and QTreeView. + \o QStringListModel is a convenience model that can be used to hold + strings for views such as QListView and QComboBox. + \endlist + + Two specialized abstract models are provided that can be subclassed + and extended (see the + \l{model-view-programming.html#related-examples}{Model/View Programming} + examples): + + \list + \o QAbstractTableModel is a useful starting point for providing a custom + model that can be used with QTableView. + \o QAbstractListModel can be subclassed to produce a list-based model + for use with QListView. + \endlist + + Operations on items, such as filtering and sorting, are handled by \e{proxy + models} that allow views to display processed data without having to + copy or modify data obtained from a source model. Interview provides + the QSortFilterProxyModel class to allow items of data from a source model + to be sorted and filtered before they are supplied to views. + + Developers who are familiar with the conventional list, tree, and table + widgets may find QListWidget, QTreeWidget, and QTableWidget useful. + These present a simplified interface to the views that does not require a + knowledge of the underlying model/view architecture. + + For details about how to use the model/view classes, see the + \l{Model/View Programming} document. + + See also the \l{The Qt 4 Database GUI Layer}{Database GUI Layer} document + for information about Qt 4's database models. + + \section1 Example Code + + To illustrate how the Interview classes are used, we present two + examples that show different aspects of the model/view architecture. + + \section2 Sharing a Model Between Views + + In this example, we display the contents of a model using two + different views, and share the user's selection between + them. We will use the QFileSystemModel supplied with Qt because it + requires very little configuration, and provides existing data to + the views. + + The main() function for this example demonstrates all the + principles involved in setting up a model and two views. We also + share the selection between the two views: + + \snippet doc/src/snippets/shareddirmodel/main.cpp 1 + + In the above function, we construct a directory model to display + the contents of a default directory. The two views are constructed + and given the same model to work with. By default, each view will + maintain and display its own selection of items from the model, + so we explicitly create a new selection that is shared between the + tree view and the list view. As a result, changes to the selection + in either of these views will automatically cause the selection in + the other to change. + + \image interview-shareddirmodel.png + + The model/view architecture allows us to replace the QFileSystemModel in + this example with a completely different model, one that will perhaps + obtain data from a remote server, or from a database. + + \section2 Creating a Custom Model + + In this example, we display items of data obtained from a custom list + model using a standard view. The custom model is a subclass of + QAbstractListModel and provides implementations of a core set of + functions. + + The complete declaration of our model is as follows: + + \snippet doc/src/snippets/stringlistmodel/model.h 0 + \snippet doc/src/snippets/stringlistmodel/model.h 1 + \codeline + \snippet doc/src/snippets/stringlistmodel/model.h 5 + + The model takes a list of strings when constructed, and supplies these + to views as required. Since this is only a simple read-only model, we + only need to implement a few functions. + + The underlying data structure used to hold the strings is a QStringList. + Since the model maps each item in the list to a row in the model, the + rowCount() function is quite simple: + + \snippet doc/src/snippets/stringlistmodel/model.cpp 0 + + The data() function returns an item of data for each model index + supplied by a view: + + \snippet doc/src/snippets/stringlistmodel/model.cpp 1 + + The data() function returns a QVariant containing the information + referred to by the model index. Items of data are returned to the view, + but only if a number of checks are satisfied; for example, if the view + specifies an invalid model index, the model indicates this by returning + an invalid QVariant. + + Vertical and horizontal headers are supplied by the headerData() + function. In this model, the value returned for these items is the row + or column number, depending on the header: + + \snippet doc/src/snippets/stringlistmodel/model.cpp 2 + + We only include an excerpt from the main() function for this short + example: + + \snippet doc/src/snippets/stringlistmodel/main.cpp 1 + \dots + \snippet doc/src/snippets/stringlistmodel/main.cpp 3 + + We create a string list to use with the model, and we supply it to the + model when it is constructed. The information in the string list is + made available to the view via the model. + + \image stringlistmodel.png + + This example shows that it can be easy to populate views with data + from a simple model. The standard models and views planned for + Qt 4 will make the process even easier, and the convenience widgets + supplied provide support for the classic item-based approach. + + \section1 What's Changed Since Qt 3? + + The table and item view classes in Qt 3 implemented widgets that + both stored data and presented it to the user. These classes were + designed to be easy-to-use and consistent, but were sometimes + difficult to customize and extend. + + The equivalent classes in Qt 4 are designed to be extensible while + remaining easy-to-use; the introduction of the model/view + architecture ensures that they will be more consistent than their + predecessors. The view classes provided can be summarized in the + following way: + + \list + \i QListView class provides a view widget that looks similar to + Qt 3's QListBox widget, but displays data provided by a model. + It can also be used to display icons in a similar way to Qt 3's + QIconView. + \i The QTableView class is a view widget that displays tabular data + like Qt 3's QTable widget, but uses data provided by a model. + \i The QTreeView class provides a view widget that behaves like + Qt 3's QListView widget, except that it displays data provided + by a model. + \endlist + + Since the model takes responsibility for supplying items of data, + and the view takes care of their presentation to the user, we do + not require item classes to represent individual items. + Delegates handle the painting and editing of data obtained from + the model. + + Qt continues to provide a number of classic item view widgets with + familiar item-based interfaces that are not based on compatibility + classes: + + \list + \i The QListWidget class provides a widget to display a + list of items, as found in Qt 3's QListBox class. + \i The QTreeWidget class implements the equivalent of Qt 3's + QListView class. + \i The QTableWidget class provides comparable functionality to + Qt 3's QTable class. + \endlist + + Each of the convenience classes have a corresponding item class: + QListWidgetItem, QTreeWidgetItem, and QTableWidgetItem are the Qt 4 + equivalents of Qt 3's QListBoxItem, QListViewItem, and QTableItem + respectively. + + The move towards a model/view architecture presents both challenges + and opportunities for developers. Although the approach may appear to + be rather powerful for simple applications, it encourages greater + reuse of components within applications. +*/ |