|
1 /**************************************************************************** |
|
2 ** |
|
3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). |
|
4 ** All rights reserved. |
|
5 ** Contact: Nokia Corporation (qt-info@nokia.com) |
|
6 ** |
|
7 ** This file is part of the QtGui module of the Qt Toolkit. |
|
8 ** |
|
9 ** $QT_BEGIN_LICENSE:LGPL$ |
|
10 ** No Commercial Usage |
|
11 ** This file contains pre-release code and may not be distributed. |
|
12 ** You may use this file in accordance with the terms and conditions |
|
13 ** contained in the Technology Preview License Agreement accompanying |
|
14 ** this package. |
|
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 ** If you have questions regarding the use of this file, please contact |
|
29 ** Nokia at qt-info@nokia.com. |
|
30 ** |
|
31 ** |
|
32 ** |
|
33 ** |
|
34 ** |
|
35 ** |
|
36 ** |
|
37 ** |
|
38 ** $QT_END_LICENSE$ |
|
39 ** |
|
40 ****************************************************************************/ |
|
41 |
|
42 |
|
43 |
|
44 /*! |
|
45 \class QButtonGroup |
|
46 \brief The QButtonGroup class provides a container to organize groups of |
|
47 button widgets. |
|
48 |
|
49 \ingroup organizers |
|
50 \ingroup geomanagement |
|
51 |
|
52 QButtonGroup provides an abstract container into which button widgets can |
|
53 be placed. It does not provide a visual representation of this container |
|
54 (see QGroupBox for a container widget), but instead manages the states of |
|
55 each of the buttons in the group. |
|
56 |
|
57 An \l {QButtonGroup::exclusive} {exclusive} button group switches |
|
58 off all checkable (toggle) buttons except the one that was |
|
59 clicked. By default, a button group is exclusive. The buttons in a |
|
60 button group are usually checkable QPushButton's, \l{QCheckBox}es |
|
61 (normally for non-exclusive button groups), or \l{QRadioButton}s. |
|
62 If you create an exclusive button group, you should ensure that |
|
63 one of the buttons in the group is initially checked; otherwise, |
|
64 the group will initially be in a state where no buttons are |
|
65 checked. |
|
66 |
|
67 A button is added to the group with addButton(). It can be removed |
|
68 from the group with removeButton(). If the group is exclusive, the |
|
69 currently checked button is available as checkedButton(). If a |
|
70 button is clicked the buttonClicked() signal is emitted. For a |
|
71 checkable button in an exclusive group this means that the button |
|
72 was checked. The list of buttons in the group is returned by |
|
73 buttons(). |
|
74 |
|
75 In addition, QButtonGroup can map between integers and buttons. |
|
76 You can assign an integer id to a button with setId(), and |
|
77 retrieve it with id(). The id of the currently checked button is |
|
78 available with checkedId(), and there is an overloaded signal |
|
79 buttonClicked() which emits the id of the button. The id \c {-1} |
|
80 is reserved by QButtonGroup to mean "no such button". The purpose |
|
81 of the mapping mechanism is to simplify the representation of enum |
|
82 values in a user interface. |
|
83 |
|
84 \sa QGroupBox QPushButton, QCheckBox, QRadioButton |
|
85 */ |
|
86 |
|
87 /*! |
|
88 \fn QButtonGroup::QButtonGroup(QObject *parent) |
|
89 |
|
90 Constructs a new, empty button group with the given \a parent. |
|
91 |
|
92 \sa addButton() setExclusive() |
|
93 */ |
|
94 |
|
95 /*! |
|
96 \fn QButtonGroup::~QButtonGroup() |
|
97 |
|
98 Destroys the button group. |
|
99 */ |
|
100 |
|
101 /*! |
|
102 \property QButtonGroup::exclusive |
|
103 \brief whether the button group is exclusive |
|
104 |
|
105 If this property is true then only one button in the group can be checked |
|
106 at any given time. The user can click on any button to check it, and that |
|
107 button will replace the existing one as the checked button in the group. |
|
108 |
|
109 In an exclusive group, the user cannot uncheck the currently checked button |
|
110 by clicking on it; instead, another button in the group must be clicked |
|
111 to set the new checked button for that group. |
|
112 |
|
113 By default, this property is true. |
|
114 */ |
|
115 |
|
116 /*! |
|
117 \fn void QButtonGroup::buttonClicked(QAbstractButton *button) |
|
118 |
|
119 This signal is emitted when the given \a button is clicked. A |
|
120 button is clicked when it is first pressed and then released, when |
|
121 its shortcut key is typed, or programmatically when |
|
122 QAbstractButton::click() or QAbstractButton::animateClick() is |
|
123 called. |
|
124 |
|
125 |
|
126 \sa checkedButton(), QAbstractButton::clicked() |
|
127 */ |
|
128 |
|
129 /*! |
|
130 \fn void QButtonGroup::buttonClicked(int id) |
|
131 |
|
132 This signal is emitted when a button with the given \a id is |
|
133 clicked. |
|
134 |
|
135 \sa checkedButton(), QAbstractButton::clicked() |
|
136 */ |
|
137 |
|
138 /*! |
|
139 \fn void QButtonGroup::buttonPressed(QAbstractButton *button) |
|
140 \since 4.2 |
|
141 |
|
142 This signal is emitted when the given \a button is pressed down. |
|
143 |
|
144 \sa QAbstractButton::pressed() |
|
145 */ |
|
146 |
|
147 /*! |
|
148 \fn void QButtonGroup::buttonPressed(int id) |
|
149 \since 4.2 |
|
150 |
|
151 This signal is emitted when a button with the given \a id is |
|
152 pressed down. |
|
153 |
|
154 \sa QAbstractButton::pressed() |
|
155 */ |
|
156 |
|
157 /*! |
|
158 \fn void QButtonGroup::buttonReleased(QAbstractButton *button) |
|
159 \since 4.2 |
|
160 |
|
161 This signal is emitted when the given \a button is released. |
|
162 |
|
163 \sa QAbstractButton::released() |
|
164 */ |
|
165 |
|
166 /*! |
|
167 \fn void QButtonGroup::buttonReleased(int id) |
|
168 \since 4.2 |
|
169 |
|
170 This signal is emitted when a button with the given \a id is |
|
171 released. |
|
172 |
|
173 \sa QAbstractButton::released() |
|
174 */ |
|
175 |
|
176 /*! |
|
177 \fn void QButtonGroup::addButton(QAbstractButton *button); |
|
178 |
|
179 Adds the given \a button to the end of the group's internal list |
|
180 of buttons. An id will be assigned to the button by this |
|
181 QButtonGroup. Automatically assigned ids are guaranteed to be |
|
182 negative, starting with -2. If you are also assigning your own |
|
183 ids, use positive values to avoid conflicts. |
|
184 |
|
185 \sa removeButton() buttons() |
|
186 */ |
|
187 |
|
188 /*! |
|
189 \fn void QButtonGroup::addButton(QAbstractButton *button, int id); |
|
190 |
|
191 Adds the given \a button to the button group, with the given \a |
|
192 id. It is recommended to assign only positive ids. |
|
193 |
|
194 \sa removeButton() buttons() |
|
195 */ |
|
196 |
|
197 /*! |
|
198 \fn void QButtonGroup::removeButton(QAbstractButton *button); |
|
199 |
|
200 Removes the given \a button from the button group. |
|
201 |
|
202 \sa addButton() buttons() |
|
203 */ |
|
204 |
|
205 /*! |
|
206 \fn QList<QAbstractButton*> QButtonGroup::buttons() const |
|
207 |
|
208 Returns the list of this groups's buttons. This may be empty. |
|
209 |
|
210 \sa addButton(), removeButton() |
|
211 */ |
|
212 |
|
213 /*! |
|
214 \fn QAbstractButton *QButtonGroup::checkedButton() const; |
|
215 |
|
216 Returns the button group's checked button, or 0 if no buttons are |
|
217 checked. |
|
218 |
|
219 \sa buttonClicked() |
|
220 */ |
|
221 |
|
222 /*! |
|
223 \fn QAbstractButton *QButtonGroup::button(int id) const; |
|
224 \since 4.1 |
|
225 |
|
226 Returns the button with the specified \a id, or 0 if no such button |
|
227 exists. |
|
228 */ |
|
229 |
|
230 /*! |
|
231 \fn void QButtonGroup::setId(QAbstractButton *button, int id) |
|
232 \since 4.1 |
|
233 |
|
234 Sets the \a id for the specified \a button. Note that \a id can |
|
235 not be -1. |
|
236 |
|
237 \sa id() |
|
238 */ |
|
239 |
|
240 /*! |
|
241 \fn int QButtonGroup::id(QAbstractButton *button) const; |
|
242 \since 4.1 |
|
243 |
|
244 Returns the id for the specified \a button, or -1 if no such button |
|
245 exists. |
|
246 |
|
247 |
|
248 \sa setId() |
|
249 */ |
|
250 |
|
251 /*! |
|
252 \fn int QButtonGroup::checkedId() const; |
|
253 \since 4.1 |
|
254 |
|
255 Returns the id of the checkedButton(), or -1 if no button is checked. |
|
256 |
|
257 \sa setId() |
|
258 */ |
|
259 |
|
260 |
|
261 /*! \fn void QButtonGroup::insert(QAbstractButton *b) |
|
262 |
|
263 Use addButton() instead. |
|
264 */ |
|
265 |
|
266 /*! \fn void QButtonGroup::remove(QAbstractButton *b) |
|
267 |
|
268 Use removeButton() instead. |
|
269 */ |