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
36class 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*/
57class KDEUI_EXPORT KShortcut
58{
59public:
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
241private:
242 class KShortcutPrivate *const d;
243};
244
245uint qHash(int);
246inline uint qHash(const KShortcut &key)
247{
248 return qHash(key.primary()[0]) + qHash(key.primary()[1]);
249}
250
251inline 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
259Q_DECLARE_METATYPE(KShortcut)
260
261#endif // KSHORTCUT_H
262