doc/src/porting/qt4-interview.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2015 The Qt Company Ltd.
   4 ** Contact: http://www.qt.io/licensing/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   9 ** Commercial License Usage
  10 ** Licensees holding valid commercial Qt licenses may use this file in
  11 ** accordance with the commercial license agreement provided with the
  12 ** Software or, alternatively, in accordance with the terms contained in
  13 ** a written agreement between you and The Qt Company. For licensing terms
  14 ** and conditions see http://www.qt.io/terms-conditions. For further
  15 ** information use the contact form at http://www.qt.io/contact-us.
  16 **
  17 ** GNU Free Documentation License Usage
  18 ** Alternatively, this file may be used under the terms of the GNU Free
  19 ** Documentation License version 1.3 as published by the Free Software
  20 ** Foundation and appearing in the file included in the packaging of
  21 ** this file.  Please review the following information to ensure
  22 ** the GNU Free Documentation License version 1.3 requirements
  23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29     \page qt4-interview.html
  30     \title The Interview Framework
  31
  32     \contentspage {What's New in Qt 4}{Home}
  33     \previouspage The Tulip Container Classes
  34     \nextpage The Arthur Paint System
  35
  36     The Interview classes provide a model/view framework for Qt
  37     applications based on the well known Model-View-Controller design
  38     pattern. In this document, we will describe Qt's model/view
  39     architecture, provide some examples, and show the improvements
  40     offered over Qt 3's item view classes.
  41
  42     \tableofcontents
  43
  44     \section1 Overview of The Model/View Architecture
  45
  46     The model/view architecture is a variation of the Model-View-Controller
  47     (MVC) design pattern, originating from Smalltalk, that is often used when
  48     building user interfaces.
  49
  50     In the model/view architecture, the view and the controller objects are
  51     combined. This still separates the way that data is stored from the way
  52     that it is presented to the user, but provides a simpler framework based
  53     on the same principles. This separation makes it possible to display the
  54     same data in several different views, and to implement new types of views,
  55     without changing the underlying data structures.
  56
  57     User input is handled by \e delegates. The advantage of this approach is
  58     that it allows rendering and editing of individual items of data to be
  59     customized to suit each data type in use.
  60
  61     \table
  62     \row \i \inlineimage modelview-overview.png
  63     \i \bold{The model/view architecture}
  64
  65     The model communicates with a source of data, providing an \e interface
  66     for the other components in the architecture. The nature of the
  67     communication depends on the type of data source, and the way the model
  68     is implemented.
  69
  70     The view obtains \e{model indexes} from the model; these are references
  71     to items of data. By supplying model indexes to the model, the view can
  72     retrieve items of data from the data source.
  73
  74     In standard views, a \e delegate renders the items of data. When an item
  75     is edited, the delegate communicates with the model directly using
  76     model indexes.
  77     \endtable
  78
  79     \section1 Model/View Classes
  80
  81     On a fundamental level, the Interview classes define the interfaces and
  82     common functionality for models, views, and delegates. All implemented
  83     components subclass QAbstractItemModel, QAbstractItemView, or
  84     QAbstractItemDelegate. The use of a common API ensures a level of
  85     interoperability between the components.
  86
  87     \image standard-views.png
  88
  89     Interview provides ready-to-use implementations of views for table,
  90     tree, and list widgets: QTableView, QTreeView, and QListView.
  91     These standard views are suitable for displaying the most common
  92     types of data structures used in applications, and can be used with
  93     the ready-made models supplied with Qt:
  94
  95     \list
  96     \o QStandardItemModel is a minimal convenience model that developers
  97        can use to manage items of data.
  98     \o QFileSystemModel provides directory information for use with QListView
  99        and QTreeView.
 100     \o QStringListModel is a convenience model that can be used to hold
 101        strings for views such as QListView and QComboBox.
 102     \endlist
 103
 104     Two specialized abstract models are provided that can be subclassed
 105     and extended (see the
 106     \l{model-view-programming.html#related-examples}{Model/View Programming}
 107     examples):
 108
 109     \list
 110     \o QAbstractTableModel is a useful starting point for providing a custom
 111        model that can be used with QTableView.
 112     \o QAbstractListModel can be subclassed to produce a list-based model
 113        for use with QListView.
 114     \endlist
 115
 116     Operations on items, such as filtering and sorting, are handled by \e{proxy
 117     models} that allow views to display processed data without having to
 118     copy or modify data obtained from a source model. Interview provides
 119     the QSortFilterProxyModel class to allow items of data from a source model
 120     to be sorted and filtered before they are supplied to views.
 121
 122     Developers who are familiar with the conventional list, tree, and table
 123     widgets may find QListWidget, QTreeWidget, and QTableWidget useful.
 124     These present a simplified interface to the views that does not require a
 125     knowledge of the underlying model/view architecture.
 126
 127     For details about how to use the model/view classes, see the
 128     \l{Model/View Programming} document.
 129
 130     See also the \l{The Qt 4 Database GUI Layer}{Database GUI Layer} document
 131     for information about Qt 4's database models.
 132
 133     \section1 Example Code
 134
 135     To illustrate how the Interview classes are used, we present two
 136     examples that show different aspects of the model/view architecture.
 137
 138     \section2 Sharing a Model Between Views
 139
 140     In this example, we display the contents of a model using two
 141     different views, and share the user's selection between
 142     them. We will use the QFileSystemModel supplied with Qt because it
 143     requires very little configuration, and provides existing data to
 144     the views.
 145
 146     The main() function for this example demonstrates all the
 147     principles involved in setting up a model and two views. We also
 148     share the selection between the two views:
 149
 150     \snippet doc/src/snippets/shareddirmodel/main.cpp 1
 151
 152     In the above function, we construct a directory model to display
 153     the contents of a default directory. The two views are constructed
 154     and given the same model to work with. By default, each view will
 155     maintain and display its own selection of items from the model,
 156     so we explicitly create a new selection that is shared between the
 157     tree view and the list view. As a result, changes to the selection
 158     in either of these views will automatically cause the selection in
 159     the other to change.
 160
 161     \image interview-shareddirmodel.png
 162
 163     The model/view architecture allows us to replace the QFileSystemModel in
 164     this example with a completely different model, one that will perhaps
 165     obtain data from a remote server, or from a database.
 166
 167     \section2 Creating a Custom Model
 168
 169     In this example, we display items of data obtained from a custom list
 170     model using a standard view. The custom model is a subclass of
 171     QAbstractListModel and provides implementations of a core set of
 172     functions.
 173
 174     The complete declaration of our model is as follows:
 175
 176     \snippet doc/src/snippets/stringlistmodel/model.h 0
 177     \snippet doc/src/snippets/stringlistmodel/model.h 1
 178     \codeline
 179     \snippet doc/src/snippets/stringlistmodel/model.h 5
 180
 181     The model takes a list of strings when constructed, and supplies these
 182     to views as required. Since this is only a simple read-only model, we
 183     only need to implement a few functions.
 184
 185     The underlying data structure used to hold the strings is a QStringList.
 186     Since the model maps each item in the list to a row in the model, the
 187     rowCount() function is quite simple:
 188
 189     \snippet doc/src/snippets/stringlistmodel/model.cpp 0
 190
 191     The data() function returns an item of data for each model index
 192     supplied by a view:
 193
 194     \snippet doc/src/snippets/stringlistmodel/model.cpp 1
 195
 196     The data() function returns a QVariant containing the information
 197     referred to by the model index. Items of data are returned to the view,
 198     but only if a number of checks are satisfied; for example, if the view
 199     specifies an invalid model index, the model indicates this by returning
 200     an invalid QVariant.
 201
 202     Vertical and horizontal headers are supplied by the headerData()
 203     function. In this model, the value returned for these items is the row
 204     or column number, depending on the header:
 205
 206     \snippet doc/src/snippets/stringlistmodel/model.cpp 2
 207
 208     We only include an excerpt from the main() function for this short
 209     example:
 210
 211     \snippet doc/src/snippets/stringlistmodel/main.cpp 1
 212     \dots
 213     \snippet doc/src/snippets/stringlistmodel/main.cpp 3
 214
 215     We create a string list to use with the model, and we supply it to the
 216     model when it is constructed. The information in the string list is
 217     made available to the view via the model.
 218
 219     \image stringlistmodel.png
 220
 221     This example shows that it can be easy to populate views with data
 222     from a simple model. The standard models and views planned for
 223     Qt 4 will make the process even easier, and the convenience widgets
 224     supplied provide support for the classic item-based approach.
 225
 226     \section1 What's Changed Since Qt 3?
 227
 228     The table and item view classes in Qt 3 implemented widgets that
 229     both stored data and presented it to the user. These classes were
 230     designed to be easy-to-use and consistent, but were sometimes
 231     difficult to customize and extend.
 232
 233     The equivalent classes in Qt 4 are designed to be extensible while
 234     remaining easy-to-use; the introduction of the model/view
 235     architecture ensures that they will be more consistent than their
 236     predecessors. The view classes provided can be summarized in the
 237     following way:
 238
 239     \list
 240     \i QListView class provides a view widget that looks similar to
 241        Qt 3's QListBox widget, but displays data provided by a model.
 242        It can also be used to display icons in a similar way to Qt 3's
 243        QIconView.
 244     \i The QTableView class is a view widget that displays tabular data
 245        like Qt 3's QTable widget, but uses data provided by a model.
 246     \i The QTreeView class provides a view widget that behaves like
 247        Qt 3's QListView widget, except that it displays data provided
 248        by a model.
 249     \endlist
 250
 251     Since the model takes responsibility for supplying items of data,
 252     and the view takes care of their presentation to the user, we do
 253     not require item classes to represent individual items.
 254     Delegates handle the painting and editing of data obtained from
 255     the model.
 256
 257     Qt continues to provide a number of classic item view widgets with
 258     familiar item-based interfaces that are not based on compatibility
 259     classes:
 260
 261     \list
 262     \i The QListWidget class provides a widget to display a
 263        list of items, as found in Qt 3's QListBox class.
 264     \i The QTreeWidget class implements the equivalent of Qt 3's
 265        QListView class.
 266     \i The QTableWidget class provides comparable functionality to
 267        Qt 3's QTable class.
 268     \endlist
 269
 270     Each of the convenience classes have a corresponding item class:
 271     QListWidgetItem, QTreeWidgetItem, and QTableWidgetItem are the Qt 4
 272     equivalents of Qt 3's QListBoxItem, QListViewItem, and QTableItem
 273     respectively.
 274
 275     The move towards a model/view architecture presents both challenges
 276     and opportunities for developers. Although the approach may appear to
 277     be rather powerful for simple applications, it encourages greater
 278     reuse of components within applications.
 279 */