1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the documentation of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 /*!

    43     \group model-view

    44     \title Model/View Classes

    45 */

    46 

    47 /*!

    48     \page model-view-programming.html

    49     \nextpage An Introduction to Model/View Programming

    50     \startpage index.html Qt Reference Documentation

    51 

    52     \title Model/View Programming

    53     \brief A guide to the extensible model/view architecture used by Qt's

    54     item view classes.

    55 

    56     \ingroup frameworks-technologies

    57 

    58     \list

    59     \o \l{An Introduction to Model/View Programming}

    60       \tableofcontents{1 An Introduction to Model/View Programming}

    61     \o \l{Using Models and Views}

    62       \tableofcontents{1 Using Models and Views}

    63     \o \l{Model Classes}

    64       \tableofcontents{1 Model Classes}

    65     \o \l{Creating New Models}

    66       \tableofcontents{1 Creating New Models}

    67     \o \l{View Classes}

    68       \tableofcontents{1 View Classes}

    69     \o \l{Handling Selections in Item Views}

    70       \tableofcontents{1 Handling Selections in Item Views}

    71     \o \l{Delegate Classes}

    72       \tableofcontents{1 Delegate Classes}

    73     \o \l{Item View Convenience Classes}

    74       \tableofcontents{1 Item View Convenience Classes}

    75     \o \l{Using Drag and Drop with Item Views}

    76       \tableofcontents{1 Using Drag and Drop with Item Views}

    77     \o \l{Proxy Models}

    78       \tableofcontents{1 Proxy Models}

    79     \o \l{Model Subclassing Reference}

    80       \tableofcontents{1 Model Subclassing Reference}

    81     \endlist

    82 

    83     \keyword Model/View Classes

    84     \section1 All Model/View Classes

    85 

    86     These classes use the model/view design pattern in which the

    87     underlying data (in the model) is kept separate from the way the data

    88     is presented and manipulated by the user (in the view).

    89 

    90     \annotatedlist model-view

    91 

    92     \section1 Related Examples

    93 

    94     \list

    95     \o \l{itemviews/dirview}{Dir View}

    96     \o \l{itemviews/spinboxdelegate}{Spin Box Delegate}

    97     \o \l{itemviews/pixelator}{Pixelator}

    98     \o \l{itemviews/simpletreemodel}{Simple Tree Model}

    99     \o \l{itemviews/chart}{Chart}

   100     \endlist

   101 */

   102 

   103 /*!

   104     \page model-view-introduction.html

   105     \previouspage Model/View Programming

   106     \nextpage Using Models and Views

   107     \startpage index.html Qt Reference Documentation

   108 

   109     \title An Introduction to Model/View Programming

   110 

   111     \tableofcontents

   112 

   113     Qt 4 introduces a new set of item view classes that use a model/view

   114     architecture to manage the relationship between data and the way it

   115     is presented to the user. The separation of functionality introduced by

   116     this architecture gives developers greater flexibility to customize the

   117     presentation of items, and provides a standard model interface to allow

   118     a wide range of data sources to be used with existing item views.

   119     In this document, we give a brief introduction to the model/view paradigm,

   120     outline the concepts involved, and describe the architecture of the item

   121     view system. Each of the components in the architecture is explained,

   122     and examples are given that show how to use the classes provided.

   123 

   124     \section1 The Model/View Architecture

   125 

   126     Model-View-Controller (MVC) is a design pattern originating from

   127     Smalltalk that is often used when building user interfaces.

   128     In \l{Design Patterns}, Gamma et al. write:

   129 

   130     \quotation

   131     MVC consists of three kinds of objects. The Model is the application

   132     object, the View is its screen presentation, and the Controller defines

   133     the way the user interface reacts to user input. Before MVC, user

   134     interface designs tended to lump these objects together. MVC decouples

   135     them to increase flexibility and reuse.

   136     \endquotation

   137 

   138     If the view and the controller objects are combined, the result is

   139     the model/view architecture. This still separates the way that data

   140     is stored from the way that it is presented to the user, but provides

   141     a simpler framework based on the same principles. This separation

   142     makes it possible to display the same data in several different views,

   143     and to implement new types of views, without changing the underlying

   144     data structures.

   145     To allow flexible handling of user input, we introduce the concept of

   146     the \e delegate. The advantage of having a delegate in this framework

   147     is that it allows the way items of data are rendered and edited to be

   148     customized.

   149 

   150     \table

   151     \row \i \inlineimage modelview-overview.png

   152     \i \bold{The model/view architecture}

   153 

   154     The model communicates with a source of data, providing an \e interface

   155     for the other components in the architecture. The nature of the

   156     communication depends on the type of data source, and the way the model

   157     is implemented.

   158 

   159     The view obtains \e{model indexes} from the model; these are references

   160     to items of data. By supplying model indexes to the model, the view can

   161     retrieve items of data from the data source.

   162 

   163     In standard views, a \e delegate renders the items of data. When an item

   164     is edited, the delegate communicates with the model directly using

   165     model indexes.

   166     \endtable

   167 

   168     Generally, the model/view classes can be separated into the three groups

   169     described above: models, views, and delegates. Each of these components

   170     is defined by \e abstract classes that provide common interfaces and,

   171     in some cases, default implementations of features.

   172     Abstract classes are meant to be subclassed in order to provide the full

   173     set of functionality expected by other components; this also allows

   174     specialized components to be written.

   175 

   176     Models, views, and delegates communicate with each other using \e{signals

   177     and slots}:

   178 

   179     \list

   180     \o Signals from the model inform the view about changes to the data

   181        held by the data source.

   182     \o Signals from the view provide information about the user's interaction

   183        with the items being displayed.

   184     \o Signals from the delegate are used during editing to tell the

   185        model and view about the state of the editor.

   186     \endlist

   187 

   188     \section2 Models

   189 

   190     All item models are based on the QAbstractItemModel class. This class

   191     defines an interface that is used by views and delegates to access data.

   192     The data itself does not have to be stored in the model; it can be held

   193     in a data structure or repository provided by a separate class, a file,

   194     a database, or some other application component.

   195 

   196     The basic concepts surrounding models are presented in the section

   197     on \l{Model Classes}.

   198 

   199     QAbstractItemModel

   200     provides an interface to data that is flexible enough to handle views

   201     that represent data in the form of tables, lists, and trees. However,

   202     when implementing new models for list and table-like data structures,

   203     the QAbstractListModel and QAbstractTableModel classes are better

   204     starting points because they provide appropriate default implementations

   205     of common functions. Each of these classes can be subclassed to provide

   206     models that support specialized kinds of lists and tables.

   207 

   208     The process of subclassing models is discussed in the section on

   209     \l{Creating New Models}.

   210 

   211     Qt provides some ready-made models that can be used to handle items of

   212     data:

   213 

   214     \list

   215     \o QStringListModel is used to store a simple list of QString items.

   216     \o QStandardItemModel manages more complex tree structures of items, each

   217        of which can contain arbitrary data.

   218     \o QFileSystemModel provides information about files and directories in the

   219        local filing system.

   220     \o QSqlQueryModel, QSqlTableModel, and QSqlRelationalTableModel are used

   221        to access databases using model/view conventions.

   222     \endlist

   223 

   224     If these standard models do not meet your requirements, you can subclass

   225     QAbstractItemModel, QAbstractListModel, or QAbstractTableModel to create

   226     your own custom models.

   227 

   228     \section2 Views

   229 

   230     Complete implementations are provided for different kinds of

   231     views: QListView displays a list of items, QTableView displays data

   232     from a model in a table, and QTreeView shows model items of data in a

   233     hierarchical list. Each of these classes is based on the

   234     QAbstractItemView abstract base class. Although these classes are

   235     ready-to-use implementations, they can also be subclassed to provide

   236     customized views.

   237 

   238     The available views are examined in the section on \l{View Classes}.

   239 

   240     \section2 Delegates

   241 

   242     QAbstractItemDelegate is the abstract base class for delegates in the

   243     model/view framework. Since Qt 4.4, the default delegate implementation is

   244     provided by QStyledItemDelegate, and this is used as the default delegate

   245     by Qt's standard views. However, QStyledItemDelegate and QItemDelegate are

   246     independent alternatives to painting and providing editors for items in

   247     views. The difference between them is that QStyledItemDelegate uses the

   248     current style to paint its items. We therefore recommend using

   249     QStyledItemDelegate as the base class when implementing custom delegates or

   250     when working with Qt style sheets.

   251 

   252     Delegates are described in the section on \l{Delegate Classes}.

   253 

   254     \section2 Sorting

   255 

   256     There are two ways of approaching sorting in the model/view

   257     architecture; which approach to choose depends on your underlying

   258     model.

   259 

   260     If your model is sortable, i.e, if it reimplements the

   261     QAbstractItemModel::sort() function, both QTableView and QTreeView

   262     provide an API that allows you to sort your model data

   263     programmatically. In addition, you can enable interactive sorting

   264     (i.e. allowing the users to sort the data by clicking the view's

   265     headers), by connecting the QHeaderView::sortIndicatorChanged() signal

   266     to the QTableView::sortByColumn() slot or the

   267     QTreeView::sortByColumn() slot, respectively.

   268 

   269     The alternative approach, if your model do not have the required

   270     interface or if you want to use a list view to present your data,

   271     is to use a proxy model to transform the structure of your model

   272     before presenting the data in the view. This is covered in detail

   273     in the section on \l {Proxy Models}.

   274 

   275     \section2 Convenience Classes

   276 

   277     A number of \e convenience classes are derived from the standard view

   278     classes for the benefit of applications that rely on Qt's item-based

   279     item view and table classes. They are not intended to be subclassed,

   280     but simply exist to provide a familiar interface to the equivalent classes

   281     in Qt 3.

   282     Examples of such classes include \l QListWidget, \l QTreeWidget, and

   283     \l QTableWidget; these provide similar behavior to the \c QListBox,

   284     \c QListView, and \c QTable classes in Qt 3.

   285 

   286     These classes are less flexible than the view classes, and cannot be

   287     used with arbitrary models. We recommend that you use a model/view

   288     approach to handling data in item views unless you strongly need an

   289     item-based set of classes.

   290 

   291     If you wish to take advantage of the features provided by the model/view

   292     approach while still using an item-based interface, consider using view

   293     classes, such as QListView, QTableView, and QTreeView with

   294     QStandardItemModel.

   295 

   296     \section1 The Model/View Components

   297 

   298     The following sections describe the way in which the model/view pattern

   299     is used in Qt. Each section provides an example of use, and is followed

   300     by a section showing how you can create new components.

   301 */

   302 

   303 /*!

   304     \page model-view-using.html

   305     \contentspage model-view-programming.html Contents

   306     \previouspage An Introduction to Model/View Programming

   307     \nextpage Model Classes

   308 

   309     \title Using Models and Views

   310 

   311     \tableofcontents

   312 

   313     \section1 Introduction

   314 

   315     Two of the standard models provided by Qt are QStandardItemModel and

   316     QFileSystemModel. QStandardItemModel is a multi-purpose model that can be

   317     used to represent various different data structures needed by list, table,

   318     and tree views. This model also holds the items of data.

   319     QFileSystemModel is a model that maintains information about the contents

   320     of a directory. As a result, it does not hold any items of data itself, but

   321     simply represents files and directories on the local filing system.

   322 

   323     QFileSystemModel provides a ready-to-use model to experiment with, and can be

   324     easily configured to use existing data. Using this model, we can show how

   325     to set up a model for use with ready-made views, and explore how to

   326     manipulate data using model indexes.

   327 

   328     \section1 Using Views with an Existing Model

   329 

   330     The QListView and QTreeView classes are the most suitable views

   331     to use with QFileSystemModel. The example presented below displays the

   332     contents of a directory in a tree view next to the same information in

   333     a list view. The views share the user's selection so that the selected

   334     items are highlighted in both views.

   335 

   336     \img shareddirmodel.png

   337 

   338     We set up a QFileSystemModel so that it is ready for use, and create some

   339     views to display the contents of a directory. This shows the simplest

   340     way to use a model. The construction and use of the model is

   341     performed from within a single \c main() function:

   342 

   343     \snippet doc/src/snippets/shareddirmodel/main.cpp 0

   344 

   345     The model is set up to use data from a certain file system. The call to

   346     \l{QFileSystemModel::}{setRootPath()} tell the model which drive on the

   347     file system to expose to the views.

   348 

   349     We create two views so that we can examine the items held in the model in two

   350     different ways:

   351 

   352     \snippet doc/src/snippets/shareddirmodel/main.cpp 5

   353 

   354     The views are constructed in the same way as other widgets. Setting up

   355     a view to display the items in the model is simply a matter of calling its

   356     \l{QAbstractItemView::setModel()}{setModel()} function with the directory

   357     model as the argument. We filter the data supplied by the model by calling

   358     the \l{QAbstractItemView::}{setRootIndex()} function on each view, passing

   359     a suitable \e{model index} from the file system model for the current

   360     directory.

   361 

   362     The \c index() function used in this case is unique to QFileSystemModel; we

   363     supply it with a directory and it returns a model index. Model indexes are

   364     discussed in the \l{Model Classes} chapter.

   365 

   366     The rest of the function just displays the views within a splitter

   367     widget, and runs the application's event loop:

   368 

   369     \snippet doc/src/snippets/shareddirmodel/main.cpp 8

   370 

   371     In the above example, we neglected to mention how to handle selections

   372     of items. This subject is covered in more detail in the chapter on

   373     \l{Handling Selections in Item Views}. Before examining how selections

   374     are handled, you may find it useful to read the \l{Model Classes} chapter

   375     which describes the concepts used in the model/view framework.

   376 */

   377 

   378 /*!

   379     \page model-view-model.html

   380     \contentspage model-view-programming.html Contents

   381     \previouspage Using Models and Views

   382     \nextpage Creating New Models

   383 

   384     \title Model Classes

   385 

   386     \tableofcontents

   387 

   388     \section1 Basic Concepts

   389 

   390     In the model/view architecture, the model provides a standard interface

   391     that views and delegates use to access data. In Qt, the standard

   392     interface is defined by the QAbstractItemModel class. No matter how the

   393     items of data are stored in any underlying data structure, all subclasses

   394     of QAbstractItemModel represent the data as a hierarchical structure

   395     containing tables of items. Views use this \e convention to access items

   396     of data in the model, but they are not restricted in the way that they

   397     present this information to the user.

   398 

   399     \image modelview-models.png

   400 

   401     Models also notify any attached views about changes to data through the

   402     signals and slots mechanism.

   403 

   404     This chapter describes some basic concepts that are central to the way

   405     item of data are accessed by other components via a model class. More

   406     advanced concepts are discussed in later chapters.

   407 

   408     \section2 Model Indexes

   409 

   410     To ensure that the representation of the data is kept separate from the

   411     way it is accessed, the concept of a \e{model index} is introduced. Each

   412     piece of information that can be obtained via a model is represented by

   413     a model index. Views and delegates use these indexes to request items of

   414     data to display.

   415 

   416     As a result, only the model needs to know how to obtain data, and the type

   417     of data managed by the model can be defined fairly generally. Model indexes

   418     contain a pointer to the model that created them, and this prevents

   419     confusion when working with more than one model.

   420 

   421     \snippet doc/src/snippets/code/doc_src_model-view-programming.qdoc 0

   422 

   423     Model indexes provide \e temporary references to pieces of information, and

   424     can be used to retrieve or modify data via the model. Since models may

   425     reorganize their internal structures from time to time, model indexes may

   426     become invalid, and \e{should not be stored}. If a long-term reference to a

   427     piece of information is required, a \e{persistent model index} must be

   428     created. This provides a reference to the information that the model keeps

   429     up-to-date. Temporary model indexes are provided by the QModelIndex class,

   430     and persistent model indexes are provided by the QPersistentModelIndex

   431     class.

   432 

   433     To obtain a model index that corresponds to an item of data, three

   434     properties must be specified to the model: a row number, a column number,

   435     and the model index of a parent item. The following sections describe

   436     and explain these properties in detail.

   437 

   438     \section2 Rows and Columns

   439 

   440     In its most basic form, a model can be accessed as a simple table in which

   441     items are located by their row and column numbers. \e{This does not mean

   442     that the underlying pieces of data are stored in an array structure}; the

   443     use of row and column numbers is only a convention to allow components to

   444     communicate with each other. We can retrieve information about any given

   445     item by specifying its row and column numbers to the model, and we receive

   446     an index that represents the item:

   447 

   448     \snippet doc/src/snippets/code/doc_src_model-view-programming.qdoc 1

   449 

   450     Models that provide interfaces to simple, single level data structures like

   451     lists and tables do not need any other information to be provided but, as

   452     the above code indicates, we need to supply more information when obtaining

   453     a model index.

   454 

   455     \table

   456     \row \i \inlineimage modelview-tablemodel.png

   457     \i \bold{Rows and columns}

   458 

   459     The diagram shows a representation of a basic table model in which each

   460     item is located by a pair of row and column numbers. We obtain a model

   461     index that refers to an item of data by passing the relevant row and

   462     column numbers to the model.

   463 

   464     \snippet doc/src/snippets/code/doc_src_model-view-programming.qdoc 2

   465 

   466     Top level items in a model are always referenced by specifying

   467     \c QModelIndex() as their parent item. This is discussed in the next

   468     section.

   469     \endtable

   470 

   471     \section2 Parents of Items

   472 

   473     The table-like interface to item data provided by models is ideal when

   474     using data in a table or list view; the row and column number system maps

   475     exactly to the way the views display items. However, structures such as

   476     tree views require the model to expose a more flexible interface to the

   477     items within. As a result, each item can also be the parent of another

   478     table of items, in much the same way that a top-level item in a tree view

   479     can contain another list of items.

   480 

   481     When requesting an index for a model item, we must provide some information

   482     about the item's parent. Outside the model, the only way to refer to an

   483     item is through a model index, so a parent model index must also be given:

   484 

   485     \snippet doc/src/snippets/code/doc_src_model-view-programming.qdoc 3

   486 

   487     \table

   488     \row \i \inlineimage modelview-treemodel.png

   489     \i \bold{Parents, rows, and columns}

   490 

   491     The diagram shows a representation of a tree model in which each item is

   492     referred to by a parent, a row number, and a column number.

   493 

   494     Items "A" and "C" are represented as top-level siblings in the model:

   495 

   496     \snippet doc/src/snippets/code/doc_src_model-view-programming.qdoc 4

   497 

   498     Item "A" has a number of children. A model index for item "B" is

   499     obtained with the following code:

   500 

   501     \snippet doc/src/snippets/code/doc_src_model-view-programming.qdoc 5

   502     \endtable

   503 

   504     \section2 Item Roles

   505 

   506     Items in a model can perform various \e roles for other components,

   507     allowing different kinds of data to be supplied for different situations.

   508     For example, Qt::DisplayRole is used to access a string that can be

   509     displayed as text in a view. Typically, items contain data for a number of

   510     different roles, and the standard roles are defined by Qt::ItemDataRole.

   511 

   512     We can ask the model for the item's data by passing it the model index

   513     corresponding to the item, and by specifying a role to obtain the type

   514     of data we want:

   515 

   516     \snippet doc/src/snippets/code/doc_src_model-view-programming.qdoc 6

   517 

   518     \table

   519     \row \i \inlineimage modelview-roles.png

   520     \i \bold{Item roles}

   521 

   522     The role indicates to the model which type of data is being referred to.

   523     Views can display the roles in different ways, so it is important to

   524     supply appropriate information for each role.

   525 

   526     The \l{Creating New Models} section covers some specific uses of roles in

   527     more detail.

   528     \endtable

   529 

   530     Most common uses for item data are covered by the standard roles defined in

   531     Qt::ItemDataRole. By supplying appropriate item data for each role, models

   532     can provide hints to views and delegates about how items should be

   533     presented to the user. Different kinds of views have the freedom to

   534     interpret or ignore this information as required. It is also possible to

   535     define additional roles for application-specific purposes.

   536 

   537     \section2 Summary of Concepts

   538 

   539     \list

   540     \o Model indexes give views and delegates information about the location

   541        of items provided by models in a way that is independent of any

   542        underlying data structures.

   543     \o Items are referred to by their row and column numbers, and by the model

   544        index of their parent items.

   545     \o Model indexes are constructed by models at the request of other

   546        components, such as views and delegates.

   547     \o If a valid model index is specified for the parent item when an index is

   548        requested using \l{QAbstractItemModel::index()}{index()}, the index

   549        returned will refer to an item beneath that parent item in the

   550        model.

   551        The index obtained refers to a child of that item.

   552     \o If an invalid model index is specified for the parent item when an index

   553        is requested using \l{QAbstractItemModel::index()}{index()}, the index

   554        returned will refer to a top-level item in the model.

   555     \o The \l{Qt::ItemDataRole}{role} distinguishes between the

   556        different kinds of data associated with an item.

   557     \endlist

   558 

   559     \section2 Using Model Indexes

   560 

   561     To demonstrate how data can be retrieved from a model, using model

   562     indexes, we set up a QFileSystemModel without a view and display the

   563     names of files and directories in a widget.

   564     Although this does not show a normal way of using a model, it demonstrates

   565     the conventions used by models when dealing with model indexes.

   566 

   567     We construct a file system model in the following way:

   568 

   569     \snippet doc/src/snippets/simplemodel-use/main.cpp 0

   570 

   571     In this case, we set up a default QFileSystemModel, obtain a parent index

   572     using a specific implementation of \l{QFileSystemModel::}{index()}

   573     provided by that model, and we count the number of rows in the model using

   574     the \l{QFileSystemModel::}{rowCount()} function.

   575 

   576     For simplicity, we are only interested in the items in the first column

   577     of the model. We examine each row in turn, obtaining a model index for

   578     the first item in each row, and read the data stored for that item

   579     in the model.

   580 

   581     \snippet doc/src/snippets/simplemodel-use/main.cpp 1

   582 

   583     To obtain a model index, we specify the row number, column number (zero

   584     for the first column), and the appropriate model index for the parent

   585     of all the items that we want.

   586     The text stored in each item is retrieved using the model's

   587     \l{QFileSystemModel::}{data()} function. We specify the model index and

   588     the \l{Qt::ItemDataRole}{DisplayRole} to obtain data for the

   589     item in the form of a string.

   590 

   591     \snippet doc/src/snippets/simplemodel-use/main.cpp 2

   592     \codeline

   593     \snippet doc/src/snippets/simplemodel-use/main.cpp 3

   594 

   595     The above example demonstrates the basic principles used to retrieve

   596     data from a model:

   597 

   598     \list

   599     \i The dimensions of a model can be found using

   600        \l{QAbstractItemModel::rowCount()}{rowCount()} and

   601        \l{QAbstractItemModel::columnCount()}{columnCount()}.

   602        These functions generally require a parent model index to be

   603        specified.

   604     \i Model indexes are used to access items in the model. The row, column,

   605        and parent model index are needed to specify the item.

   606     \i To access top-level items in a model, specify a null model index

   607        as the parent index with \c QModelIndex().

   608     \i Items contain data for different roles. To obtain the data for a

   609        particular role, both the model index and the role must be supplied

   610        to the model.

   611     \endlist

   612 

   613 

   614     \section1 Further Reading

   615 

   616     New models can be created by implementing the standard interface provided

   617     by QAbstractItemModel. In the \l{Creating New Models} chapter, we will

   618     demonstrate this by creating a convenient ready-to-use model for holding

   619     lists of strings.

   620 */

   621 

   622 /*!

   623     \page model-view-view.html

   624     \contentspage model-view-programming.html Contents

   625     \previouspage Creating New Models

   626     \nextpage Handling Selections in Item Views

   627 

   628     \title View Classes

   629 

   630     \tableofcontents

   631 

   632     \section1 Concepts

   633 

   634     In the model/view architecture, the view obtains items of data from the

   635     model and presents them to the user. The way that the data is

   636     presented need not resemble the representation of the data provided by

   637     the model, and may be \e{completely different} from the underlying data

   638     structure used to store items of data.

   639 

   640     The separation of content and presentation is achieved by the use of a

   641     standard model interface provided by QAbstractItemModel, a standard view

   642     interface provided by QAbstractItemView, and the use of model indexes

   643     that represent items of data in a general way.

   644     Views typically manage the overall layout of the data obtained from

   645     models. They may render individual items of data themselves, or use

   646     \l{Delegate Classes}{delegates} to handle both rendering and editing

   647     features.

   648 

   649     As well as presenting data, views handle navigation between items,

   650     and some aspects of item selection. The views also implement basic

   651     user interface features, such as context menus and drag and drop.

   652     A view can provide default editing facilities for items, or it may

   653     work with a \l{Delegate Classes}{delegate} to provide a custom

   654     editor.

   655 

   656     A view can be constructed without a model, but a model must be

   657     provided before it can display useful information. Views keep track of

   658     the items that the user has selected through the use of

   659     \l{Handling Selections in Item Views}{selections} which can be maintained

   660     separately for each view, or shared between multiple views.

   661 

   662     Some views, such as QTableView and QTreeView, display headers as well

   663     as items. These are also implemented by a view class, QHeaderView.

   664     Headers usually access the same model as the view that contains them.

   665     They retrieve data from the model using the

   666     \l{QAbstractItemModel::headerData()} function, and usually display

   667     header information in the form of a label. New headers can be

   668     subclassed from the QHeaderView class to provide more specialized

   669     labels for views.

   670 

   671     \section1 Using an Existing View

   672 

   673     Qt provides three ready-to-use view classes that present data from

   674     models in ways that are familiar to most users.

   675     QListView can display items from a model as a simple list, or in the

   676     form of a classic icon view. QTreeView displays items from a

   677     model as a hierarchy of lists, allowing deeply nested structures to be

   678     represented in a compact way. QTableView presents items from a model

   679     in the form of a table, much like the layout of a spreadsheet

   680     application.

   681 

   682     \img standard-views.png

   683 

   684     The default behavior of the standard views shown above should be

   685     sufficient for most applications. They provide basic editing

   686     facilities, and can be customized to suit the needs of more specialized

   687     user interfaces.

   688 

   689     \section2 Using a Model

   690 

   691     We take the string list model that \l{Creating New Models}{we created as

   692     an example model}, set it up with some data, and construct a view to

   693     display the contents of the model. This can all be performed within a

   694     single function:

   695 

   696     \snippet doc/src/snippets/stringlistmodel/main.cpp 0

   697 

   698     Note that the \c StringListModel is declared as a \l QAbstractItemModel.

   699     This allows us to use the abstract interface to the model, and

   700     ensures that the code will still work even if we replace the string list

   701     model with a different model in the future.

   702 

   703     The list view provided by \l QListView is sufficient for presenting

   704     the items in the string list model. We construct the view, and set up

   705     the model using the following lines of code:

   706 

   707     \snippet doc/src/snippets/stringlistmodel/main.cpp 2

   708     \snippet doc/src/snippets/stringlistmodel/main.cpp 4

   709 

   710     The view is shown in the normal way:

   711 

   712     \snippet doc/src/snippets/stringlistmodel/main.cpp 5

   713 

   714     The view renders the contents of a model, accessing data via the model's

   715     interface. When the user tries to edit an item, the view uses a default

   716     delegate to provide an editor widget.

   717 

   718     \img stringlistmodel.png

   719 

   720     The above image shows how a QListView represents the data in the string

   721     list model. Since the model is editable, the view automatically allows

   722     each item in the list to be edited using the default delegate.

   723 

   724     \section2 Using Multiple Views onto the Same Model

   725 

   726     Providing multiple views onto the same model is simply a matter of

   727     setting the same model for each view. In the following code we create

   728     two table views, each using the same simple table model which we have

   729     created for this example:

   730 

   731     \snippet doc/src/snippets/sharedtablemodel/main.cpp 0

   732     \codeline

   733     \snippet doc/src/snippets/sharedtablemodel/main.cpp 1

   734 

   735     The use of signals and slots in the model/view architecture means that

   736     changes to the model can be propagated to all the attached views,

   737     ensuring that we can always access the same data regardless of the

   738     view being used.

   739 

   740     \img sharedmodel-tableviews.png

   741 

   742     The above image shows two different views onto the same model, each

   743     containing a number of selected items. Although the data from the model

   744     is shown consistently across view, each view maintains its own internal

   745     selection model. This can be useful in certain situations but, for

   746     many applications, a shared selection model is desirable.

   747 

   748     \section1 Handling Selections of Items

   749 

   750     The mechanism for handling selections of items within views is provided

   751     by the \l QItemSelectionModel class. All of the standard views construct

   752     their own selection models by default, and interact with them in the

   753     normal way. The selection model being used by a view can be obtained

   754     through the \l{QAbstractItemView::selectionModel()}{selectionModel()}

   755     function, and a replacement selection model can be specified with

   756     \l{QAbstractItemView::setSelectionModel()}{setSelectionModel()}.

   757     The ability to control the selection model used by a view is useful

   758     when we want to provide multiple consistent views onto the same model

   759     data.

   760 

   761     Generally, unless you are subclassing a model or view, you will not

   762     need to manipulate the contents of selections directly. However, the

   763     interface to the selection model can be accessed, if required, and

   764     this is explored in the chapter on

   765     \l{Handling Selections in Item Views}.

   766 

   767     \section2 Sharing Selections Between Views

   768 

   769     Although it is convenient that the view classes provide their own

   770     selection models by default, when we use more than one view onto the

   771     same model it is often desirable that both the model's data and the

   772     user's selection are shown consistently in all views.

   773     Since the view classes allow their internal selection models to be

   774     replaced, we can achieve a unified selection between views with the

   775     following line:

   776 

   777     \snippet doc/src/snippets/sharedtablemodel/main.cpp 2

   778 

   779     The second view is given the selection model for the first view.

   780     Both views now operate on the same selection model, keeping both

   781     the data and the selected items synchronized.

   782 

   783     \img sharedselection-tableviews.png

   784 

   785     In the example shown above, two views of the same type were used to

   786     display the same model's data. However, if two different types of view

   787     were used, the selected items may be represented very differently in

   788     each view; for example, a contiguous selection in a table view can be

   789     represented as a fragmented set of highlighted items in a tree view.

   790 

   791 */

   792 

   793 /*!

   794     \page model-view-delegate.html

   795     \contentspage model-view-programming.html Contents

   796     \previouspage Handling Selections in Item Views

   797     \nextpage Item View Convenience Classes

   798 

   799     \title Delegate Classes

   800 

   801     \tableofcontents

   802 

   803     \section1 Concepts

   804 

   805     Unlike the Model-View-Controller pattern, the model/view design does not

   806     include a completely separate component for managing interaction with

   807     the user. Generally, the view is responsible for the presentation of

   808     model data to the user, and for processing user input. To allow some

   809     flexibility in the way this input is obtained, the interaction is

   810     performed by delegates. These components provide input capabilities

   811     and are also responsible for rendering individual items in some views.

   812     The standard interface for controlling delegates is defined in the

   813     \l QAbstractItemDelegate class.

   814 

   815     Delegates are expected to be able to render their contents themselves

   816     by implementing the \l{QItemDelegate::paint()}{paint()}

   817     and \l{QItemDelegate::sizeHint()}{sizeHint()} functions.

   818     However, simple widget-based delegates can subclass \l QItemDelegate

   819     instead of \l QAbstractItemDelegate, and take advantage of the default

   820     implementations of these functions.

   821 

   822     Editors for delegates can be implemented either by using widgets to manage

   823     the editing process or by handling events directly.

   824     The first approach is covered later in this chapter, and it is also

   825     shown in the \l{Spin Box Delegate Example}{Spin Box Delegate} example.

   826 

   827     The \l{Pixelator Example}{Pixelator} example shows how to create a

   828     custom delegate that performs specialized rendering for a table view.

   829 

   830     \section1 Using an Existing Delegate

   831 

   832     The standard views provided with Qt use instances of \l QItemDelegate

   833     to provide editing facilities. This default implementation of the

   834     delegate interface renders items in the usual style for each of the

   835     standard views: \l QListView, \l QTableView, and \l QTreeView.

   836 

   837     All the standard roles are handled by the default delegate used by

   838     the standard views. The way these are interpreted is described in the

   839     QItemDelegate documentation.

   840 

   841     The delegate used by a view is returned by the

   842     \l{QAbstractItemView::itemDelegate()}{itemDelegate()} function.

   843     The \l{QAbstractItemView::setItemDelegate()}{setItemDelegate()} function

   844     allows you to install a custom delegate for a standard view, and it is

   845     necessary to use this function when setting the delegate for a custom

   846     view.

   847 

   848     \section1 A Simple Delegate

   849 

   850     The delegate implemented here uses a \l QSpinBox to provide editing

   851     facilities, and is mainly intended for use with models that display

   852     integers. Although we set up a custom integer-based table model for

   853     this purpose, we could easily have used \l QStandardItemModel instead

   854     since the custom delegate will control data entry. We construct a

   855     table view to display the contents of the model, and this will use

   856     the custom delegate for editing.

   857 

   858     \img spinboxdelegate-example.png

   859 

   860     We subclass the delegate from \l QItemDelegate because we do not want

   861     to write custom display functions. However, we must still provide

   862     functions to manage the editor widget:

   863 

   864     \snippet examples/itemviews/spinboxdelegate/delegate.h 0

   865 

   866     Note that no editor widgets are set up when the delegate is

   867     constructed. We only construct an editor widget when it is needed.

   868 

   869     \section2 Providing an Editor

   870 

   871     In this example, when the table view needs to provide an editor, it

   872     asks the delegate to provide an editor widget that is appropriate

   873     for the item being modified. The

   874     \l{QAbstractItemDelegate::createEditor()}{createEditor()} function is

   875     supplied with everything that the delegate needs to be able to set up

   876     a suitable widget:

   877 

   878     \snippet examples/itemviews/spinboxdelegate/delegate.cpp 1

   879 

   880     Note that we do not need to keep a pointer to the editor widget because

   881     the view takes responsibility for destroying it when it is no longer

   882     needed.

   883 

   884     We install the delegate's default event filter on the editor to ensure

   885     that it provides the standard editing shortcuts that users expect.

   886     Additional shortcuts can be added to the editor to allow more

   887     sophisticated behavior; these are discussed in the section on

   888     \l{#EditingHints}{Editing Hints}.

   889 

   890     The view ensures that the editor's data and geometry are set

   891     correctly by calling functions that we define later for these purposes.

   892     We can create different editors depending on the model index supplied

   893     by the view. For example, if we have a column of integers and a column

   894     of strings we could return either a \c QSpinBox or a \c QLineEdit,

   895     depending on which column is being edited.

   896 

   897     The delegate must provide a function to copy model data into the

   898     editor. In this example, we read the data stored in the

   899     \l{Qt::ItemDataRole}{display role}, and set the value in the

   900     spin box accordingly.

   901 

   902     \snippet examples/itemviews/spinboxdelegate/delegate.cpp 2

   903 

   904     In this example, we know that the editor widget is a spin box, but we

   905     could have provided different editors for different types of data in

   906     the model, in which case we would need to cast the widget to the

   907     appropriate type before accessing its member functions.

   908 

   909     \section2 Submitting Data to the Model

   910 

   911     When the user has finished editing the value in the spin box, the view

   912     asks the delegate to store the edited value in the model by calling the

   913     \l{QAbstractItemDelegate::setModelData()}{setModelData()} function.

   914 

   915     \snippet examples/itemviews/spinboxdelegate/delegate.cpp 3

   916 

   917     Since the view manages the editor widgets for the delegate, we only

   918     need to update the model with the contents of the editor supplied.

   919     In this case, we ensure that the spin box is up-to-date, and update

   920     the model with the value it contains using the index specified.

   921 

   922     The standard \l QItemDelegate class informs the view when it has

   923     finished editing by emitting the

   924     \l{QAbstractItemDelegate::closeEditor()}{closeEditor()} signal.

   925     The view ensures that the editor widget is closed and destroyed. In

   926     this example, we only provide simple editing facilities, so we need

   927     never emit this signal.

   928 

   929     All the operations on data are performed through the interface

   930     provided by \l QAbstractItemModel. This makes the delegate mostly

   931     independent from the type of data it manipulates, but some

   932     assumptions must be made in order to use certain types of

   933     editor widgets. In this example, we have assumed that the model

   934     always contains integer values, but we can still use this

   935     delegate with different kinds of models because \l{QVariant}

   936     provides sensible default values for unexpected data.

   937 

   938     \section2 Updating the Editor's Geometry

   939 

   940     It is the responsibility of the delegate to manage the editor's

   941     geometry. The geometry must be set when the editor is created, and

   942     when the item's size or position in the view is changed. Fortunately,

   943     the view provides all the necessary geometry information inside a

   944     \l{QStyleOptionViewItem}{view option} object.

   945 

   946     \snippet examples/itemviews/spinboxdelegate/delegate.cpp 4

   947 

   948     In this case, we just use the geometry information provided by the

   949     view option in the item rectangle. A delegate that renders items with

   950     several elements would not use the item rectangle directly. It would

   951     position the editor in relation to the other elements in the item.

   952 

   953     \target EditingHints

   954     \section2 Editing Hints

   955 

   956     After editing, delegates should provide hints to the other components

   957     about the result of the editing process, and provide hints that will

   958     assist any subsequent editing operations. This is achieved by

   959     emitting the \l{QAbstractItemDelegate::closeEditor()}{closeEditor()}

   960     signal with a suitable hint. This is taken care of by the default

   961     QItemDelegate event filter which we installed on the spin box when

   962     it was constructed.

   963 

   964     The behavior of the spin box could be adjusted to make it more user

   965     friendly. In the default event filter supplied by QItemDelegate, if

   966     the user hits \key Return to confirm their choice in the spin box,

   967     the delegate commits the value to the model and closes the spin box.

   968     We can change this behavior by installing our own event filter on the

   969     spin box, and provide editing hints that suit our needs; for example,

   970     we might emit \l{QAbstractItemDelegate::closeEditor()}{closeEditor()}

   971     with the \l{QAbstractItemDelegate::EndEditHint}{EditNextItem} hint to

   972     automatically start editing the next item in the view.

   973 

   974     Another approach that does not require the use of an event

   975     filter is to provide our own editor widget, perhaps subclassing

   976     QSpinBox for convenience. This alternative approach would give us

   977     more control over how the editor widget behaves at the cost of

   978     writing additional code. It is usually easier to install an event

   979     filter in the delegate if you need to customize the behavior of

   980     a standard Qt editor widget.

   981 

   982     Delegates do not have to emit these hints, but those that do not will

   983     be less integrated into applications, and will be less usable than

   984     those that emit hints to support common editing actions.

   985 */

   986 

   987 /*!

   988     \page model-view-selection.html

   989     \contentspage model-view-programming.html Contents

   990     \previouspage View Classes

   991     \nextpage Delegate Classes

   992 

   993     \title Handling Selections in Item Views

   994 

   995     \tableofcontents

   996 

   997     \section1 Concepts

   998 

   999     The selection model used in the item view classes offers many improvements

  1000     over the selection model used in Qt 3. It provides a more general

  1001     description of selections based on the facilities of the model/view

  1002     architecture. Although the standard classes for manipulating selections are

  1003     sufficient for the item views provided, the selection model allows you to

  1004     create specialized selection models to suit the requirements for your own

  1005     item models and views.

  1006 

  1007     Information about the items selected in a view is stored in an instance of

  1008     the \l QItemSelectionModel class. This maintains model indexes for items in

  1009     a single model, and is independent of any views. Since there can be many

  1010     views onto a model, it is possible to share selections between views,

  1011     allowing applications to show multiple views in a consistent way.

  1012 

  1013     Selections are made up of \e{selection ranges}. These efficiently maintain

  1014     information about large selections of items by recording only the starting

  1015     and ending model indexes for each range of selected items. Non-contiguous

  1016     selections of items are constructed by using more than one selection range

  1017     to describe the selection.

  1018 

  1019     Selections are applied to a collection of model indexes held by a selection

  1020     model. The most recent selection of items applied is known as the

  1021     \e{current selection}. The effects of this selection can be modified even

  1022     after its application through the use of certain types of selection

  1023     commands. These are discussed later in this section.

  1024 

  1025 

  1026     \section2 Current Item and Selected Items

  1027 

  1028     In a view, there is always a current item and a selected item - two

  1029     independent states. An item can be the current item and selected at the

  1030     same time. The view is responsible for ensuring that there is always a

  1031     current item as keyboard navigation, for example, requires a current item.

  1032 

  1033     The table below highlights the differences between current item and

  1034     selected items.

  1035 

  1036     \table

  1037     \header

  1038         \o  Current Item

  1039         \o  Selected Items

  1040 

  1041     \row

  1042         \o  There can only be one current item.

  1043         \o  There can be multiple selected items.

  1044     \row

  1045         \o  The current item will be changed with key navigation or mouse

  1046             button clicks.

  1047         \o  The selected state of items is set or unset, depending on several

  1048             pre-defined modes - e.g., single selection, multiple selection,

  1049             etc. - when the user interacts with the items.

  1050     \row

  1051         \o  The current item will be edited if the edit key, \gui F2, is

  1052             pressed or the item is double-clicked (provided that editing is

  1053             enabled).

  1054         \o  The current item can be used together with an anchor to specify a

  1055             range that should be selected or deselected (or a combination of

  1056             the two).

  1057     \row

  1058         \o  The current item is indicated by the focus rectangle.

  1059         \o  The selected items are indicated with the selection rectangle.

  1060     \endtable

  1061 

  1062     When manipulating selections, it is often helpful to think of

  1063     \l QItemSelectionModel as a record of the selection state of all the items

  1064     in an item model. Once a selection model is set up, collections of items

  1065     can be selected, deselected, or their selection states can be toggled

  1066     without the need to know which items are already selected. The indexes of

  1067     all selected items can be retrieved at any time, and other components can

  1068     be informed of changes to the selection model via the signals and slots

  1069     mechanism.

  1070 

  1071 

  1072     \section1 Using a Selection Model

  1073 

  1074     The standard view classes provide default selection models that can

  1075     be used in most applications. A selection model belonging to one view

  1076     can be obtained using the view's

  1077     \l{QAbstractItemView::selectionModel()}{selectionModel()} function,

  1078     and shared between many views with

  1079     \l{QAbstractItemView::setSelectionModel()}{setSelectionModel()},

  1080     so the construction of new selection models is generally not required.

  1081 

  1082     A selection is created by specifying a model, and a pair of model

  1083     indexes to a \l QItemSelection. This uses the indexes to refer to items

  1084     in the given model, and interprets them as the top-left and bottom-right

  1085     items in a block of selected items.

  1086     To apply the selection to items in a model requires the selection to be

  1087     submitted to a selection model; this can be achieved in a number of ways,

  1088     each having a different effect on the selections already present in the

  1089     selection model.

  1090 

  1091 

  1092     \section2 Selecting Items

  1093 

  1094     To demonstrate some of the principal features of selections, we construct

  1095     an instance of a custom table model with 32 items in total, and open a

  1096     table view onto its data:

  1097 

  1098     \snippet doc/src/snippets/itemselection/main.cpp 0

  1099 

  1100     The table view's default selection model is retrieved for later use.

  1101     We do not modify any items in the model, but instead select a few

  1102     items that the view will display at the top-left of the table. To do

  1103     this, we need to retrieve the model indexes corresponding to the

  1104     top-left and bottom-right items in the region to be selected:

  1105 

  1106     \snippet doc/src/snippets/itemselection/main.cpp 1

  1107 

  1108     To select these items in the model, and see the corresponding change

  1109     in the table view, we need to construct a selection object then apply

  1110     it to the selection model:

  1111 

  1112     \snippet doc/src/snippets/itemselection/main.cpp 2

  1113 

  1114     The selection is applied to the selection model using a command

  1115     defined by a combination of

  1116     \l{QItemSelectionModel::SelectionFlag}{selection flags}.

  1117     In this case, the flags used cause the items recorded in the

  1118     selection object to be included in the selection model, regardless

  1119     of their previous state. The resulting selection is shown by the view.

  1120 

  1121     \img selected-items1.png

  1122 

  1123     The selection of items can be modified using various operations that

  1124     are defined by the selection flags. The selection that results from

  1125     these operations may have a complex structure, but will be represented

  1126     efficiently by the selection model. The use of different selection

  1127     flags to manipulate the selected items is described when we examine

  1128     how to update a selection.

  1129 

  1130     \section2 Reading the Selection State

  1131 

  1132     The model indexes stored in the selection model can be read using

  1133     the \l{QItemSelectionModel::selectedIndexes()}{selectedIndexes()}

  1134     function. This returns an unsorted list of model indexes that we can

  1135     iterate over as long as we know which model they are for: