1 | /* This file is part of the KDE libraries |
2 | Copyright (C) 2001,2002 Ellis Whitehead <ellis@kde.org> |
3 | Copyright (C) 2006 Hamish Rodda <rodda@kde.org> |
4 | Copyright (C) 2006 Andreas Hartmetz <ahartmetz@gmail.com> |
5 | |
6 | This library is free software; you can redistribute it and/or |
7 | modify it under the terms of the GNU Library General Public |
8 | License as published by the Free Software Foundation; either |
9 | version 2 of the License, or (at your option) any later version. |
10 | |
11 | This library is distributed in the hope that it will be useful, |
12 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
13 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
14 | Library General Public License for more details. |
15 | |
16 | You should have received a copy of the GNU Library General Public License |
17 | along with this library; see the file COPYING.LIB. If not, write to |
18 | the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
19 | Boston, MA 02110-1301, USA. |
20 | */ |
21 | |
22 | /** |
23 | * @file kshortcut.h |
24 | * Defines platform-independent classes for keyboard shortcut handling. |
25 | */ |
26 | |
27 | #ifndef KSHORTCUT_H |
28 | #define KSHORTCUT_H |
29 | |
30 | #include <kdeui_export.h> |
31 | |
32 | #include <QtCore/QList> |
33 | #include <QtCore/QMetaType> |
34 | #include <QtGui/QKeySequence> |
35 | |
36 | class KShortcutPrivate; |
37 | |
38 | /** |
39 | * @short Represents a keyboard shortcut |
40 | * |
41 | * The KShortcut class is used to represent a keyboard shortcut to an action. |
42 | * A shortcut is normally a single key with modifiers, such as Ctrl+V. |
43 | * A KShortcut object may also contain an alternate key sequence which will also |
44 | * activate the action it's associated with, as long as no other actions have |
45 | * defined that key as their primary key. Ex: Ctrl+V;Shift+Insert. |
46 | * |
47 | * This can be used to add additional accelerators to a KAction. For example, |
48 | * the below code binds the escape key to the close action. |
49 | * |
50 | * \code |
51 | * KAction *closeAction = KStandardAction::close(this, SLOT( close() ), actionCollection()); |
52 | * KShortcut closeShortcut = closeAction->shortcut(); |
53 | * closeShortcut.setAlternate(Qt::Key_Escape); |
54 | * closeAction->setShortcut(closeShortcut); |
55 | * \endcode |
56 | */ |
57 | class KDEUI_EXPORT KShortcut |
58 | { |
59 | public: |
60 | /** |
61 | * An enum about the behavior of operations that treat a KShortcut like a list of QKeySequences. |
62 | */ |
63 | enum EmptyHandling { |
64 | ///if a shortcut is or becomes empty, let it stay as a placeholder |
65 | KeepEmpty = 0, |
66 | ///remove empty QKeySequences, possibly changing the positions of QKeySequences due to the ensuing reshuffling. |
67 | RemoveEmpty |
68 | }; |
69 | |
70 | /** |
71 | * Creates a new empty shortcut. |
72 | * @see isEmpty() |
73 | * @see clear() |
74 | */ |
75 | KShortcut(); |
76 | |
77 | /** |
78 | * Creates a new shortcut that contains the given Qt key |
79 | * sequence as primary shortcut. |
80 | * @param primary Qt key sequence to add |
81 | */ |
82 | explicit KShortcut(const QKeySequence &primary); |
83 | |
84 | /** |
85 | * Creates a new shortcut with the given Qt key sequences |
86 | * as primary and secondary shortcuts. |
87 | * @param primary Qt keycode of primary shortcut |
88 | * @param alternate Qt keycode of alternate shortcut |
89 | * @see Qt::Key |
90 | */ |
91 | KShortcut(const QKeySequence &primary, const QKeySequence &alternate); |
92 | |
93 | /** |
94 | * Creates a new shortcut with the given Qt key codes |
95 | * as primary and secondary shortcuts. |
96 | * You can only assign single-key shortcuts this way. |
97 | * @param keyQtPri Qt keycode of primary shortcut |
98 | * @param keyQtAlt Qt keycode of alternate shortcut |
99 | * @see Qt::Key |
100 | */ |
101 | explicit KShortcut(int keyQtPri, int keyQtAlt = 0); |
102 | |
103 | /** |
104 | * Copy constructor. |
105 | */ |
106 | KShortcut(const KShortcut &other); |
107 | |
108 | /** |
109 | * Creates a new shortcut that contains the key sequences described |
110 | * in @p description. The format of description is the same as |
111 | * used in QKeySequence::fromString(const QString&). |
112 | * Up to two key sequences separated by a semicolon followed by a |
113 | * space "; " may be given. |
114 | * @param description the description of key sequence(s) |
115 | * @see QKeySequence::fromString(const QString&, SequenceFormat) |
116 | */ |
117 | explicit KShortcut(const QString &description); |
118 | |
119 | /** |
120 | * Creates a new shortcut with the given Qt key sequences. |
121 | * The first sequence in the list is considered to be the primary |
122 | * sequence, the second one the alternate. |
123 | * @param seqs List of key sequeces. |
124 | */ |
125 | explicit KShortcut(const QList<QKeySequence> &seqs); |
126 | |
127 | /** |
128 | * Destructor. |
129 | */ |
130 | ~KShortcut(); |
131 | |
132 | /** @name Query methods */ |
133 | /** @{ */ |
134 | |
135 | /** |
136 | * Returns the primary key sequence of this shortcut. |
137 | * @return primary key sequence |
138 | */ |
139 | QKeySequence primary() const; |
140 | |
141 | /** |
142 | * Returns the alternate key sequence of this shortcut. |
143 | * @return alternate key sequence |
144 | */ |
145 | QKeySequence alternate() const; |
146 | |
147 | /** |
148 | * Returns whether this shortcut contains any nonempty key sequences. |
149 | * @return whether this shortcut is empty |
150 | */ |
151 | bool isEmpty() const; |
152 | |
153 | /** |
154 | * Returns whether at least one of the key sequences is equal to @p needle. |
155 | * @return whether this shortcut contains @p needle |
156 | */ |
157 | bool contains(const QKeySequence &needle) const; |
158 | |
159 | /** |
160 | * Returns whether at least one of the key sequences conflicts witho @p needle. |
161 | * @return whether this shortcut conflicts with @p needle |
162 | */ |
163 | bool conflictsWith(const QKeySequence &needle) const; |
164 | |
165 | /** |
166 | * Returns a description of the shortcut as a semicolon-separated |
167 | * list of key sequences, as returned by QKeySequence::toString(). |
168 | * @return the string represenation of this shortcut |
169 | * @see QKeySequence::toString() |
170 | * @see KShortcut(const QString &description) |
171 | */ |
172 | QString toString() const; |
173 | |
174 | /** |
175 | * Returns a description of the shortcut as a semicolon-separated |
176 | * list of key sequences, as returned by QKeySequence::toString(). |
177 | * @return the string represenation of this shortcut |
178 | * @see QKeySequence::toString() |
179 | * @see KShortcut(const QString &description) |
180 | * @since KDE 4.2 |
181 | */ |
182 | QString toString(QKeySequence::SequenceFormat format) const; |
183 | |
184 | bool operator==(const KShortcut &other) const; |
185 | |
186 | bool operator!=(const KShortcut &other) const; |
187 | |
188 | /** |
189 | * Returns shortcut as QList\<QKeySequence\>, and is equivalent to toList(RemoveEmpty). |
190 | * Be aware that empty shortcuts will not be included in the list; |
191 | * due to this, conversion operations like |
192 | * KShortcut b = (QList\<QKeySequence\>)KShortcut a |
193 | * will not always result in b == a. |
194 | * @return the shortcut converted to a QList\<QKeySequence\> |
195 | */ |
196 | operator QList<QKeySequence>() const; |
197 | |
198 | /** |
199 | * The same as operator QList\<QKeySequence\>() |
200 | * If @p handleEmpty equals RemoveEmpty, empty key sequences will be left out of the result. |
201 | * Otherwise, empy key sequences will be included; you can be sure that |
202 | * shortcut.alternate() == shortcut.toList(KeepEmpty).at(1). |
203 | * @return the shortcut converted to a QList\<QKeySequence\> |
204 | */ |
205 | QList<QKeySequence> toList(enum EmptyHandling handleEmpty = RemoveEmpty) const; |
206 | |
207 | /** |
208 | * Returns shortcut as QVariant. |
209 | */ |
210 | operator QVariant() const; |
211 | |
212 | /** @} */ |
213 | /** @name Mutator methods */ |
214 | /** @{ */ |
215 | |
216 | /** |
217 | * Set the primary key sequence of this shortcut to the given key sequence. |
218 | * @param keySeq set primary key sequence to this |
219 | */ |
220 | void setPrimary(const QKeySequence &keySeq); |
221 | |
222 | /** |
223 | * Set the alternate key sequence of this shortcut to the given key sequence. |
224 | * @param keySeq set alternate key sequence to this |
225 | */ |
226 | void setAlternate(const QKeySequence &keySeq); |
227 | |
228 | /** |
229 | * Remove @p keySeq from this shortcut. |
230 | * If @p handleEmpty equals RemoveEmpty, following key sequences will move up to take the place of |
231 | * @p keySeq. Otherwise, key sequences equal to @p keySeq will be set to empty. |
232 | * @param keySeq remove this key sequence from the shortcut |
233 | */ |
234 | void remove(const QKeySequence &keySeq, enum EmptyHandling handleEmpty = RemoveEmpty); |
235 | |
236 | /** |
237 | * Assignment operator. |
238 | */ |
239 | KShortcut &operator=(const KShortcut &other); |
240 | |
241 | private: |
242 | class KShortcutPrivate *const d; |
243 | }; |
244 | |
245 | uint qHash(int); |
246 | inline uint qHash(const KShortcut &key) |
247 | { |
248 | return qHash(key.primary()[0]) + qHash(key.primary()[1]); |
249 | } |
250 | |
251 | inline uint qHash(const QKeySequence &key) |
252 | { |
253 | uint hash = 0; |
254 | for(uint i = 0; i < key.count(); i++) |
255 | hash += qHash(key[i]); |
256 | return hash; |
257 | } |
258 | |
259 | Q_DECLARE_METATYPE(KShortcut) |
260 | |
261 | #endif // KSHORTCUT_H |
262 | |