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 | |
38 | class 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 | */ |
51 | class 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 | |
66 | public: |
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. \"&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. \"&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 | , |
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 () const; |
132 | |
133 | /** |
134 | * Set how this list of actions should behave when in popup mode and plugged into a toolbar. |
135 | */ |
136 | void (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 ( & ) 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 ( 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 () const; |
316 | |
317 | /** |
318 | * Changes the text of item @param index to @param text . |
319 | */ |
320 | void changeItem( int index, const QString& text ); |
321 | |
322 | Q_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 | |
341 | protected 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 | |
352 | protected: |
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 | |
378 | private: |
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 | |