source: trunk/doc/src/examples/spinboxdelegate.qdoc@ 534

Last change on this file since 534 was 2, checked in by Dmitry A. Kuminov, 16 years ago

Initially imported qt-all-opensource-src-4.5.1 from Trolltech.
File size: 6.5 KB
Line 
1/****************************************************************************
2**
3** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
4** Contact: Qt Software Information (qt-info@nokia.com)
5**
6** This file is part of the documentation of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL$
9** Commercial Usage
10** Licensees holding valid Qt Commercial licenses may use this file in
11** accordance with the Qt Commercial License Agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and Nokia.
14**
15** GNU Lesser General Public License Usage
16** Alternatively, this file may be used under the terms of the GNU Lesser
17** General Public License version 2.1 as published by the Free Software
18** Foundation and appearing in the file LICENSE.LGPL included in the
19** packaging of this file. Please review the following information to
20** ensure the GNU Lesser General Public License version 2.1 requirements
21** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
22**
23** In addition, as a special exception, Nokia gives you certain
24** additional rights. These rights are described in the Nokia Qt LGPL
25** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
26** 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 are unsure which license is appropriate for your use, please
37** contact the sales department at qt-sales@nokia.com.
38** $QT_END_LICENSE$
39**
40****************************************************************************/
41
42/*!
43 \example itemviews/spinboxdelegate
44 \title Spin Box Delegate Example
45
46 The Spin Box Delegate example shows how to create an editor for a custom delegate in
47 the model/view framework by reusing a standard Qt editor widget.
48
49 The model/view framework provides a standard delegate that is used by default
50 with the standard view classes. For most purposes, the selection of editor
51 widgets available through this delegate is sufficient for editing text, boolean
52 values, and other simple data types. However, for specific data types, it is
53 sometimes necessary to use a custom delegate to either display the data in a
54 specific way, or allow the user to edit it with a custom control.
55
56 \image spinboxdelegate-example.png
57
58 This concepts behind this example are covered in the
59 \l{model-view-delegate.html}{Delegate Classes} chapter of the
60 \l{model-view-programming.html}{Model/View Programming} overview.
61
62 \section1 SpinBoxDelegate Class Definition
63
64 The definition of the delegate is as follows:
65
66 \snippet examples/itemviews/spinboxdelegate/delegate.h 0
67
68 The delegate class declares only those functions that are needed to
69 create an editor widget, display it at the correct location in a view,
70 and communicate with a model. Custom delegates can also provide their
71 own painting code by reimplementing the \c paintEvent() function.
72
73 \section1 SpinBoxDelegate Class Implementation
74
75 Since the delegate is stateless, the constructor only needs to
76 call the base class's constructor with the parent QObject as its
77 argument:
78
79 \snippet examples/itemviews/spinboxdelegate/delegate.cpp 0
80
81 Since the delegate is a subclass of QItemDelegate, the data it retrieves
82 from the model is displayed in a default style, and we do not need to
83 provide a custom \c paintEvent().
84
85 The \c createEditor() function returns an editor widget, in this case a
86 spin box that restricts values from the model to integers from 0 to 100
87 inclusive.
88
89 \snippet examples/itemviews/spinboxdelegate/delegate.cpp 1
90
91 We install an event filter on the spin box to ensure that it behaves in
92 a way that is consistent with other delegates. The implementation for
93 the event filter is provided by the base class.
94
95 The \c setEditorData() function reads data from the model, converts it
96 to an integer value, and writes it to the editor widget.
97
98 \snippet examples/itemviews/spinboxdelegate/delegate.cpp 2
99
100 Since the view treats delegates as ordinary QWidget instances, we have
101 to use a static cast before we can set the value in the spin box.
102
103 The \c setModelData() function reads the contents of the spin box, and
104 writes it to the model.
105
106 \snippet examples/itemviews/spinboxdelegate/delegate.cpp 3
107
108 We call \l{QSpinBox::interpretText()}{interpretText()} to make sure that
109 we obtain the most up-to-date value in the spin box.
110
111 The \c updateEditorGeometry() function updates the editor widget's
112 geometry using the information supplied in the style option. This is the
113 minimum that the delegate must do in this case.
114
115 \snippet examples/itemviews/spinboxdelegate/delegate.cpp 4
116
117 More complex editor widgets may divide the rectangle available in
118 \c{option.rect} between different child widgets if required.
119
120 \section1 The Main Function
121
122 This example is written in a slightly different way to many of the
123 other examples supplied with Qt. To demonstrate the use of a custom
124 editor widget in a standard view, it is necessary to set up a model
125 containing some arbitrary data and a view to display it.
126
127 We set up the application in the normal way, construct a standard item
128 model to hold some data, set up a table view to use the data in the
129 model, and construct a custom delegate to use for editing:
130
131 \snippet examples/itemviews/spinboxdelegate/main.cpp 0
132
133 The table view is informed about the delegate, and will use it to
134 display each of the items. Since the delegate is a subclass of
135 QItemDelegate, each cell in the table will be rendered using standard
136 painting operations.
137
138 We insert some arbitrary data into the model for demonstration purposes:
139
140 \snippet examples/itemviews/spinboxdelegate/main.cpp 1
141 \snippet examples/itemviews/spinboxdelegate/main.cpp 2
142
143 Finally, the table view is displayed with a window title, and we start
144 the application's event loop:
145
146 \snippet examples/itemviews/spinboxdelegate/main.cpp 3
147
148 Each of the cells in the table can now be edited in the usual way, but
149 the spin box ensures that the data returned to the model is always
150 constrained by the values allowed by the spin box delegate.
151*/
Note: See TracBrowser for help on using the repository browser.