File indexing completed on 2025-02-02 14:19:55
0001 /* 0002 This file is part of the KDE project 0003 SPDX-FileCopyrightText: 2002 Anders Lund <anders.lund@lund.tdcadsl.dk> 0004 0005 SPDX-License-Identifier: LGPL-2.0-only 0006 */ 0007 0008 #ifndef _KACTION_SELECTOR_H_ 0009 #define _KACTION_SELECTOR_H_ 0010 0011 #include <QWidget> 0012 #include <kwidgetsaddons_export.h> 0013 #include <memory> 0014 0015 class QListWidget; 0016 class QListWidgetItem; 0017 class QKeyEvent; 0018 class QEvent; 0019 class QIcon; 0020 0021 /** 0022 @class KActionSelector kactionselector.h KActionSelector 0023 0024 @short A widget for selecting and arranging actions/objects 0025 0026 This widget allows the user to select from a set of objects and arrange 0027 the order of the selected ones using two list boxes labeled "Available" 0028 and "Used" with horizontal arrows in between to move selected objects between 0029 the two, and vertical arrows on the right to arrange the order of the selected 0030 objects. 0031 0032 The widget moves objects to the other listbox when doubleclicked if 0033 the property moveOnDoubleClick is set to true (default). See moveOnDoubleClick() 0034 and setMoveOnDoubleClick(). 0035 0036 The user control the widget using the keyboard if enabled (default), 0037 see keyboardEnabled. 0038 0039 Note that this may conflict with keyboard selection in the selected list box, 0040 if you set that to anything else than QListWidget::Single (which is the default). 0041 0042 To use it, simply construct an instance and then add items to the two listboxes, 0043 available through lbAvailable() and lbSelected(). Whenever you want, you can retrieve 0044 the selected options using QListWidget methods on lbSelected(). 0045 0046 This way, you can use your own QListWidgetItem class, allowing you to easily 0047 store object data in those. 0048 0049 When an item is moved to a listbox, it is placed below the current item 0050 of that listbox. 0051 0052 Standard arrow icons are used, but you can use icons of your own choice if desired, 0053 see setButtonIcon(). It is also possible to set tooltips and whatsthis help 0054 for the buttons. See setButtonTooltip() and setButtonWhatsThis(). 0055 0056 To set whatsthis or tooltips for the listboxes, access them through 0057 availableListWidget() and selectedListWidget(). 0058 0059 All the moving buttons are automatically set enabled as expected. 0060 0061 Signals are sent each time an item is moved, allowing you to follow the 0062 users actions if you need to. See addedToSelection(), removedFromSelection(), 0063 movedUp() and movedDown() 0064 0065 \image html kactionselector.png "KActionSelector Widget" 0066 0067 @author Anders Lund <anders@alweb.dk> 0068 */ 0069 class KWIDGETSADDONS_EXPORT KActionSelector : public QWidget 0070 { 0071 Q_OBJECT 0072 Q_PROPERTY(bool moveOnDoubleClick READ moveOnDoubleClick WRITE setMoveOnDoubleClick) 0073 Q_PROPERTY(bool keyboardEnabled READ keyboardEnabled WRITE setKeyboardEnabled) 0074 Q_PROPERTY(QString availableLabel READ availableLabel WRITE setAvailableLabel) 0075 Q_PROPERTY(QString selectedLabel READ selectedLabel WRITE setSelectedLabel) 0076 Q_PROPERTY(InsertionPolicy availableInsertionPolicy READ availableInsertionPolicy WRITE setAvailableInsertionPolicy) 0077 Q_PROPERTY(InsertionPolicy selectedInsertionPolicy READ selectedInsertionPolicy WRITE setSelectedInsertionPolicy) 0078 Q_PROPERTY(bool showUpDownButtons READ showUpDownButtons WRITE setShowUpDownButtons) 0079 0080 public: 0081 explicit KActionSelector(QWidget *parent = nullptr); 0082 ~KActionSelector() override; 0083 0084 /** 0085 * @return The QListWidget holding the available actions 0086 */ 0087 QListWidget *availableListWidget() const; 0088 0089 /** 0090 * @return The QListWidget holding the selected actions 0091 */ 0092 QListWidget *selectedListWidget() const; 0093 0094 /** 0095 * This enum identifies the moving buttons 0096 */ 0097 enum MoveButton { 0098 ButtonAdd, 0099 ButtonRemove, 0100 ButtonUp, 0101 ButtonDown, 0102 }; 0103 Q_ENUM(MoveButton) 0104 0105 /** 0106 * This enum defines policies for where to insert moved items in a listbox. 0107 * 0108 * @sa availableInsertionPolicy(), setAvailableInsertionPolicy(), 0109 * selectedInsertionPolicy(), setSelectedInsertionPolicy() 0110 */ 0111 enum InsertionPolicy { 0112 BelowCurrent, ///< The item is inserted below the listbox' currentItem() or at the end if there is no current item. 0113 Sorted, ///< The listbox is sort()ed after one or more items are inserted. 0114 AtTop, ///< The item is inserted at index 0 in the listbox. 0115 AtBottom, ///< The item is inserted at the end of the listbox. 0116 }; 0117 Q_ENUM(InsertionPolicy) 0118 0119 /** 0120 * @return Whether moveOnDoubleClcik is enabled. 0121 * 0122 * If enabled, an item in any listbox will be moved to the other one whenever 0123 * double-clicked. 0124 * This feature is enabled by default. 0125 * @sa setMoveOnDoubleClick() 0126 */ 0127 bool moveOnDoubleClick() const; 0128 0129 /** 0130 * Sets moveOnDoubleClick to @p enable 0131 * @sa moveOnDoubleClick() 0132 */ 0133 void setMoveOnDoubleClick(bool enable); 0134 0135 /** 0136 * @return Whether keyboard control is enabled. 0137 * 0138 * When Keyboard control is enabled, the widget will react to 0139 * the following keyboard actions: 0140 * @li CTRL + Right - simulate clicking the add button 0141 * @li CTRL + Left - simulate clicking the remove button 0142 * @li CTRL + Up - simulate clicking the up button 0143 * @li CTRL + Down - simulate clicking the down button 0144 * 0145 * Additionally, pressing RETURN or ENTER on one of the list boxes 0146 * will cause the current item of that listbox to be moved to the other 0147 * listbox. 0148 * 0149 * The keyboard actions are enabled by default. 0150 * 0151 * @sa setKeyboardEnabled() 0152 */ 0153 bool keyboardEnabled() const; 0154 0155 /** 0156 * Sets the keyboard enabled depending on @p enable. 0157 * @sa keyboardEnabled() 0158 */ 0159 void setKeyboardEnabled(bool enable); 0160 0161 /** 0162 * @return The text of the label for the available items listbox. 0163 */ 0164 QString availableLabel() const; 0165 0166 /** 0167 * Sets the label for the available items listbox to @p text. 0168 * Note that this label has the listbox as its @e buddy, so that 0169 * if you have a single ampersand in the text, the following character 0170 * will become the accelerator to focus the listbox. 0171 */ 0172 void setAvailableLabel(const QString &text); 0173 0174 /** 0175 * @return the label of the selected items listbox. 0176 */ 0177 QString selectedLabel() const; 0178 0179 /** 0180 * Sets the label for the selected items listbox to @p text. 0181 * Note that this label has the listbox as its @e buddy, so that 0182 * if you have a single ampersand in the text, the following character 0183 * will become the accelerator to focus the listbox. 0184 */ 0185 void setSelectedLabel(const QString &text); 0186 0187 /** 0188 * @return The current insertion policy for the available listbox. 0189 * The default policy for the available listbox is Sorted. 0190 * @sa InsertionPolicy, setAvailableInsertionPolicy() 0191 */ 0192 InsertionPolicy availableInsertionPolicy() const; 0193 0194 /** 0195 * Sets the insertion policy for the available listbox. 0196 * @sa InsertionPolicy, availableInsertionPolicy() 0197 */ 0198 void setAvailableInsertionPolicy(InsertionPolicy policy); 0199 0200 /** 0201 * @return The current insertion policy for the selected listbox. 0202 * The default policy for the selected listbox is BelowCurrent. 0203 * @sa InsertionPolicy, setSelectedInsertionPolicy() 0204 */ 0205 InsertionPolicy selectedInsertionPolicy() const; 0206 0207 /** 0208 * Sets the insertion policy for the selected listbox. 0209 * @sa InsertionPolicy, selectedInsertionPolicy() 0210 */ 0211 void setSelectedInsertionPolicy(InsertionPolicy policy); 0212 0213 /** 0214 * @return whether the Up and Down buttons should be displayed. 0215 */ 0216 bool showUpDownButtons() const; 0217 0218 /** 0219 * Sets whether the Up and Down buttons should be displayed 0220 * according to @p show 0221 */ 0222 void setShowUpDownButtons(bool show); 0223 0224 /** 0225 * Sets the pixmap of the button @p button to @p icon. 0226 * It calls SmallIconSet(pm) to generate the icon set. 0227 */ 0228 void setButtonIcon(const QString &icon, MoveButton button); 0229 0230 /** 0231 * Sets the iconset for button @p button to @p iconset. 0232 * You can use this method to set a custom icon set. Either 0233 * created by QIconSet, or use the application instance of 0234 * KIconLoader (recommended). 0235 */ 0236 void setButtonIconSet(const QIcon &iconset, MoveButton button); 0237 0238 /** 0239 * Sets the tooltip for the button @p button to @p tip. 0240 */ 0241 void setButtonTooltip(const QString &tip, MoveButton button); 0242 0243 /** 0244 * Sets the whatsthis help for button @p button to @p text. 0245 */ 0246 void setButtonWhatsThis(const QString &text, MoveButton button); 0247 0248 Q_SIGNALS: 0249 /** 0250 * Emitted when an item is moved to the "selected" listbox. 0251 */ 0252 void added(QListWidgetItem *item); 0253 0254 /** 0255 * Emitted when an item is moved out of the "selected" listbox. 0256 */ 0257 void removed(QListWidgetItem *item); 0258 0259 /** 0260 * Emitted when an item is moved upwards in the "selected" listbox. 0261 */ 0262 void movedUp(QListWidgetItem *item); 0263 0264 /** 0265 * Emitted when an item is moved downwards in the "selected" listbox. 0266 */ 0267 void movedDown(QListWidgetItem *item); 0268 0269 /** 0270 * Emitted when an item is moved to the "selected" listbox. 0271 */ 0272 // void addedToSelection( QListWidgetItem *item ); 0273 0274 public Q_SLOTS: 0275 /** 0276 * Sets the enabled state of all moving buttons to reflect the current 0277 * options. 0278 * 0279 * Be sure to call this if you add or removes items to either listbox after the 0280 * widget is shown 0281 */ 0282 void setButtonsEnabled(); 0283 0284 protected: 0285 /** 0286 * Reimplemented for internal reasons. 0287 */ 0288 void keyPressEvent(QKeyEvent *) override; 0289 0290 /** 0291 * Reimplemented for internal reasons. 0292 */ 0293 bool eventFilter(QObject *, QEvent *) override; 0294 0295 private: 0296 /** 0297 * @private 0298 * Private data storage 0299 */ 0300 friend class KActionSelectorPrivate; 0301 std::unique_ptr<class KActionSelectorPrivate> const d; 0302 0303 Q_DISABLE_COPY(KActionSelector) 0304 }; 0305 0306 #endif // _KACTION_SELECTOR_H_