1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
|
'\" t
.TH QActionGroup 3qt "18 March 2002" "Trolltech AS" \" -*- nroff -*-
.\" Copyright 1992-2001 Trolltech AS. All rights reserved. See the
.\" license file included in the distribution for a complete license
.\" statement.
.\"
.ad l
.nh
.SH NAME
QActionGroup \- Groups actions together
.SH SYNOPSIS
\fC#include <qaction.h>\fR
.PP
Inherits QAction.
.PP
.SS "Public Members"
.in +1c
.ti -1c
.BI "\fBQActionGroup\fR ( QObject * parent, const char * name = 0, bool exclusive = TRUE )"
.br
.ti -1c
.BI "\fB~QActionGroup\fR ()"
.br
.ti -1c
.BI "void \fBsetExclusive\fR ( bool )"
.br
.ti -1c
.BI "bool \fBisExclusive\fR () const"
.br
.ti -1c
.BI "void \fBadd\fR ( QAction * action )"
.br
.ti -1c
.BI "void \fBaddSeparator\fR ()"
.br
.ti -1c
.BI "virtual bool \fBaddTo\fR ( QWidget * w )"
.br
.ti -1c
.BI "void \fBsetUsesDropDown\fR ( bool enable )"
.br
.ti -1c
.BI "bool \fBusesDropDown\fR () const"
.br
.ti -1c
.BI "void insert ( QAction * a ) \fI(obsolete)\fR"
.br
.in -1c
.SS "Signals"
.in +1c
.ti -1c
.BI "void \fBselected\fR ( QAction * )"
.br
.in -1c
.SS "Properties"
.in +1c
.ti -1c
.BI "bool \fBexclusive\fR - whether the action group does exclusive toggling"
.br
.ti -1c
.BI "bool \fBusesDropDown\fR - whether the group's actions are displayed in a subwidget of the widgets the action group is added to"
.br
.in -1c
.SS "Protected Members"
.in +1c
.ti -1c
.BI "virtual void \fBaddedTo\fR ( QWidget * actionWidget, QWidget * container, QAction * a )"
.br
.ti -1c
.BI "virtual void \fBaddedTo\fR ( int index, QPopupMenu * menu, QAction * a )"
.br
.in -1c
.SH DESCRIPTION
The QActionGroup class groups actions together.
.PP
In some situations it is useful to group actions together. For example, if you have a left justify action, a right justify action and a center action, only one of these actions should be active at any one time, and one simple way of achieving this is to group the actions together in an action group and call setExclusive(TRUE).
.PP
An action group can also be added to a menu or a toolbar as a single unit, with all the actions within the action group appearing as separate menu options and toolbar buttons.
.PP
Here's an example from examples/textedit:
.PP
.nf
.br
QActionGroup *grp = new QActionGroup( this );
.br
grp->setExclusive( TRUE );
.br
connect( grp, SIGNAL( selected( QAction* ) ), this, SLOT( textAlign( QAction* ) ) );
.fi
.PP
We create a new action group and call setExclusive() to ensure that only one of the actions in the group is ever active at any one time. We then connect the group's selected() signal to our textAlign() slot.
.PP
.nf
.br
actionAlignLeft = new QAction( tr( "Left" ), QPixmap( "textleft.xpm" ), tr( "&Left" ), CTRL + Key_L, grp, "textLeft" );
.br
actionAlignLeft->addTo( tb );
.br
actionAlignLeft->addTo( menu );
.br
actionAlignLeft->setToggleAction( TRUE );
.fi
.PP
We create a left align action, add it to the toolbar and the menu and make it a toggle action. We create center and right align actions in exactly the same way.
.PP
The actions in an action group emit their activated() (and for toggle actions, toggled()) signals as usual.
.PP
The setExclusive() function is used to ensure that only one action is active at any one time: it should be used with actions which have their toggleAction set to TRUE.
.PP
Action group actions appear as individual menu options and toolbar buttons. For exclusive action groups use setUsesDropDown() to display the actions in a subwidget of any widget the action group is added to. For example, the actions would appear in a combobox in a toolbar or as a submenu in a menu.
.PP
Actions can be added to an action group using add(), but normally they are added by creating the action with the action group as parent. Actions can have separators dividing them using addSeparator(). Action groups are added to widgets with addTo().
.PP
See also Main Window and Related Classes and Basic Widgets.
.SH MEMBER FUNCTION DOCUMENTATION
.SH "QActionGroup::QActionGroup ( QObject * parent, const char * name = 0, bool exclusive = TRUE )"
Constructs an action group with parent \fIparent\fR and name \fIname\fR.
.PP
If \fIexclusive\fR is TRUE only one toggle action in the group will ever be active.
.SH "QActionGroup::~QActionGroup ()"
Destroys the object and frees allocated resources.
.SH "void QActionGroup::add ( QAction * action )"
Adds action \fIaction\fR to this group.
.PP
Normally an action is added to a group by creating it with the group as parent, so this function is not usually used.
.PP
See also addTo().
.SH "void QActionGroup::addSeparator ()"
Adds a separator to the group.
.SH "bool QActionGroup::addTo ( QWidget * w )\fC [virtual]\fR"
Adds this action group to the widget \fIw\fR.
.PP
If usesDropDown() is TRUE and exclusive is TRUE (see setExclusive()) the actions are presented in a combobox if \fIw\fR is a toolbar and as a submenu if \fIw\fR is a menu. Otherwise (the default) the actions within the group are added to the widget individually. For example if the widget is a menu, the actions will appear as individual menu options, and if the widget is a toolbar, the actions will appear as toolbar buttons.
.PP
It is recommended that actions in action groups, especially where usesDropDown() is TRUE, have their menuText() or text() property set.
.PP
All actions should be added to the action group \fIbefore\fR the action group is added to the widget. If actions are added to the action group \fIafter\fR the action group has been added to the widget these later actions will \fInot\fR appear.
.PP
See also exclusive, usesDropDown and removeFrom().
.PP
Examples:
.)l action/actiongroup/editor.cpp and themes/themes.cpp.
.PP
Reimplemented from QAction.
.SH "void QActionGroup::addedTo ( QWidget * actionWidget, QWidget * container, QAction * a )\fC [virtual protected]\fR"
This function is called from the addTo() function when it created a widget (\fIactionWidget\fR) for the child action \fIa\fR in the \fIcontainer\fR.
.SH "void QActionGroup::addedTo ( int index, QPopupMenu * menu, QAction * a )\fC [virtual protected]\fR"
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
.PP
This function is called from the addTo() function when it created a menu item for the child action at the index \fIindex\fR in the popup menu \fImenu\fR.
.SH "void QActionGroup::insert ( QAction * a )"
\fBThis function is obsolete.\fR It is provided to keep old source working. We strongly advise against using it in new code.
.PP
Use add() instead, or better still create the action with the action group as its parent.
.SH "bool QActionGroup::isExclusive () const"
Returns TRUE if the action group does exclusive toggling; otherwise returns FALSE. See the "exclusive" property for details.
.SH "void QActionGroup::selected ( QAction * )\fC [signal]\fR"
This signal is emitted from exclusive groups when toggle actions change state.
.PP
The argument is the action whose state changed to "on".
.PP
.nf
.br
QActionGroup * colors = new QActionGroup( this, "colors", TRUE );
.fi
.PP
.nf
.br
QObject::connect( colors, SIGNAL( selected( QAction * ) ),
.br
this, SLOT( setFontColor( QAction * ) ) );
.fi
.PP
In this example we connect the selected() signal to our own setFontColor() slot, passing the QAction so that we know which action was chosen by the user.
.PP
(See the QActionGroup Walkthrough.)
.PP
See also exclusive and on.
.PP
Examples:
.)l action/actiongroup/editor.cpp and textedit/textedit.cpp.
.SH "void QActionGroup::setExclusive ( bool )"
Sets whether the action group does exclusive toggling. See the "exclusive" property for details.
.SH "void QActionGroup::setUsesDropDown ( bool enable )"
Sets whether the group's actions are displayed in a subwidget of the widgets the action group is added to to \fIenable\fR. See the "usesDropDown" property for details.
.SH "bool QActionGroup::usesDropDown () const"
Returns TRUE if the group's actions are displayed in a subwidget of the widgets the action group is added to; otherwise returns FALSE. See the "usesDropDown" property for details.
.SS "Property Documentation"
.SH "bool exclusive"
This property holds whether the action group does exclusive toggling.
.PP
If exclusive is TRUE only one toggle action in the action group can ever be active at any one time. If the user chooses another toggle action in the group the one they chose becomes active and the one that was active becomes inactive. By default this property is FALSE.
.PP
See also QAction::toggleAction.
.PP
Set this property's value with setExclusive() and get this property's value with isExclusive().
.SH "bool usesDropDown"
This property holds whether the group's actions are displayed in a subwidget of the widgets the action group is added to.
.PP
Exclusive action groups added to a toolbar display their actions in a combobox with the action's QAction::text and QAction::iconSet properties shown. Non-exclusive groups are represented by a tool button showing their QAction::iconSet and -- depending on QMainWindow::usesTextLabel() -- text() property.
.PP
In a popup menu the member actions are displayed in a submenu.
.PP
Changing usesDropDown only effects \fIsubsequent\fR calls to addTo().
.PP
This property's default is FALSE.
.PP
Set this property's value with setUsesDropDown() and get this property's value with usesDropDown().
.SH "SEE ALSO"
.BR http://doc.trolltech.com/qactiongroup.html
.BR http://www.trolltech.com/faq/tech.html
.SH COPYRIGHT
Copyright 1992-2001 Trolltech AS, http://www.trolltech.com. See the
license file included in the distribution for a complete license
statement.
.SH AUTHOR
Generated automatically from the source code.
.SH BUGS
If you find a bug in Qt, please report it as described in
.BR http://doc.trolltech.com/bughowto.html .
Good bug reports help us to help you. Thank you.
.P
The definitive Qt documentation is provided in HTML format; it is
located at $QTDIR/doc/html and can be read using Qt Assistant or with
a web browser. This man page is provided as a convenience for those
users who prefer man pages, although this format is not officially
supported by Trolltech.
.P
If you find errors in this manual page, please report them to
.BR qt-bugs@trolltech.com .
Please include the name of the manual page (qactiongroup.3qt) and the Qt
version (3.0.3).
|
