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

source code of kwidgetsaddons/src/kactionselector.h