File indexing completed on 2024-04-28 03:59:14
0001 /* 0002 This file is part of the KDE libraries 0003 SPDX-FileCopyrightText: 1999 Reginald Stadlbauer <reggie@kde.org> 0004 SPDX-FileCopyrightText: 1999 Simon Hausmann <hausmann@kde.org> 0005 SPDX-FileCopyrightText: 2000 Nicolas Hadacek <haadcek@kde.org> 0006 SPDX-FileCopyrightText: 2000 Kurt Granroth <granroth@kde.org> 0007 SPDX-FileCopyrightText: 2000 Michael Koch <koch@kde.org> 0008 SPDX-FileCopyrightText: 2001 Holger Freyther <freyther@kde.org> 0009 SPDX-FileCopyrightText: 2002 Ellis Whitehead <ellis@kde.org> 0010 SPDX-FileCopyrightText: 2003 Andras Mantia <amantia@kde.org> 0011 SPDX-FileCopyrightText: 2005-2006 Hamish Rodda <rodda@kde.org> 0012 SPDX-FileCopyrightText: 2006 Albert Astals Cid <aacid@kde.org> 0013 SPDX-FileCopyrightText: 2006 Clarence Dang <dang@kde.org> 0014 SPDX-FileCopyrightText: 2006 Michel Hermier <michel.hermier@gmail.com> 0015 SPDX-FileCopyrightText: 2007 Nick Shaforostoff <shafff@ukr.net> 0016 0017 SPDX-License-Identifier: LGPL-2.0-only 0018 */ 0019 0020 #ifndef KSELECTACTION_H 0021 #define KSELECTACTION_H 0022 0023 #include <QToolButton> 0024 #include <QWidgetAction> 0025 #include <memory> 0026 0027 #include <kwidgetsaddons_export.h> 0028 0029 class KSelectActionPrivate; 0030 0031 /** 0032 * @class KSelectAction kselectaction.h KSelectAction 0033 * 0034 * @short Action for selecting one of several items 0035 * 0036 * Action for selecting one of several items. 0037 * 0038 * This action shows up a submenu with a list of items. 0039 * One of them can be checked. If the user clicks on an item 0040 * this item will automatically be checked, 0041 * the formerly checked item becomes unchecked. 0042 * There can be only one item checked at a time. 0043 * 0044 * Porting from KF5 to KF6: 0045 * 0046 * <!-- Using '%' before the old symbol to prevent auto linking here and below --> 0047 * The overloaded signal %KSelectAction::triggered(QAction *action) was renamed 0048 * to KSelectAction::actionTriggered(QAction *action). 0049 * 0050 * The protected virtual method %KSelectAction::actionTriggered(QAction *action) was renamed 0051 * to KSelectAction::slotActionTriggered(QAction *action). 0052 */ 0053 class KWIDGETSADDONS_EXPORT KSelectAction : public QWidgetAction 0054 { 0055 Q_OBJECT 0056 Q_PROPERTY(QAction *currentAction READ currentAction WRITE setCurrentAction) 0057 Q_PROPERTY(bool editable READ isEditable WRITE setEditable) 0058 Q_PROPERTY(int comboWidth READ comboWidth WRITE setComboWidth) 0059 Q_PROPERTY(QString currentText READ currentText) 0060 Q_PROPERTY(ToolBarMode toolBarMode READ toolBarMode WRITE setToolBarMode) 0061 Q_PROPERTY(QToolButton::ToolButtonPopupMode toolButtonPopupMode READ toolButtonPopupMode WRITE setToolButtonPopupMode) 0062 Q_PROPERTY(int currentItem READ currentItem WRITE setCurrentItem) 0063 Q_PROPERTY(QStringList items READ items WRITE setItems) 0064 0065 public: 0066 /** 0067 * Constructs a selection action with the specified parent. 0068 * 0069 * @param parent The action's parent object. 0070 */ 0071 explicit KSelectAction(QObject *parent); 0072 0073 /** 0074 * Constructs a selection action with text; a shortcut may be specified by 0075 * the ampersand character (e.g.\ "&Option" creates a shortcut with key \e O ) 0076 * 0077 * This is the most common KSelectAction used when you do not have a 0078 * corresponding icon (note that it won't appear in the current version 0079 * of the "Edit ToolBar" dialog, because an action needs an icon to be 0080 * plugged in a toolbar...). 0081 * 0082 * @param text The text that will be displayed. 0083 * @param parent The action's parent object. 0084 */ 0085 KSelectAction(const QString &text, QObject *parent); 0086 0087 /** 0088 * Constructs a selection action with text and an icon; a shortcut may be specified by 0089 * the ampersand character (e.g.\ "&Option" creates a shortcut with key \e O ) 0090 * 0091 * This is the other common KSelectAction used. Use it when you 0092 * \e do have a corresponding icon. 0093 * 0094 * @param icon The icon to display. 0095 * @param text The text that will be displayed. 0096 * @param parent The action's parent object. 0097 */ 0098 KSelectAction(const QIcon &icon, const QString &text, QObject *parent); 0099 0100 /** 0101 * Destructor 0102 */ 0103 ~KSelectAction() override; 0104 0105 enum ToolBarMode { 0106 /// Creates a button which pops up a menu when interacted with, as defined by toolButtonPopupMode(). 0107 MenuMode, 0108 /// Creates a combo box which contains the actions. 0109 /// This is the default. 0110 ComboBoxMode, 0111 }; 0112 Q_ENUM(ToolBarMode) 0113 0114 /** 0115 * Returns which type of widget (combo box or button with drop-down menu) will be inserted 0116 * in a toolbar. 0117 */ 0118 ToolBarMode toolBarMode() const; 0119 0120 /** 0121 * Set the type of widget to be inserted in a toolbar to \a mode. 0122 */ 0123 void setToolBarMode(ToolBarMode mode); 0124 0125 /** 0126 * Returns the style for the list of actions, when this action is plugged 0127 * into a KToolBar. The default value is QToolButton::InstantPopup 0128 * 0129 * \sa QToolButton::setPopupMode() 0130 */ 0131 QToolButton::ToolButtonPopupMode toolButtonPopupMode() const; 0132 0133 /** 0134 * Set how this list of actions should behave when in popup mode and plugged into a toolbar. 0135 */ 0136 void setToolButtonPopupMode(QToolButton::ToolButtonPopupMode mode); 0137 0138 /** 0139 * The action group used to create exclusivity between the actions associated with this action. 0140 */ 0141 QActionGroup *selectableActionGroup() const; 0142 0143 /** 0144 * Returns the current QAction. 0145 * @see setCurrentAction 0146 */ 0147 QAction *currentAction() const; 0148 0149 /** 0150 * Returns the index of the current item. 0151 * 0152 * @sa currentText(), currentAction() 0153 */ 0154 int currentItem() const; 0155 0156 /** 0157 * Returns the text of the currently selected item. 0158 * 0159 * @sa currentItem(), currentAction() 0160 */ 0161 QString currentText() const; 0162 0163 /** 0164 * Returns the list of selectable actions 0165 */ 0166 QList<QAction *> actions() const; 0167 0168 /** 0169 * Returns the action at \a index, if one exists. 0170 */ 0171 QAction *action(int index) const; 0172 0173 /** 0174 * Searches for an action with the specified \a text, using a search whose 0175 * case sensitivity is defined by \a cs. 0176 */ 0177 QAction *action(const QString &text, Qt::CaseSensitivity cs = Qt::CaseSensitive) const; 0178 0179 /** 0180 * Sets the currently checked item. 0181 * 0182 * @param action the QAction to become the currently checked item. 0183 * 0184 * \return \e true if a corresponding action was found and successfully checked. 0185 */ 0186 bool setCurrentAction(QAction *action); 0187 0188 /** 0189 * Convenience function to set the currently checked action to be the action 0190 * at index \p index. 0191 * 0192 * If there is no action at that index, the currently checked action (if any) will 0193 * be deselected. 0194 * 0195 * \return \e true if a corresponding action was found and thus set to the current action, otherwise \e false 0196 */ 0197 bool setCurrentItem(int index); 0198 0199 /** 0200 * Overloaded member function, provided for convenience, to set the currently 0201 * checked action to be the action which has \p text as its text(). 0202 * 0203 * If there is no action at that index, the currently checked action (if any) will 0204 * be deselected. 0205 * 0206 * \return \e true if a corresponding action was found, otherwise \e false 0207 */ 0208 bool setCurrentAction(const QString &text, Qt::CaseSensitivity cs = Qt::CaseSensitive); 0209 0210 /** 0211 * Add \a action to the list of selectable actions. 0212 */ 0213 void addAction(QAction *action); 0214 0215 /** 0216 * Overloaded member function, provided for convenience, which creates an action 0217 * from \p text and inserts it into the list of selectable actions. 0218 * 0219 * The newly created action is checkable and not user configurable. 0220 */ 0221 QAction *addAction(const QString &text); 0222 0223 /** 0224 * Overloaded member function, provided for convenience, which creates an action 0225 * from \p text and \p icon and inserts it into the list of selectable actions. 0226 * 0227 * The newly created action is checkable and not user configurable. 0228 */ 0229 QAction *addAction(const QIcon &icon, const QString &text); 0230 0231 /** 0232 * Remove the specified \a action from this action selector. 0233 * 0234 * You take ownership here, so save or delete it in order to not leak the action. 0235 */ 0236 virtual QAction *removeAction(QAction *action); 0237 0238 /** 0239 * Inserts the action action to this widget's list of actions, before the action before. 0240 * It appends the action if before is a null pointer or before is not a valid action for this widget. 0241 * 0242 * @since 5.0 0243 */ 0244 virtual void insertAction(QAction *before, QAction *action); 0245 0246 /** 0247 * Convenience function to create the list of selectable items. 0248 * Any previously existing items will be cleared. 0249 */ 0250 void setItems(const QStringList &lst); 0251 0252 /** 0253 * Convenience function which returns the items that can be selected with this action. 0254 * It is the same as iterating selectableActionGroup()->actions() and looking at each 0255 * action's text(). 0256 */ 0257 QStringList items() const; 0258 0259 /** 0260 * When this action is plugged into a toolbar, it creates a combobox. 0261 * @return true if the combo editable. 0262 */ 0263 bool isEditable() const; 0264 0265 /** 0266 * When this action is plugged into a toolbar, it creates a combobox. 0267 * This makes the combo editable or read-only. 0268 */ 0269 void setEditable(bool); 0270 0271 /** 0272 * When this action is plugged into a toolbar, it creates a combobox. 0273 * This returns the maximum width set by setComboWidth 0274 */ 0275 int comboWidth() const; 0276 0277 /** 0278 * When this action is plugged into a toolbar, it creates a combobox. 0279 * This gives a _maximum_ size to the combobox. 0280 * The minimum size is automatically given by the contents (the items). 0281 */ 0282 void setComboWidth(int width); 0283 0284 /** 0285 * Sets the maximum items that are visible at once if the action 0286 * is a combobox, that is the number of items in the combobox's viewport 0287 */ 0288 void setMaxComboViewCount(int n); 0289 0290 /** 0291 * Remove and delete all the items in this action. 0292 * 0293 * @see removeAllActions() 0294 */ 0295 void clear(); 0296 0297 /** 0298 * Remove all the items in this action. 0299 * 0300 * Unlike clear(), this will not delete the actions. 0301 * 0302 * @see clear() 0303 */ 0304 void removeAllActions(); 0305 0306 /** 0307 * Sets whether any occurrence of the ampersand character ( & ) in items 0308 * should be interpreted as keyboard accelerator for items displayed in a 0309 * menu or not. Only applies to (overloaded) methods dealing with QStrings, 0310 * not those dealing with QActions. 0311 * 0312 * Defaults to true. 0313 * 0314 * \param b true if ampersands indicate a keyboard accelerator, otherwise false. 0315 */ 0316 void setMenuAccelsEnabled(bool b); 0317 0318 /** 0319 * Returns whether ampersands passed to methods using QStrings are interpreted 0320 * as keyboard accelerator indicators or as literal ampersands. 0321 */ 0322 bool menuAccelsEnabled() const; 0323 0324 /** 0325 * You should delete KSelectAction::menu() before calling setMenu(). KSelectAction 0326 * will take the @param menu ownership and it will be deleted when KSelectAction is 0327 * destroyed. 0328 */ 0329 using QWidgetAction::setMenu; 0330 0331 /** 0332 * Changes the text of item @param index to @param text . 0333 */ 0334 void changeItem(int index, const QString &text); 0335 0336 Q_SIGNALS: 0337 /** 0338 * This signal is emitted when an item is selected. 0339 * @param action indicates the item selected 0340 * 0341 * @since 6.0 0342 */ 0343 void actionTriggered(QAction *action); 0344 0345 /** 0346 * This signal is emitted when an item is selected. 0347 * @param index indicates the item selected 0348 * 0349 * @since 5.78 0350 */ 0351 void indexTriggered(int index); 0352 0353 /** 0354 * This signal is emitted when an item is selected. 0355 * @param text indicates the item selected 0356 * 0357 * @since 5.78 0358 */ 0359 void textTriggered(const QString &text); 0360 0361 protected Q_SLOTS: 0362 /** 0363 * This function is called whenever an action from the selections is triggered. 0364 * The default implementation calls trigger() if isCheckable() is @c true, then emits 0365 * the signals actionTriggered(QAction *), indexTriggered(int) and textTriggered(const QString &). 0366 * 0367 * @since 6.0 0368 */ 0369 virtual void slotActionTriggered(QAction *action); 0370 0371 /** 0372 * For structured menu building. Deselects all items if the action was unchecked by the top menu 0373 */ 0374 void slotToggled(bool); 0375 0376 protected: 0377 /** 0378 * Reimplemented from QWidgetAction. 0379 */ 0380 QWidget *createWidget(QWidget *parent) override; 0381 0382 /** 0383 * Reimplemented from QWidgetAction. 0384 */ 0385 void deleteWidget(QWidget *widget) override; 0386 0387 bool event(QEvent *event) override; 0388 0389 bool eventFilter(QObject *watched, QEvent *event) override; 0390 0391 /** 0392 * @internal 0393 * Creates a new KSelectAction object. 0394 * 0395 * @param dd the private d member 0396 * @param parent The action's parent object. 0397 */ 0398 KWIDGETSADDONS_NO_EXPORT KSelectAction(KSelectActionPrivate &dd, QObject *parent); 0399 0400 std::unique_ptr<class KSelectActionPrivate> const d_ptr; 0401 0402 private: 0403 Q_DECLARE_PRIVATE(KSelectAction) 0404 }; 0405 0406 #endif