File: kactionselector.h

package info (click to toggle)
kwidgetsaddons 5.28.0-3
  • links: PTS, VCS
  • area: main
  • in suites: stretch
  • size: 62,388 kB
  • ctags: 3,611
  • sloc: cpp: 26,647; python: 682; sh: 23; makefile: 6
file content (353 lines) | stat: -rw-r--r-- 11,344 bytes parent folder | download
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
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
/* This file is part of the KDE project
   Copyright (C) 2002 Anders Lund <anders.lund@lund.tdcadsl.dk>

   This library is free software; you can redistribute it and/or
   modify it under the terms of the GNU Library General Public
   License version 2 as published by the Free Software Foundation.

   This library is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   Library General Public License for more details.

   You should have received a copy of the GNU Library General Public License
   along with this library; see the file COPYING.LIB.  If not, write to
   the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
   Boston, MA 02110-1301, USA.
*/

#ifndef _KACTION_SELECTOR_H_
#define _KACTION_SELECTOR_H_

#include <kwidgetsaddons_export.h>
#include <QWidget>

class QListWidget;
class QListWidgetItem;
class QKeyEvent;
class QEvent;
class QIcon;

class KActionSelectorPrivate;

/**
    @short A widget for selecting and arranging actions/objects

    This widget allows the user to select from a set of objects and arrange
    the order of the selected ones using two list boxes labeled "Available"
    and "Used" with horizontal arrows in between to move selected objects between
    the two, and vertical arrows on the right to arrange the order of the selected
    objects.

    The widget moves objects to the other listbox when doubleclicked if
    the property moveOnDoubleClick is set to true (default). See moveOnDoubleClick()
    and setMoveOnDoubleClick().

    The user control the widget using the keyboard if enabled (default),
    see keyboardEnabled.

    Note that this may conflict with keyboard selection in the selected list box,
    if you set that to anything else than QListWidget::Single (which is the default).

    To use it, simply construct an instance and then add items to the two listboxes,
    available through lbAvailable() and lbSelected(). Whenever you want, you can retrieve
    the selected options using QListWidget methods on lbSelected().

    This way, you can use your own QListWidgetItem class, allowing you to easily
    store object data in those.

    When an item is moved to a listbox, it is placed below the current item
    of that listbox.

    Standard arrow icons are used, but you can use icons of your own choice if desired,
    see setButtonIcon(). It is also possible to set tooltips and whatsthis help
    for the buttons. See setButtonTooltip() and setButtonWhatsThis().

    To set whatsthis or tooltips for the listboxes, access them through
    availableListWidget() and selectedListWidget().

    All the moving buttons are automatically set enabled as expected.

    Signals are sent each time an item is moved, allowing you to follow the
    users actions if you need to. See addedToSelection(), removedFromSelection(),
    movedUp() and movedDown()

    \image html kactionselector.png "KDE Action Selector"

    @author Anders Lund <anders@alweb.dk>
*/

class KWIDGETSADDONS_EXPORT KActionSelector : public QWidget
{
    Q_OBJECT
    Q_ENUMS(InsertionPolicy MoveButton)
    Q_PROPERTY(bool moveOnDoubleClick READ moveOnDoubleClick WRITE setMoveOnDoubleClick)
    Q_PROPERTY(bool keyboardEnabled READ keyboardEnabled WRITE setKeyboardEnabled)
    Q_PROPERTY(QString availableLabel READ availableLabel WRITE setAvailableLabel)
    Q_PROPERTY(QString selectedLabel READ selectedLabel WRITE setSelectedLabel)
    Q_PROPERTY(InsertionPolicy availableInsertionPolicy READ availableInsertionPolicy WRITE setAvailableInsertionPolicy)
    Q_PROPERTY(InsertionPolicy selectedInsertionPolicy READ selectedInsertionPolicy WRITE setSelectedInsertionPolicy)
    Q_PROPERTY(bool showUpDownButtons READ showUpDownButtons WRITE setShowUpDownButtons)

public:
    explicit KActionSelector(QWidget *parent = 0);
    ~KActionSelector();

    /**
       @return The QListWidget holding the available actions
    */
    QListWidget *availableListWidget() const;

    /**
       @return The QListWidget holding the selected actions
    */
    QListWidget *selectedListWidget() const;

    /**
      This enum identifies the moving buttons
    */
    enum MoveButton {
        ButtonAdd,
        ButtonRemove,
        ButtonUp,
        ButtonDown
    };

    /**
      This enum defines policies for where to insert moved items in a listbox.
      The following policies are currently defined:
      @li BelowCurrent - The item is inserted below the listbox'
          currentItem() or at the end if there is no current item.
      @li Sorted - The listbox is sort()ed after one or more items are inserted.
      @li AtTop - The item is inserted at index 0 in the listbox.
      @li AtBottom - The item is inserted at the end of the listbox.

      @sa availableInsertionPolicy(), setAvailableInsertionPolicy(),
      selectedInsertionPolicy(), setSelectedInsertionPolicy().
    */
    enum InsertionPolicy {
        BelowCurrent,
        Sorted,
        AtTop,
        AtBottom
    };

    /**
      @return Whether moveOnDoubleClcik is enabled.

      If enabled, an item in any listbox will be moved to the other one whenever
      double-clicked.
      This feature is enabled by default.
      @sa setMoveOnDoubleClick()
    */
    bool moveOnDoubleClick() const;

    /**
      Sets moveOnDoubleClick to @p enable
      @sa moveOnDoubleClick()
    */
    void setMoveOnDoubleClick(bool enable);

    /**
      @return Whether keyboard control is enabled.

      When Keyboard control is enabled, the widget will react to
      the following keyboard actions:
      @li CTRL + Right - simulate clicking the add button
      @li CTRL + Left - simulate clicking the remove button
      @li CTRL + Up - simulate clicking the up button
      @li CTRL + Down - simulate clicking the down button

      Additionally, pressing RETURN or ENTER on one of the list boxes
      will cause the current item of that listbox to be moved to the other
      listbox.

      The keyboard actions are enabled by default.

      @sa setKeyboardEnabled()
    */
    bool keyboardEnabled() const;

    /**
      Sets the keyboard enabled depending on @p enable.
      @sa keyboardEnabled()
    */
    void setKeyboardEnabled(bool enable);

    /**
      @return The text of the label for the available items listbox.
    */
    QString availableLabel() const;

    /**
      Sets the label for the available items listbox to @p text.
      Note that this label has the listbox as its @e buddy, so that
      if you have a single ampersand in the text, the following character
      will become the accelerator to focus the listbox.
    */
    void setAvailableLabel(const QString &text);

    /**
      @return the label of the selected items listbox.
    */
    QString selectedLabel() const;

    /**
      Sets the label for the selected items listbox to @p text.
      Note that this label has the listbox as its @e buddy, so that
      if you have a single ampersand in the text, the following character
      will become the accelerator to focus the listbox.
    */
    void setSelectedLabel(const QString &text);

    /**
      @return The current insertion policy for the available listbox.
      The default policy for the available listbox is Sorted.
      See also InsertionPolicy, setAvailableInsertionPolicy().
    */
    InsertionPolicy availableInsertionPolicy() const;

    /**
      Sets the insertion policy for the available listbox.
      See also InsertionPolicy, availableInsertionPolicy().
    */
    void setAvailableInsertionPolicy(InsertionPolicy policy);

    /**
      @return The current insertion policy for the selected listbox.
      The default policy for the selected listbox is BelowCurrent.
      See also InsertionPolicy, setSelectedInsertionPolicy().
    */
    InsertionPolicy selectedInsertionPolicy() const;

    /**
      Sets the insertion policy for the selected listbox.
      See also InsertionPolicy, selectedInsertionPolicy().
    */
    void setSelectedInsertionPolicy(InsertionPolicy policy);

    /**
      @return whether the Up and Down buttons should be displayed.
    */
    bool showUpDownButtons() const;

    /**
      Sets whether the Up and Down buttons should be displayed
      according to @p show
    */
    void setShowUpDownButtons(bool show);

    /**
      Sets the pixmap of the button @p button to @p icon.
      It calls SmallIconSet(pm) to generate the icon set.
    */
    void setButtonIcon(const QString &icon, MoveButton button);

    /**
      Sets the iconset for button @p button to @p iconset.
      You can use this method to set a custom icon set. Either
      created by QIconSet, or use the application instance of
      KIconLoader (recommended).
    */
    void setButtonIconSet(const QIcon &iconset, MoveButton button);

    /**
      Sets the tooltip for the button @p button to @p tip.
    */
    void setButtonTooltip(const QString &tip, MoveButton button);

    /**
      Sets the whatsthis help for button @p button to @p text.
    */
    void setButtonWhatsThis(const QString &text, MoveButton button);

Q_SIGNALS:
    /**
      Emitted when an item is moved to the "selected" listbox.
    */
    void added(QListWidgetItem *item);

    /**
      Emitted when an item is moved out of the "selected" listbox.
    */
    void removed(QListWidgetItem *item);

    /**
      Emitted when an item is moved upwards in the "selected" listbox.
    */
    void movedUp(QListWidgetItem *item);

    /**
      Emitted when an item is moved downwards in the "selected" listbox.
    */
    void movedDown(QListWidgetItem *item);

    /**
      Emitted when an item is moved to the "selected" listbox.
    */
//  void addedToSelection( QListWidgetItem *item );

public Q_SLOTS:
    /**
       Sets the enabled state of all moving buttons to reflect the current
       options.

       Be sure to call this if you add or removes items to either listbox after the
       widget is shown
    */
    void setButtonsEnabled();

protected:
    /**
      Reimplemented for internal reasons.
    */
    void keyPressEvent(QKeyEvent *) Q_DECL_OVERRIDE;

    /**
      Reimplemented for internal reasons.
    */
    bool eventFilter(QObject *, QEvent *) Q_DECL_OVERRIDE;

private:
    /**
      Move selected item from available box to the selected box
    */
    Q_PRIVATE_SLOT(d, void buttonAddClicked())

    /**
      Move selected item from selected box to available box
    */
    Q_PRIVATE_SLOT(d, void buttonRemoveClicked())

    /**
      Move selected item in selected box upwards
    */
    Q_PRIVATE_SLOT(d, void buttonUpClicked())

    /**
      Move seleted item in selected box downwards
    */
    Q_PRIVATE_SLOT(d, void buttonDownClicked())

    /**
      Moves the item @p item to the other listbox if moveOnDoubleClick is enabled.
    */
    Q_PRIVATE_SLOT(d, void itemDoubleClicked(QListWidgetItem *item))

    /**
      connected to both list boxes to set the buttons enabled
    */
    Q_PRIVATE_SLOT(d, void slotCurrentChanged(QListWidgetItem *))

private:

    /** @private
      Private data storage
    */
    friend class KActionSelectorPrivate;
    KActionSelectorPrivate *const d;

    Q_DISABLE_COPY(KActionSelector)
};

#endif // _KACTION_SELECTOR_H_