KXmlGui

kkeysequencewidget.h
1 /*
2  This file is part of the KDE libraries
3  SPDX-FileCopyrightText: 2001, 2002 Ellis Whitehead <[email protected]>
4  SPDX-FileCopyrightText: 2007 Andreas Hartmetz <[email protected]>
5 
6  SPDX-License-Identifier: LGPL-2.0-or-later
7 */
8 
9 #ifndef KKEYSEQUENCEWIDGET_H
10 #define KKEYSEQUENCEWIDGET_H
11 
12 #include <kxmlgui_export.h>
13 
14 #include <QList>
15 #include <QPushButton>
16 
17 class KKeySequenceWidgetPrivate;
18 class QAction;
19 class KActionCollection;
20 
21 /**
22  * @class KKeySequenceWidget kkeysequencewidget.h KKeySequenceWidget
23  *
24  * @short A widget to input a QKeySequence.
25  *
26  * This widget lets the user choose a QKeySequence, which is usually used as a
27  * shortcut key. The recording is initiated by calling captureKeySequence() or
28  * the user clicking into the widget.
29  *
30  * The widgets provides support for conflict handling. See
31  * setCheckForConflictsAgainst() for more information.
32  *
33  * \image html kkeysequencewidget.png "KKeySequenceWidget"
34  *
35  * @author Mark Donohoe <[email protected]>
36  */
37 class KXMLGUI_EXPORT KKeySequenceWidget : public QWidget
38 {
39  Q_OBJECT
40 
41  /// @since 5.65
42  Q_PROPERTY(QKeySequence keySequence READ keySequence WRITE setKeySequence NOTIFY keySequenceChanged)
43 
44  Q_PROPERTY(bool multiKeyShortcutsAllowed READ multiKeyShortcutsAllowed WRITE setMultiKeyShortcutsAllowed)
45 
46  Q_PROPERTY(ShortcutTypes checkForConflictsAgainst READ checkForConflictsAgainst WRITE setCheckForConflictsAgainst)
47 
48  Q_PROPERTY(bool modifierlessAllowed READ isModifierlessAllowed WRITE setModifierlessAllowed)
49 
50 public:
51  /// An enum about validation when setting a key sequence.
52  ///@see setKeySequence()
53  enum Validation {
54  /// Validate key sequence
55  Validate = 0,
56  /// Use key sequence without validation
57  NoValidate = 1,
58  };
59 
60  /**
61  * Constructor.
62  */
63  explicit KKeySequenceWidget(QWidget *parent = nullptr);
64 
65  /**
66  * Destructs the widget.
67  */
68  ~KKeySequenceWidget() override;
69 
70  /**
71  * \name Configuration
72  *
73  * Configuration options for the widget.
74  * @see ShortcutTypes
75  */
76  //@{
77 
78  enum ShortcutType {
79  None = 0x00, //!< No checking for conflicts
80  LocalShortcuts = 0x01, //!< Check with local shortcuts. @see setCheckActionCollections()
81  StandardShortcuts = 0x02, //!< Check against standard shortcuts. @see KStandardShortcut
82  GlobalShortcuts = 0x04, //!< Check against global shortcuts. @see KGlobalAccel
83  };
84  /**
85  * Stores a combination of #ShortcutType values.
86  */
87  Q_DECLARE_FLAGS(ShortcutTypes, ShortcutType)
89 
90  /**
91  * Configure if the widget should check for conflicts with existing
92  * shortcuts.
93  *
94  * When capturing a key sequence for local shortcuts you should check
95  * against GlobalShortcuts and your other local shortcuts. This is the
96  * default.
97  *
98  * You have to provide the local actions to check against with
99  * setCheckActionCollections().
100  *
101  * When capturing a key sequence for a global shortcut you should
102  * check against StandardShortcuts, GlobalShortcuts and your local
103  * shortcuts.
104  *
105  * There are two ways to react to a user agreeing to steal a shortcut:
106  *
107  * 1. Listen to the stealShortcut() signal and steal the shortcuts
108  * manually. It's your responsibility to save that change later when
109  * you think it is appropriate.
110  *
111  * 2. Call applyStealShortcut() and KKeySequenceWidget will steal the
112  * shortcut. This will save the actionCollections the shortcut is part
113  * of so make sure it doesn't inadvertly save some unwanted changes
114  * too. Read its documentation for some limitation when handling
115  * global shortcuts.
116  *
117  * If you want to do the conflict checking yourself here are some code
118  * snippets for global ...
119  *
120  * \code
121  * QStringList conflicting = KGlobalAccel::findActionNameSystemwide(keySequence);
122  * if (!conflicting.isEmpty()) {
123  * // Inform and ask the user about the conflict and reassigning
124  * // the keys sequence
125  * if (!KGlobalAccel::promptStealShortcutSystemwide(q, conflicting, keySequence)) {
126  * return true;
127  * }
128  * KGlobalAccel::stealShortcutSystemwide(keySequence);
129  * }
130  * \endcode
131  *
132  * ... and standard shortcuts
133  *
134  * \code
135  * KStandardShortcut::StandardShortcut ssc = KStandardShortcut::find(keySequence);
136  * if (ssc != KStandardShortcut::AccelNone) {
137  * // We have a conflict
138  * }
139  * \endcode
140  *
141  *
142  * @since 4.2
143  */
144  void setCheckForConflictsAgainst(ShortcutTypes types);
145 
146  /**
147  * The shortcut types we check for conflicts.
148  *
149  * @see setCheckForConflictsAgainst()
150  * @since 4.2
151  */
152  ShortcutTypes checkForConflictsAgainst() const;
153 
154  /**
155  * Allow multikey shortcuts?
156  */
157  void setMultiKeyShortcutsAllowed(bool);
158  bool multiKeyShortcutsAllowed() const;
159 
160  /**
161  * This only applies to user input, not to setKeySequence().
162  * Set whether to accept "plain" keys without modifiers (like Ctrl, Alt, Meta).
163  * Plain keys by our definition include letter and symbol keys and
164  * text editing keys (Return, Space, Tab, Backspace, Delete).
165  * "Special" keys like F1, Cursor keys, Insert, PageDown will always work.
166  */
167  void setModifierlessAllowed(bool allow);
168 
169  /**
170  * @see setModifierlessAllowed()
171  */
172  bool isModifierlessAllowed();
173 
174  /**
175  * Set whether a small button to set an empty key sequence should be displayed next to the
176  * main input widget. The default is to show the clear button.
177  */
178  void setClearButtonShown(bool show);
179 
180  //@}
181 
182  /**
183  * Checks whether the key sequence @p seq is available to grab.
184  *
185  * The sequence is checked under the same rules as if it has been typed by
186  * the user. This method is useful if you get key sequences from another
187  * input source and want to check if it is save to set them.
188  *
189  * @since 4.2
190  */
191  bool isKeySequenceAvailable(const QKeySequence &seq) const;
192 
193  /**
194  * Return the currently selected key sequence.
195  */
196  QKeySequence keySequence() const;
197 
198  /**
199  * Set a list of action collections to check against for conflictuous shortcut.
200  *
201  * @see setCheckForConflictsAgainst()
202  *
203  * If a QAction with a conflicting shortcut is found inside this list and
204  * its shortcut can be configured (KActionCollection::isShortcutConfigurable()
205  * returns true) the user will be prompted whether to steal the shortcut
206  * from this action.
207  *
208  * @since 4.1
209  */
210  void setCheckActionCollections(const QList<KActionCollection *> &actionCollections);
211 
212 #if KXMLGUI_ENABLE_DEPRECATED_SINCE(4, 1)
213  /**
214  * @deprecated since 4.1
215  * use setCheckActionCollections so that KKeySequenceWidget knows
216  * in which action collection to call the writeSettings method after stealing
217  * a shortcut from an action.
218  */
219  KXMLGUI_DEPRECATED_VERSION(4, 1, "Use KKeySequenceWidget::setCheckActionCollections(const QList<KActionCollection *> &)")
220  void setCheckActionList(const QList<QAction *> &checkList);
221 #endif
222 
223  /**
224  * If the component using this widget supports shortcuts contexts, it has
225  * to set its component name so we can check conflicts correctly.
226  */
227  void setComponentName(const QString &componentName);
228 
229 Q_SIGNALS:
230 
231  /**
232  * This signal is emitted when the current key sequence has changed, be it by user
233  * input or programmatically.
234  */
235  void keySequenceChanged(const QKeySequence &seq);
236 
237  /**
238  * This signal is emitted after the user agreed to steal a shortcut from
239  * an action. This is only done for local shortcuts. So you can be sure \a
240  * action is one of the actions you provided with setCheckActionList() or
241  * setCheckActionCollections().
242  *
243  * If you listen to that signal and don't call applyStealShortcut() you
244  * are supposed to steal the shortcut and save this change.
245  */
246  void stealShortcut(const QKeySequence &seq, QAction *action);
247 
248 public Q_SLOTS:
249 
250  /**
251  * Capture a shortcut from the keyboard. This call will only return once a key sequence
252  * has been captured or input was aborted.
253  * If a key sequence was input, keySequenceChanged() will be emitted.
254  *
255  * @see setModifierlessAllowed()
256  */
257  void captureKeySequence();
258 
259  /**
260  * Set the key sequence.
261  *
262  * If @p val == Validate, and the call is actually changing the key sequence,
263  * conflictuous shortcut will be checked.
264  */
265  void setKeySequence(const QKeySequence &seq, Validation val = NoValidate);
266 
267  /**
268  * Clear the key sequence.
269  */
270  void clearKeySequence();
271 
272  /**
273  * Actually remove the shortcut that the user wanted to steal, from the
274  * action that was using it. This only applies to actions provided to us
275  * by setCheckActionCollections() and setCheckActionList().
276  *
277  * Global and Standard Shortcuts have to be stolen immediately when the
278  * user gives his consent (technical reasons). That means those changes
279  * will be active even if you never call applyStealShortcut().
280  *
281  * To be called before you apply your changes. No local shortcuts are
282  * stolen until this function is called.
283  */
284  void applyStealShortcut();
285 
286 private:
287  friend class KKeySequenceWidgetPrivate;
288  KKeySequenceWidgetPrivate *const d;
289 
291 };
292 
293 Q_DECLARE_OPERATORS_FOR_FLAGS(KKeySequenceWidget::ShortcutTypes)
294 
295 #endif // KKEYSEQUENCEWIDGET_H
Q_PROPERTY(...)
Q_SLOTSQ_SLOTS
A widget to input a QKeySequence.
A container for a set of QAction objects.
Q_SIGNALSQ_SIGNALS
Q_FLAG(...)
Q_DISABLE_COPY(Class)
Validation
An enum about validation when setting a key sequence.
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Tue Nov 28 2023 04:05:23 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.