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
|
---|
|
---|