/****************************************************************************

**

** Copyright (C) 2009 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:LGPL$

** 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 Lesser General Public License Usage

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

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

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

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

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

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

**

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

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

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

**

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

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

**

**

**

**

**

**

**

**

** $QT_END_LICENSE$

**

****************************************************************************/

/*!

    \group model-view

    \title Model/View Classes

*/

/*!

    \page model-view-programming.html

    \nextpage An Introduction to Model/View Programming

    \startpage index.html Qt Reference Documentation

    \title Model/View Programming

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

    item view classes.

    \ingroup frameworks-technologies

    \list

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

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

    \o \l{Using Models and Views}

      \tableofcontents{1 Using Models and Views}

    \o \l{Model Classes}

      \tableofcontents{1 Model Classes}

    \o \l{Creating New Models}

      \tableofcontents{1 Creating New Models}

    \o \l{View Classes}

      \tableofcontents{1 View Classes}

    \o \l{Handling Selections in Item Views}

      \tableofcontents{1 Handling Selections in Item Views}

    \o \l{Delegate Classes}

      \tableofcontents{1 Delegate Classes}

    \o \l{Item View Convenience Classes}

      \tableofcontents{1 Item View Convenience Classes}

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

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

    \o \l{Proxy Models}

      \tableofcontents{1 Proxy Models}

    \o \l{Model Subclassing Reference}

      \tableofcontents{1 Model Subclassing Reference}

    \endlist

    \keyword Model/View Classes

    \section1 All Model/View Classes

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

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

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

    \annotatedlist model-view

    \section1 Related Examples

    \list

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

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

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

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

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

    \endlist

*/

/*!

    \page model-view-introduction.html

    \previouspage Model/View Programming

    \nextpage Using Models and Views

    \startpage index.html Qt Reference Documentation

    \title An Introduction to Model/View Programming

    \tableofcontents

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

    architecture to manage the relationship between data and the way it

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

    this architecture gives developers greater flexibility to customize the

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

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

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

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

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

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

    \section1 The Model/View Architecture

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

    Smalltalk that is often used when building user interfaces.

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

    \quotation

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

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

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

    interface designs tended to lump these objects together. MVC decouples

    them to increase flexibility and reuse.

    \endquotation

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

    the model/view architecture. 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.

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

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

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

    customized.

    \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

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

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

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

    in some cases, default implementations of features.

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

    set of functionality expected by other components; this also allows

    specialized components to be written.

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

    and slots}:

    \list

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

       held by the data source.

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

       with the items being displayed.

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

       model and view about the state of the editor.

    \endlist

    \section2 Models

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

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

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

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

    a database, or some other application component.

    The basic concepts surrounding models are presented in the section

    on \l{Model Classes}.

    QAbstractItemModel

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

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

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

    the QAbstractListModel and QAbstractTableModel classes are better

    starting points because they provide appropriate default implementations

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

    models that support specialized kinds of lists and tables.

    The process of subclassing models is discussed in the section on

    \l{Creating New Models}.

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

    data:

    \list

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

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

       of which can contain arbitrary data.

    \o QFileSystemModel provides information about files and directories in the

       local filing system.

    \o QSqlQueryModel, QSqlTableModel, and QSqlRelationalTableModel are used

       to access databases using model/view conventions.

    \endlist

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

    QAbstractItemModel, QAbstractListModel, or QAbstractTableModel to create

    your own custom models.

    \section2 Views

    Complete implementations are provided for different kinds of

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

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

    hierarchical list. Each of these classes is based on the

    QAbstractItemView abstract base class. Although these classes are

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

    customized views.

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

    \section2 Delegates

    QAbstractItemDelegate is the abstract base class for delegates in the

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

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

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

    independent alternatives to painting and providing editors for items in

    views. The difference between them is that QStyledItemDelegate uses the

    current style to paint its items. We therefore recommend using

    QStyledItemDelegate as the base class when implementing custom delegates or

    when working with Qt style sheets.

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

    \section2 Sorting

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

    architecture; which approach to choose depends on your underlying

    model.

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

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

    provide an API that allows you to sort your model data

    programmatically. In addition, you can enable interactive sorting

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

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

    to the QTableView::sortByColumn() slot or the

    QTreeView::sortByColumn() slot, respectively.

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

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

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

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

    in the section on \l {Proxy Models}.

    \section2 Convenience Classes

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

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

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

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

    in Qt 3.

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

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

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

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

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

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

    item-based set of classes.

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

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

    classes, such as QListView, QTableView, and QTreeView with

    QStandardItemModel.

    \section1 The Model/View Components

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

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

    by a section showing how you can create new components.

*/

/*!

    \page model-view-using.html

    \contentspage model-view-programming.html Contents

    \previouspage An Introduction to Model/View Programming

    \nextpage Model Classes

    \title Using Models and Views

    \tableofcontents

    \section1 Introduction

    Two of the standard models provided by Qt are QStandardItemModel and

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

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

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

    QFileSystemModel is a model that maintains information about the contents

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

    simply represents files and directories on the local filing system.

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

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

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

    manipulate data using model indexes.

    \section1 Using Views with an Existing Model

    The QListView and QTreeView classes are the most suitable views

    to use with QFileSystemModel. The example presented below displays the

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

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

    items are highlighted in both views.

    \img shareddirmodel.png

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

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

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

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

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

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

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

    file system to expose to the views.

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

    different ways:

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

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

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

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

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

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

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

    directory.

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

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

    discussed in the \l{Model Classes} chapter.

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

    widget, and runs the application's event loop:

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

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

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

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

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

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

*/

/*!

    \page model-view-model.html

    \contentspage model-view-programming.html Contents

    \previouspage Using Models and Views

    \nextpage Creating New Models

    \title Model Classes

    \tableofcontents

    \section1 Basic Concepts

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

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

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

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

    of QAbstractItemModel represent the data as a hierarchical structure

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

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

    present this information to the user.

    \image modelview-models.png

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

    signals and slots mechanism.

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

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

    advanced concepts are discussed in later chapters.

    \section2 Model Indexes

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

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

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

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

    data to display.

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

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

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

    confusion when working with more than one model.

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

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

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

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

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

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

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

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

    and persistent model indexes are provided by the QPersistentModelIndex

    class.

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

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

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

    and explain these properties in detail.

    \section2 Rows and Columns

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

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

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

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

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

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

    an index that represents the item:

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

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

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

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

    a model index.

    \table

    \row \i \inlineimage modelview-tablemodel.png

    \i \bold{Rows and columns}

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

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

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

    column numbers to the model.

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

    Top level items in a model are always referenced by specifying

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

    section.

    \endtable

    \section2 Parents of Items

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

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

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

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

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

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

    can contain another list of items.

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

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

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

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

    \table

    \row \i \inlineimage modelview-treemodel.png

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

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

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

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

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

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

    obtained with the following code:

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

    \endtable

    \section2 Item Roles

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

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

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

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

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

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

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

    of data we want:

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

    \table

    \row \i \inlineimage modelview-roles.png

    \i \bold{Item roles}

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

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

    supply appropriate information for each role.

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

    more detail.

    \endtable