1/* This file is part of the KDE libraries
2 Copyright (C) 1999 Reginald Stadlbauer <reggie@kde.org>
3 (C) 1999 Simon Hausmann <hausmann@kde.org>
4 (C) 2000 Nicolas Hadacek <haadcek@kde.org>
5 (C) 2000 Kurt Granroth <granroth@kde.org>
6 (C) 2000 Michael Koch <koch@kde.org>
7 (C) 2001 Holger Freyther <freyther@kde.org>
8 (C) 2002 Ellis Whitehead <ellis@kde.org>
9 (C) 2003 Andras Mantia <amantia@kde.org>
10 (C) 2005-2006 Hamish Rodda <rodda@kde.org>
11 (C) 2006 Albert Astals Cid <aacid@kde.org>
12 (C) 2006 Clarence Dang <dang@kde.org>
13 (C) 2006 Michel Hermier <michel.hermier@gmail.com>
14 (C) 2007 Nick Shaforostoff <shafff@ukr.net>
15
16 This library is free software; you can redistribute it and/or
17 modify it under the terms of the GNU Library General Public
18 License version 2 as published by the Free Software Foundation.
19
20 This library is distributed in the hope that it will be useful,
21 but WITHOUT ANY WARRANTY; without even the implied warranty of
22 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
23 Library General Public License for more details.
24
25 You should have received a copy of the GNU Library General Public License
26 along with this library; see the file COPYING.LIB. If not, write to
27 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
28 Boston, MA 02110-1301, USA.
29*/
30
31#ifndef KSELECTACTION_H
32#define KSELECTACTION_H
33
34#include <QtGui/QToolButton>
35
36#include <kaction.h>
37
38class KSelectActionPrivate;
39
40/**
41 * @short Action for selecting one of several items
42 *
43 * Action for selecting one of several items.
44 *
45 * This action shows up a submenu with a list of items.
46 * One of them can be checked. If the user clicks on an item
47 * this item will automatically be checked,
48 * the formerly checked item becomes unchecked.
49 * There can be only one item checked at a time.
50 */
51class KDEUI_EXPORT KSelectAction : public KAction
52{
53 Q_OBJECT
54 Q_PROPERTY( QAction* currentAction READ currentAction WRITE setCurrentAction )
55 Q_PROPERTY( bool editable READ isEditable WRITE setEditable )
56 Q_PROPERTY( int comboWidth READ comboWidth WRITE setComboWidth )
57 Q_PROPERTY( QString currentText READ currentText )
58 Q_ENUMS( ToolBarMode )
59 Q_PROPERTY( ToolBarMode toolBarMode READ toolBarMode WRITE setToolBarMode )
60 Q_PROPERTY( QToolButton::ToolButtonPopupMode toolButtonPopupMode READ toolButtonPopupMode WRITE setToolButtonPopupMode )
61 Q_PROPERTY( int currentItem READ currentItem WRITE setCurrentItem )
62 Q_PROPERTY( QStringList items READ items WRITE setItems )
63 Q_DECLARE_PRIVATE(KSelectAction)
64
65
66public:
67 /**
68 * Constructs a selection action with the specified parent.
69 *
70 * @param parent The action's parent object.
71 */
72 explicit KSelectAction(QObject *parent);
73
74 /**
75 * Constructs a selection action with text; a shortcut may be specified by
76 * the ampersand character (e.g. \"&amp;Option\" creates a shortcut with key \e O )
77 *
78 * This is the most common KSelectAction used when you do not have a
79 * corresponding icon (note that it won't appear in the current version
80 * of the "Edit ToolBar" dialog, because an action needs an icon to be
81 * plugged in a toolbar...).
82 *
83 * @param text The text that will be displayed.
84 * @param parent The action's parent object.
85 */
86 KSelectAction(const QString& text, QObject *parent);
87
88 /**
89 * Constructs a selection action with text and an icon; a shortcut may be specified by
90 * the ampersand character (e.g. \"&amp;Option\" creates a shortcut with key \e O )
91 *
92 * This is the other common KSelectAction used. Use it when you
93 * \e do have a corresponding icon.
94 *
95 * @param icon The icon to display.
96 * @param text The text that will be displayed.
97 * @param parent The action's parent object.
98 */
99 KSelectAction(const KIcon& icon, const QString& text, QObject *parent);
100
101 /**
102 * Destructor
103 */
104 virtual ~KSelectAction();
105
106 enum ToolBarMode {
107 /// Creates a button which pops up a menu when interacted with, as defined by toolButtonPopupMode().
108 MenuMode,
109 /// Creates a combo box which contains the actions.
110 /// This is the default.
111 ComboBoxMode
112 };
113
114 /**
115 * Returns which type of widget (combo box or button with drop-down menu) will be inserted
116 * in a toolbar.
117 */
118 ToolBarMode toolBarMode() const;
119
120 /**
121 * Set the type of widget to be inserted in a toolbar to \a mode.
122 */
123 void setToolBarMode(ToolBarMode mode);
124
125 /**
126 * Returns the style for the list of actions, when this action is plugged
127 * into a KToolBar. The default value is QToolButton::InstantPopup
128 *
129 * \sa QToolButton::setPopupMode()
130 */
131 QToolButton::ToolButtonPopupMode toolButtonPopupMode() const;
132
133 /**
134 * Set how this list of actions should behave when in popup mode and plugged into a toolbar.
135 */
136 void setToolButtonPopupMode(QToolButton::ToolButtonPopupMode mode);
137
138 /**
139 * The action group used to create exclusivity between the actions associated with this action.
140 */
141 QActionGroup* selectableActionGroup() const;
142
143 /**
144 * Returns the current QAction.
145 * @see setCurrentAction
146 */
147 QAction* currentAction() const;
148
149 /**
150 * Returns the index of the current item.
151 *
152 * @sa currentItem and currentAction
153 */
154 int currentItem() const;
155
156 /**
157 * Returns the text of the currently selected item.
158 *
159 * @sa currentItem and currentAction
160 */
161 QString currentText() const;
162
163 /**
164 * Returns the list of selectable actions
165 */
166 QList<QAction*> actions() const;
167
168 /**
169 * Returns the action at \a index, if one exists.
170 */
171 QAction* action(int index) const;
172
173 /**
174 * Searches for an action with the specified \a text, using a search whose
175 * case sensitivity is defined by \a cs.
176 */
177 QAction* action(const QString& text, Qt::CaseSensitivity cs = Qt::CaseSensitive) const;
178
179 /**
180 * Sets the currently checked item.
181 *
182 * @param action the QAction to become the currently checked item.
183 *
184 * \return \e true if a corresponding action was found and successfully checked.
185 */
186 bool setCurrentAction(QAction* action);
187
188 /**
189 * \overload setCurrentAction(QAction*)
190 *
191 * Convenience function to set the currently checked action to be the action
192 * at index \p index.
193 *
194 * If there is no action at that index, the currently checked action (if any) will
195 * be deselected.
196 *
197 * \return \e true if a corresponding action was found and thus set to the current action, otherwise \e false
198 */
199 bool setCurrentItem(int index);
200
201 /**
202 * \overload setCurrentAction(QAction*)
203 *
204 * Convenience function to set the currently checked action to be the action
205 * which has \p text as its text().
206 *
207 * If there is no action at that index, the currently checked action (if any) will
208 * be deselected.
209 *
210 * \return \e true if a corresponding action was found, otherwise \e false
211 */
212 bool setCurrentAction(const QString& text, Qt::CaseSensitivity cs = Qt::CaseSensitive);
213
214 /**
215 * Add \a action to the list of selectable actions.
216 */
217 virtual void addAction(QAction* action);
218
219 /**
220 * \overload addAction(QAction* action)
221 *
222 * Convenience function which creates an action from \a text and inserts it into
223 * the list of selectable actions.
224 *
225 * The newly created action is checkable and not user configurable.
226 */
227 KAction* addAction(const QString& text);
228
229 /**
230 * \overload addAction(QAction* action)
231 *
232 * Convenience function which creates an action from \a text and \a icon and inserts it into
233 * the list of selectable actions.
234 *
235 * The newly created action is checkable and not user configurable.
236 */
237 KAction* addAction(const KIcon& icon, const QString& text);
238
239 /**
240 * Remove the specified \a action from this action selector.
241 *
242 * You take ownership here, so save or delete it in order to not leak the action.
243 */
244 virtual QAction* removeAction(QAction* action);
245
246 /**
247 * Convenience function to create the list of selectable items.
248 * Any previously existing items will be cleared.
249 */
250 void setItems( const QStringList &lst );
251
252 /**
253 * Convenience function which returns the items that can be selected with this action.
254 * It is the same as iterating selectableActionGroup()->actions() and looking at each
255 * action's text().
256 */
257 QStringList items() const;
258
259 /**
260 * When this action is plugged into a toolbar, it creates a combobox.
261 * @return true if the combo editable.
262 */
263 bool isEditable() const;
264
265 /**
266 * When this action is plugged into a toolbar, it creates a combobox.
267 * This makes the combo editable or read-only.
268 */
269 void setEditable( bool );
270
271 /**
272 * When this action is plugged into a toolbar, it creates a combobox.
273 * This returns the maximum width set by setComboWidth
274 */
275 int comboWidth() const;
276
277 /**
278 * When this action is plugged into a toolbar, it creates a combobox.
279 * This gives a _maximum_ size to the combobox.
280 * The minimum size is automatically given by the contents (the items).
281 */
282 void setComboWidth( int width );
283
284 /**
285 * Sets the maximum items that are visible at once if the action
286 * is a combobox, that is the number of items in the combobox's viewport
287 */
288 void setMaxComboViewCount( int n );
289
290 /**
291 * Clears up all the items in this action.
292 * \warning The actions will be deleted for backwards compatibility with KDE3.
293 * If you just want to remove all actions, use removeAllActions()
294 */
295 void clear();
296
297 void removeAllActions();
298
299 /**
300 * Sets whether any occurrence of the ampersand character ( &amp; ) in items
301 * should be interpreted as keyboard accelerator for items displayed in a
302 * menu or not. Only applies to (overloaded) methods dealing with QStrings,
303 * not those dealing with QActions.
304 *
305 * Defaults to true.
306 *
307 * \param b true if ampersands indicate a keyboard accelerator, otherwise false.
308 */
309 void setMenuAccelsEnabled( bool b );
310
311 /**
312 * Returns whether ampersands passed to methods using QStrings are interpreted
313 * as keyboard accelerator indicators or as literal ampersands.
314 */
315 bool menuAccelsEnabled() const;
316
317 /**
318 * Changes the text of item @param index to @param text .
319 */
320 void changeItem( int index, const QString& text );
321
322Q_SIGNALS:
323 /**
324 * This signal is emitted when an item is selected; @param action
325 * indicates the item selected.
326 */
327 void triggered( QAction* action );
328
329 /**
330 * This signal is emitted when an item is selected; @param index indicates
331 * the item selected.
332 */
333 void triggered( int index );
334
335 /**
336 * This signal is emitted when an item is selected; @param text indicates
337 * the item selected.
338 */
339 void triggered( const QString& text );
340
341protected Q_SLOTS:
342 /**
343 * This function is called whenever an action from the selections is triggered.
344 */
345 virtual void actionTriggered(QAction* action);
346
347 /**
348 * For structured menu building. Deselects all items if the action was unchecked by the top menu
349 */
350 void slotToggled(bool);
351
352protected:
353 /**
354 * Reimplemented from @see QWidgetAction.
355 */
356 virtual QWidget *createWidget(QWidget *parent);
357
358 /**
359 * Reimplemented from @see QWidgetAction.
360 */
361 virtual void deleteWidget(QWidget *widget);
362
363 virtual bool event(QEvent *event);
364
365 virtual bool eventFilter (QObject *watched, QEvent *event);
366
367 /**
368 * @internal
369 * Creates a new KSelectAction object.
370 *
371 * @param dd the private d member
372 * @param parent The action's parent object.
373 */
374 KSelectAction(KSelectActionPrivate &dd, QObject *parent);
375
376 KSelectActionPrivate *d_ptr;
377
378private:
379 Q_PRIVATE_SLOT( d_func(), void _k_comboBoxDeleted(QObject*) )
380 Q_PRIVATE_SLOT( d_func(), void _k_comboBoxCurrentIndexChanged(int) )
381};
382
383#endif
384