source: trunk/doc/src/examples/stardelegate.qdoc@ 561

/****************************************************************************
**
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation ([email protected])
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Nokia.
**
** 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.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 3.0 as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU General Public License version 3.0 requirements will be
** met: http://www.gnu.org/copyleft/gpl.html.
**
** If you have questions regarding the use of this file, please contact
** Nokia at [email protected].
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \example itemviews/stardelegate
    \title Star Delegate Example

    The Star Delegate example shows how to create a delegate that
    can paint itself and that supports editing.

    \image stardelegate.png The Star Delegate Example

    When displaying data in a QListView, QTableView, or QTreeView,
    the individual items are drawn by a
    \l{Delegate Classes}{delegate}. Also, when the user starts
    editing an item (e.g., by double-clicking the item), the delegate
    provides an editor widget that is placed on top of the item while
    editing takes place.

    Delegates are subclasses of QAbstractItemDelegate. Qt provides
    QItemDelegate, which inherits QAbstractItemDelegate and handles
    the most common data types (notably \c int and QString). If we
    need to support custom data types, or want to customize the
    rendering or the editing for existing data types, we can subclass
    QAbstractItemDelegate or QItemDelegate. See \l{Delegate Classes}
    for more information about delegates, and \l{Model/View
    Programming} if you need a high-level introduction to Qt's
    model/view architecture (including delegates).

    In this example, we will see how to implement a custom delegate
    to render and edit a "star rating" data type, which can store
    values such as "1 out of 5 stars".

    The example consists of the following classes:

    \list
    \o \c StarRating is the custom data type. It stores a rating
       expressed as stars, such as "2 out of 5 stars" or "5 out of
       6 stars".

    \o \c StarDelegate inherits QItemDelegate and provides support
       for \c StarRating (in addition to the data types already
       handled by QItemDelegate).

    \o \c StarEditor inherits QWidget and is used by \c StarDelegate
       to let the user edit a star rating using the mouse.
    \endlist

    To show the \c StarDelegate in action, we will fill a
    QTableWidget with some data and install the delegate on it.

    \section1 StarDelegate Class Definition

    Here's the definition of the \c StarDelegate class:

    \snippet examples/itemviews/stardelegate/stardelegate.h 0

    All public functions are reimplemented virtual functions from
    QItemDelegate to provide custom rendering and editing.

    \section1 StarDelegate Class Implementation

    The \l{QAbstractItemDelegate::}{paint()} function is
    reimplemented from QItemDelegate and is called whenever the view
    needs to repaint an item:

    \snippet examples/itemviews/stardelegate/stardelegate.cpp 0

    The function is invoked once for each item, represented by a
    QModelIndex object from the model. If the data stored in the item
    is a \c StarRating, we paint it ourselves; otherwise, we let
    QItemDelegate paint it for us. This ensures that the \c
    StarDelegate can handle the most common data types.

    In the case where the item is a \c StarRating, we draw the
    background if the item is selected, and we draw the item using \c
    StarRating::paint(), which we will review later.

    \c{StartRating}s can be stored in a QVariant thanks to the
    Q_DECLARE_METATYPE() macro appearing in \c starrating.h. More on
    this later.

    The \l{QAbstractItemDelegate::}{createEditor()} function is
    called when the user starts editing an item:

    \snippet examples/itemviews/stardelegate/stardelegate.cpp 2

    If the item is a \c StarRating, we create a \c StarEditor and
    connect its \c editingFinished() signal to our \c
    commitAndCloseEditor() slot, so we can update the model when the
    editor closes.

    Here's the implementation of \c commitAndCloseEditor():

    \snippet examples/itemviews/stardelegate/stardelegate.cpp 5

    When the user is done editing, we emit
    \l{QAbstractItemDelegate::}{commitData()} and
    \l{QAbstractItemDelegate::}{closeEditor()} (both declared in
    QAbstractItemDelegate), to tell the model that there is edited
    data and to inform the view that the editor is no longer needed.

    The \l{QAbstractItemDelegate::}{setEditorData()} function is
    called when an editor is created to initialize it with data
    from the model:

    \snippet examples/itemviews/stardelegate/stardelegate.cpp 3

    We simply call \c setStarRating() on the editor.

    The \l{QAbstractItemDelegate::}{setModelData()} function is
    called when editing is finished, to commit data from the editor
    to the model:

    \snippet examples/itemviews/stardelegate/stardelegate.cpp 4

    The \c sizeHint() function returns an item's preferred size:

    \snippet examples/itemviews/stardelegate/stardelegate.cpp 1

    We simply forward the call to \c StarRating.

    \section1 StarEditor Class Definition

    The \c StarEditor class was used when implementing \c
    StarDelegate. Here's the class definition: