1/* This file is part of the KDE project
2 Copyright (C) 2002 Anders Lund <anders.lund@lund.tdcadsl.dk>
3
4 This library is free software; you can redistribute it and/or
5 modify it under the terms of the GNU Library General Public
6 License version 2 as published by the Free Software Foundation.
7
8 This library is distributed in the hope that it will be useful,
9 but WITHOUT ANY WARRANTY; without even the implied warranty of
10 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
11 Library General Public License for more details.
12
13 You should have received a copy of the GNU Library General Public License
14 along with this library; see the file COPYING.LIB. If not, write to
15 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
16 Boston, MA 02110-1301, USA.
17*/
18
19#ifndef _KACTION_SELECTOR_H_
20#define _KACTION_SELECTOR_H_
21
22#include <kdeui_export.h>
23#include <QtGui/QWidget>
24
25class QListWidget;
26class QListWidgetItem;
27class QKeyEvent;
28class QEvent;
29class QIcon;
30
31class KActionSelectorPrivate;
32
33/**
34 @short A widget for selecting and arranging actions/objects
35
36 This widget allows the user to select from a set of objects and arrange
37 the order of the selected ones using two list boxes labeled "Available"
38 and "Used" with horizontal arrows in between to move selected objects between
39 the two, and vertical arrows on the right to arrange the order of the selected
40 objects.
41
42 The widget moves objects to the other listbox when doubleclicked if
43 the property moveOnDoubleClick is set to true (default). See moveOnDoubleClick()
44 and setMoveOnDoubleClick().
45
46 The user control the widget using the keyboard if enabled (default),
47 see keyboardEnabled.
48
49 Note that this may conflist with keyboard selection in the selected list box,
50 if you set that to anything else than QListWidget::Single (which is the default).
51
52 To use it, simply construct an instance and then add items to the two listboxes,
53 available through lbAvailable() and lbSelected(). Whenever you want, you can retrieve
54 the selected options using QListWidget methods on lbSelected().
55
56 This way, you can use your own QListWidgetItem class, allowing you to easily
57 store object data in those.
58
59 When an item is moved to a listbox, it is placed below the current item
60 of that listbox.
61
62 Standard arrow icons are used, but you can use icons of your own choice if desired,
63 see setButtonIcon(). It is also possible to set tooltips and whatsthis help
64 for the buttons. See setButtonTooltip() and setButtonWhatsThis().
65
66 To set whatsthis or tooltips for the listboxes, access them through
67 availableListWidget() and selectedListWidget().
68
69 All the moving buttons are automatically set enabled as expected.
70
71 Signals are sent each time an item is moved, allowing you to follow the
72 users actions if you need to. See addedToSelection(), removedFromSelection(),
73 movedUp() and movedDown()
74
75 \image html kactionselector.png "KDE Action Selector"
76
77 @author Anders Lund <anders@alweb.dk>
78*/
79
80class KDEUI_EXPORT KActionSelector : public QWidget {
81 Q_OBJECT
82 Q_ENUMS( InsertionPolicy MoveButton )
83 Q_PROPERTY( bool moveOnDoubleClick READ moveOnDoubleClick WRITE setMoveOnDoubleClick )
84 Q_PROPERTY( bool keyboardEnabled READ keyboardEnabled WRITE setKeyboardEnabled )
85 Q_PROPERTY( QString availableLabel READ availableLabel WRITE setAvailableLabel )
86 Q_PROPERTY( QString selectedLabel READ selectedLabel WRITE setSelectedLabel )
87 Q_PROPERTY( InsertionPolicy availableInsertionPolicy READ availableInsertionPolicy WRITE setAvailableInsertionPolicy )
88 Q_PROPERTY( InsertionPolicy selectedInsertionPolicy READ selectedInsertionPolicy WRITE setSelectedInsertionPolicy )
89 Q_PROPERTY( bool showUpDownButtons READ showUpDownButtons WRITE setShowUpDownButtons )
90
91public:
92 explicit KActionSelector( QWidget *parent=0 );
93 ~KActionSelector();
94
95 /**
96 @return The QListWidget holding the available actions
97 */
98 QListWidget *availableListWidget() const;
99
100 /**
101 @return The QListWidget holding the selected actions
102 */
103 QListWidget *selectedListWidget() const;
104
105 /**
106 This enum indentifies the moving buttons
107 */
108 enum MoveButton {
109 ButtonAdd,
110 ButtonRemove,
111 ButtonUp,
112 ButtonDown
113 };
114
115 /**
116 This enum defines policies for where to insert moved items in a listbox.
117 The following policies are currently defined:
118 @li BelowCurrent - The item is inserted below the listbox'
119 currentItem() or at the end if there is no curent item.
120 @li Sorted - The listbox is sort()ed after one or more items are inserted.
121 @li AtTop - The item is inserted at index 0 in the listbox.
122 @li AtBottom - The item is inserted at the end of the listbox.
123
124 @sa availableInsertionPolicy(), setAvailableInsertionPolicy(),
125 selectedInsertionPolicy(), setSelectedInsertionPolicy().
126 */
127 enum InsertionPolicy {
128 BelowCurrent,
129 Sorted,
130 AtTop,
131 AtBottom
132 };
133
134 /**
135 @return Whether moveOnDoubleClcik is enabled.
136
137 If enabled, an item in any listbox will be moved to the other one whenever
138 doubleclicked.
139 This feature is enabled by default.
140 @sa setMoveOnDoubleClick()
141 */
142 bool moveOnDoubleClick() const;
143
144 /**
145 Sets moveOnDoubleClick to @p enable
146 @sa moveOnDoubleClick()
147 */
148 void setMoveOnDoubleClick( bool enable );
149
150 /**
151 @return Weather keyboard control is enabled.
152
153 When Keyboard control is enabled, the widget will react to
154 the following keyboard actions:
155 @li CTRL + Right - simulate clicking the add button
156 @li CTRL + Left - simulate clicking the remove button
157 @li CTRL + Up - simulate clicking the up button
158 @li CTRL + Down - simulate clicking the down button
159
160 Additionally, pressing RETURN or ENTER on one of the list boxes
161 will cause the current item of that listbox to be moved to the other
162 listbox.
163
164 The keyboard actions are enabled by default.
165
166 @sa setKeyboardEnabled()
167 */
168 bool keyboardEnabled() const;
169
170 /**
171 Sets the keyboard enabled depending on @p enable.
172 @sa keyboardEnabled()
173 */
174 void setKeyboardEnabled( bool enable );
175
176 /**
177 @return The text of the label for the available items listbox.
178 */
179 QString availableLabel() const;
180
181 /**
182 Sets the label for the available items listbox to @p text.
183 Note that this label has the listbox as its @e buddy, so that
184 if you have a single ampersand in the text, the following character
185 will become the accellerator to focus te listbox.
186 */
187 void setAvailableLabel( const QString & text );
188
189 /**
190 @return the label of the selected items listbox.
191 */
192 QString selectedLabel() const;
193
194 /**
195 Sets the label for the selected items listbox to @p text.
196 Note that this label has the listbox as its @e buddy, so that
197 if you have a single ampersand in the text, the following character
198 will become the accellerator to focus te listbox.
199 */
200 void setSelectedLabel( const QString & text );
201
202 /**
203 @return The current insertion policy for the available listbox.
204 The default policy for the available listbox is Sorted.
205 See also InsertionPolicy, setAvailableInsertionPolicy().
206 */
207 InsertionPolicy availableInsertionPolicy() const;
208
209 /**
210 Sets the insertion policy for the available listbox.
211 See also InsertionPolicy, availableInsertionPolicy().
212 */
213 void setAvailableInsertionPolicy( InsertionPolicy policy );
214
215 /**
216 @return The current insertion policy for the selected listbox.
217 The default policy for the selected listbox is BelowCurrent.
218 See also InsertionPolicy, setSelectedInsertionPolicy().
219 */
220 InsertionPolicy selectedInsertionPolicy() const;
221
222 /**
223 Sets the insertion policy for the selected listbox.
224 See also InsertionPolicy, selectedInsertionPolicy().
225 */
226 void setSelectedInsertionPolicy( InsertionPolicy policy );
227
228 /**
229 @return whether the Up and Down buttons should be displayed.
230 */
231 bool showUpDownButtons() const;
232
233 /**
234 Sets whether the Up and Down buttons should be displayed
235 according to @p show
236 */
237 void setShowUpDownButtons( bool show );
238
239 /**
240 Sets the pixmap of the button @p button to @p icon.
241 It calls SmallIconSet(pm) to generate the icon set.
242 */
243 void setButtonIcon( const QString &icon, MoveButton button );
244
245 /**
246 Sets the iconset for button @p button to @p iconset.
247 You can use this method to et a costum icon set. Either
248 created by QIconSet, or use the application instance of
249 KIconLoader (recommended).
250 */
251 void setButtonIconSet( const QIcon &iconset, MoveButton button );
252
253 /**
254 Sets the tooltip for the button @p button to @p tip.
255 */
256 void setButtonTooltip( const QString &tip, MoveButton button );
257
258 /**
259 Sets the whatsthis help for button @p button to @p text.
260 */
261 void setButtonWhatsThis( const QString &text, MoveButton button );
262
263 /**
264 Sets the enabled state of all moving buttons to reflect the current
265 options.
266
267 Be sure to call this if you add or removes items to either listbox after the
268 widget is show()n
269 */
270 void setButtonsEnabled();
271
272Q_SIGNALS:
273 /**
274 Emitted when an item is moved to the "selected" listbox.
275 */
276 void added( QListWidgetItem *item );
277
278 /**
279 Emitted when an item is moved out of the "selected" listbox.
280 */
281 void removed( QListWidgetItem *item );
282
283 /**
284 Emitted when an item is moved upwards in the "selected" listbox.
285 */
286 void movedUp( QListWidgetItem *item );
287
288 /**
289 Emitted when an item is moved downwards in the "selected" listbox.
290 */
291 void movedDown( QListWidgetItem *item );
292
293 /**
294 Emitted when an item is moved to the "selected" listbox.
295 */
296// void addedToSelection( QListWidgetItem *item );
297
298public Q_SLOTS:
299 /**
300 Reimplemented for internal reasons.
301 (calls setButtonsEnabled())
302 */
303 void polish();
304
305protected:
306 /**
307 Reimplamented for internal reasons.
308 */
309 void keyPressEvent( QKeyEvent * );
310
311 /**
312 Reimplemented for internal reasons.
313 */
314 bool eventFilter( QObject *, QEvent * );
315
316private:
317 /**
318 Move selected item from available box to the selected box
319 */
320 Q_PRIVATE_SLOT(d, void buttonAddClicked())
321
322 /**
323 Move selected item from selected box to available box
324 */
325 Q_PRIVATE_SLOT(d, void buttonRemoveClicked())
326
327 /**
328 Move selected item in selected box upwards
329 */
330 Q_PRIVATE_SLOT(d, void buttonUpClicked())
331
332 /**
333 Move seleted item in selected box downwards
334 */
335 Q_PRIVATE_SLOT(d, void buttonDownClicked())
336
337 /**
338 Moves the item @p item to the other listbox if moveOnDoubleClick is enabled.
339 */
340 Q_PRIVATE_SLOT(d, void itemDoubleClicked( QListWidgetItem *item ))
341
342 /**
343 connected to both list boxes to set the buttons enabled
344 */
345 Q_PRIVATE_SLOT(d, void slotCurrentChanged( QListWidgetItem * ))
346
347private:
348
349 /** @private
350 Private data storage
351 */
352 friend class KActionSelectorPrivate;
353 KActionSelectorPrivate * const d;
354
355 Q_DISABLE_COPY(KActionSelector)
356};
357
358#endif // _KACTION_SELECTOR_H_
359