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

Last change on this file since 651 was 651, checked in by Dmitry A. Kuminov, 15 years ago

trunk: Merged in qt 4.6.2 sources.

File size: 11.6 KB
Line 
1/****************************************************************************
2**
3** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
4** All rights reserved.
5** Contact: Nokia Corporation ([email protected])
6**
7** This file is part of the documentation of the Qt Toolkit.
8**
9** $QT_BEGIN_LICENSE:LGPL$
10** Commercial Usage
11** Licensees holding valid Qt Commercial licenses may use this file in
12** accordance with the Qt Commercial License Agreement provided with the
13** Software or, alternatively, in accordance with the terms contained in
14** a written agreement between you and Nokia.
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** GNU General Public License Usage
29** Alternatively, this file may be used under the terms of the GNU
30** General Public License version 3.0 as published by the Free Software
31** Foundation and appearing in the file LICENSE.GPL included in the
32** packaging of this file. Please review the following information to
33** ensure the GNU General Public License version 3.0 requirements will be
34** met: http://www.gnu.org/copyleft/gpl.html.
35**
36** If you have questions regarding the use of this file, please contact
37** Nokia at [email protected].
38** $QT_END_LICENSE$
39**
40****************************************************************************/
41
42/*!
43 \example itemviews/pixelator
44 \title Pixelator Example
45
46 The Pixelator example shows how delegates can be used to customize the way that
47 items are rendered in standard item views.
48
49 \image pixelator-example.png
50
51 By default, QTreeView, QTableView, and QListView use a standard item delegate
52 to display and edit a set of common data types that are sufficient for many
53 applications. However, an application may need to represent items of data in a
54 particular way, or provide support for rendering more specialized data types,
55 and this often requires the use of a custom delegate.
56
57 In this example, we show how to use custom delegates to modify the appearance
58 of standard views. To do this, we implement the following components:
59
60 \list
61 \i A model which represents each pixel in an image as an item of data, where each
62 item contains a value for the brightness of the corresponding pixel.
63 \i A custom delegate that uses the information supplied by the model to represent
64 each pixel as a black circle on a white background, where the radius of the
65 circle corresponds to the darkness of the pixel.
66 \endlist
67
68 This example may be useful for developers who want to implement their own table
69 models or custom delegates. The process of creating custom delegates for editing
70 item data is covered in the \l{Spin Box Delegate Example}{Spin Box Delegate}
71 example.
72
73 \section1 ImageModel Class Definition
74
75 The \c ImageModel class is defined as follows:
76
77 \snippet examples/itemviews/pixelator/imagemodel.h 0
78
79 Since we only require a simple, read-only table model, we only need to implement
80 functions to indicate the dimensions of the image and supply data to other
81 components.
82
83 For convenience, the image to be used is passed in the constructor.
84
85 \section1 ImageModel Class Implementation
86
87 The constructor is trivial:
88
89 \snippet examples/itemviews/pixelator/imagemodel.cpp 0
90
91 The \c setImage() function sets the image that will be used by the model:
92
93 \snippet examples/itemviews/pixelator/imagemodel.cpp 1
94
95 The QAbstractItemModel::reset() call tells the view(s) that the model
96 has changed.
97
98 The \c rowCount() and \c columnCount() functions return the height and width of
99 the image respectively:
100
101 \snippet examples/itemviews/pixelator/imagemodel.cpp 2
102 \snippet examples/itemviews/pixelator/imagemodel.cpp 3
103
104 Since the image is a simple two-dimensional structure, the \c parent arguments
105 to these functions are unused. They both simply return the relevant size from
106 the underlying image object.
107
108 The \c data() function returns data for the item that corresponds to a given
109 model index in a format that is suitable for a particular role:
110
111 \snippet examples/itemviews/pixelator/imagemodel.cpp 4
112
113 In this implementation, we only check that the model index is valid, and that
114 the role requested is the \l{Qt::ItemDataRole}{DisplayRole}. If so, the function
115 returns the grayscale value of the relevant pixel in the image; otherwise, a null
116 model index is returned.
117
118 This model can be used with QTableView to display the integer brightness values
119 for the pixels in the image. However, we will implement a custom delegate to
120 display this information in a more artistic way.
121
122 The \c headerData() function is also reimplemented:
123
124 \snippet examples/itemviews/pixelator/imagemodel.cpp 5
125
126 We return (1, 1) as the size hint for a header item. If we
127 didn't, the headers would default to a larger size, preventing
128 us from displaying really small items (which can be specified
129 using the \gui{Pixel size} combobox).
130
131 \section1 PixelDelegate Class Definition
132
133 The \c PixelDelegate class is defined as follows:
134
135 \snippet examples/itemviews/pixelator/pixeldelegate.h 0
136
137 This class provides only basic features for a delegate so, unlike the
138 \l{Spin Box Delegate Example}{Spin Box Delegate} example, we subclass
139 QAbstractItemDelegate instead of QItemDelegate.
140
141 We only need to reimplement \l{QAbstractItemDelegate::paint()}{paint()} and
142 \l{QAbstractItemDelegate::sizeHint()}{sizeHint()} in this class.
143 However, we also provide a delegate-specific \c setPixelSize() function so
144 that we can change the delegate's behavior via the signals and slots mechanism.
145
146 \section1 PixelDelegate Class Implementation