source: trunk/doc/src/examples/pixelator.qdoc@ 651

/****************************************************************************
**
** Copyright (C) 2010 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/pixelator
    \title Pixelator Example

    The Pixelator example shows how delegates can be used to customize the way that
    items are rendered in standard item views.

    \image pixelator-example.png

    By default, QTreeView, QTableView, and QListView use a standard item delegate
    to display and edit a set of common data types that are sufficient for many
    applications. However, an application may need to represent items of data in a
    particular way, or provide support for rendering more specialized data types,
    and this often requires the use of a custom delegate.

    In this example, we show how to use custom delegates to modify the appearance
    of standard views. To do this, we implement the following components:

    \list
    \i A model which represents each pixel in an image as an item of data, where each
       item contains a value for the brightness of the corresponding pixel.
    \i A custom delegate that uses the information supplied by the model to represent
       each pixel as a black circle on a white background, where the radius of the
       circle corresponds to the darkness of the pixel.
    \endlist

    This example may be useful for developers who want to implement their own table
    models or custom delegates. The process of creating custom delegates for editing
    item data is covered in the \l{Spin Box Delegate Example}{Spin Box Delegate}
    example.

    \section1 ImageModel Class Definition

    The \c ImageModel class is defined as follows:

    \snippet examples/itemviews/pixelator/imagemodel.h 0

    Since we only require a simple, read-only table model, we only need to implement
    functions to indicate the dimensions of the image and supply data to other
    components.

    For convenience, the image to be used is passed in the constructor.

    \section1 ImageModel Class Implementation

    The constructor is trivial:

    \snippet examples/itemviews/pixelator/imagemodel.cpp 0

    The \c setImage() function sets the image that will be used by the model:
   
    \snippet examples/itemviews/pixelator/imagemodel.cpp 1

    The QAbstractItemModel::reset() call tells the view(s) that the model
    has changed.

    The \c rowCount() and \c columnCount() functions return the height and width of
    the image respectively:

    \snippet examples/itemviews/pixelator/imagemodel.cpp 2
    \snippet examples/itemviews/pixelator/imagemodel.cpp 3

    Since the image is a simple two-dimensional structure, the \c parent arguments
    to these functions are unused. They both simply return the relevant size from
    the underlying image object.

    The \c data() function returns data for the item that corresponds to a given
    model index in a format that is suitable for a particular role:

    \snippet examples/itemviews/pixelator/imagemodel.cpp 4

    In this implementation, we only check that the model index is valid, and that
    the role requested is the \l{Qt::ItemDataRole}{DisplayRole}. If so, the function
    returns the grayscale value of the relevant pixel in the image; otherwise, a null
    model index is returned.

    This model can be used with QTableView to display the integer brightness values
    for the pixels in the image. However, we will implement a custom delegate to
    display this information in a more artistic way.

    The \c headerData() function is also reimplemented:

    \snippet examples/itemviews/pixelator/imagemodel.cpp 5

    We return (1, 1) as the size hint for a header item. If we
    didn't, the headers would default to a larger size, preventing
    us from displaying really small items (which can be specified
    using the \gui{Pixel size} combobox).

    \section1 PixelDelegate Class Definition

    The \c PixelDelegate class is defined as follows:

    \snippet examples/itemviews/pixelator/pixeldelegate.h 0

    This class provides only basic features for a delegate so, unlike the
    \l{Spin Box Delegate Example}{Spin Box Delegate} example, we subclass
    QAbstractItemDelegate instead of QItemDelegate.

    We only need to reimplement \l{QAbstractItemDelegate::paint()}{paint()} and
    \l{QAbstractItemDelegate::sizeHint()}{sizeHint()} in this class.
    However, we also provide a delegate-specific \c setPixelSize() function so
    that we can change the delegate's behavior via the signals and slots mechanism.

    \section1 PixelDelegate Class Implementation