1 /*
2 This source file is part of Konsole, a terminal emulator.
3
4 SPDX-FileCopyrightText: 2007-2008 Robert Knight <robertknight@gmail.com>
5
6 SPDX-License-Identifier: GPL-2.0-or-later
7 */
8
9 #ifndef KEYBOARDTRANSLATOR_H
10 #define KEYBOARDTRANSLATOR_H
11
12 // Qt
13 #include <QList>
14 #include <QMetaType>
15 #include <QMultiHash>
16 #include <QString>
17
18 // Konsole
19 #include "../konsoleprivate_export.h"
20
21 class QIODevice;
22 class QTextStream;
23
24 namespace Konsole
25 {
26 /**
27 * A converter which maps between key sequences pressed by the user and the
28 * character strings which should be sent to the terminal and commands
29 * which should be invoked when those character sequences are pressed.
30 *
31 * Konsole supports multiple keyboard translators, allowing the user to
32 * specify the character sequences which are sent to the terminal
33 * when particular key sequences are pressed.
34 *
35 * A key sequence is defined as a key code, associated keyboard modifiers
36 * (Shift,Ctrl,Alt,Meta etc.) and state flags which indicate the state
37 * which the terminal must be in for the key sequence to apply.
38 */
39 class KONSOLEPRIVATE_EXPORT KeyboardTranslator
40 {
41 public:
42 /**
43 * The meaning of a particular key sequence may depend upon the state which
44 * the terminal emulation is in. Therefore findEntry() may return a different
45 * Entry depending upon the state flags supplied.
46 *
47 * This enum describes the states which may be associated with a particular
48 * entry in the keyboard translation entry.
49 */
50 enum State {
51 /** Indicates that no special state is active */
52 NoState = 0,
53 /**
54 * TODO More documentation
55 */
56 NewLineState = 1,
57 /**
58 * Indicates that the terminal is in 'ANSI' mode.
59 * TODO: More documentation
60 */
61 AnsiState = 2,
62 /**
63 * TODO More documentation
64 */
65 CursorKeysState = 4,
66 /**
67 * Indicates that the alternate screen ( typically used by interactive programs
68 * such as screen or vim ) is active
69 */
70 AlternateScreenState = 8,
71 /** Indicates that any of the modifier keys is active. */
72 AnyModifierState = 16,
73 /** Indicates that the numpad is in application mode. */
74 ApplicationKeypadState = 32,
75 };
76 Q_DECLARE_FLAGS(States, State)
77
78 /**
79 * This enum describes commands which are associated with particular key sequences.
80 */
81 enum Command {
82 /** Indicates that no command is associated with this command sequence */
83 NoCommand = 0,
84 /** TODO Document me */
85 SendCommand = 1,
86 /** Scroll the terminal display up one page */
87 ScrollPageUpCommand = 2,
88 /** Scroll the terminal display down one page */
89 ScrollPageDownCommand = 4,
90 /** Scroll the terminal display up one line */
91 ScrollLineUpCommand = 8,
92 /** Scroll the terminal display down one line */
93 ScrollLineDownCommand = 16,
94 /** Scroll the terminal display up to the start of history */
95 ScrollUpToTopCommand = 32,
96 /** Scroll the terminal display down to the end of history */
97 ScrollDownToBottomCommand = 64,
98 /** Echos the operating system specific erase character. */
99 EraseCommand = 256,
100 };
Q_DECLARE_FLAGS(Commands,Command)101 Q_DECLARE_FLAGS(Commands, Command)
102
103 /**
104 * Represents an association between a key sequence pressed by the user
105 * and the character sequence and commands associated with it for a particular
106 * KeyboardTranslator.
107 */
108 class Entry
109 {
110 public:
111 /**
112 * Constructs a new entry for a keyboard translator.
113 */
114 Entry();
115
116 /**
117 * Returns true if this entry is null.
118 * This is true for newly constructed entries which have no properties set.
119 */
120 bool isNull() const;
121
122 /** Returns the commands associated with this entry */
123 Command command() const;
124 /** Sets the command associated with this entry. */
125 void setCommand(Command aCommand);
126
127 /**
128 * Returns the character sequence associated with this entry, optionally replacing
129 * wildcard '*' characters with numbers to indicate the keyboard modifiers being pressed.
130 *
131 * TODO: The numbers used to replace '*' characters are taken from the Konsole/KDE 3 code.
132 * Document them.
133 *
134 * @param expandWildCards Specifies whether wild cards (occurrences of the '*' character) in
135 * the entry should be replaced with a number to indicate the modifier keys being pressed.
136 *
137 * @param keyboardModifiers The keyboard modifiers being pressed.
138 */
139 QByteArray text(bool expandWildCards = false, Qt::KeyboardModifiers keyboardModifiers = Qt::NoModifier) const;
140
141 /** Sets the character sequence associated with this entry */
142 void setText(const QByteArray &aText);
143
144 /**
145 * Returns the character sequence associated with this entry,
146 * with any non-printable characters replaced with escape sequences.
147 *
148 * eg. \\E for Escape, \\t for tab, \\n for new line.
149 *
150 * @param expandWildCards See text()
151 * @param keyboardModifiers The keyboard modifiers being pressed.
152 */
153 QByteArray escapedText(bool expandWildCards = false, Qt::KeyboardModifiers keyboardModifiers = Qt::NoModifier) const;
154
155 /** Returns the character code ( from the Qt::Key enum ) associated with this entry */
156 int keyCode() const;
157 /** Sets the character code associated with this entry */
158 void setKeyCode(int aKeyCode);
159
160 /**
161 * Returns a bitwise-OR of the enabled keyboard modifiers associated with this entry.
162 * If a modifier is set in modifierMask() but not in modifiers(), this means that the entry
163 * only matches when that modifier is NOT pressed.
164 *
165 * If a modifier is not set in modifierMask() then the entry matches whether the modifier
166 * is pressed or not.
167 */
168 Qt::KeyboardModifiers modifiers() const;
169
170 /** Returns the keyboard modifiers which are valid in this entry. See modifiers() */
171 Qt::KeyboardModifiers modifierMask() const;
172
173 /** See modifiers() */
174 void setModifiers(Qt::KeyboardModifiers modifiers);
175 /** See modifierMask() and modifiers() */
176 void setModifierMask(Qt::KeyboardModifiers mask);
177
178 /**
179 * Returns a bitwise-OR of the enabled state flags associated with this entry.
180 * If flag is set in stateMask() but not in state(), this means that the entry only
181 * matches when the terminal is NOT in that state.
182 *
183 * If a state is not set in stateMask() then the entry matches whether the terminal
184 * is in that state or not.
185 */
186 States state() const;
187
188 /** Returns the state flags which are valid in this entry. See state() */
189 States stateMask() const;
190
191 /** See state() */
192 void setState(States aState);
193 /** See stateMask() */
194 void setStateMask(States aStateMask);
195
196 /**
197 * Returns this entry's conditions ( ie. its key code, modifier and state criteria )
198 * as a string.
199 */
200 QString conditionToString() const;
201
202 /**
203 * Returns this entry's result ( ie. its command or character sequence )
204 * as a string.
205 *
206 * @param expandWildCards See text()
207 * @param keyboardModifiers The keyboard modifiers being pressed.
208 */
209 QString resultToString(bool expandWildCards = false, Qt::KeyboardModifiers keyboardModifiers = Qt::NoModifier) const;
210
211 /**
212 * Returns true if this entry matches the given key sequence, specified
213 * as a combination of @p testKeyCode , @p testKeyboardModifiers and @p testState.
214 */
215 bool matches(int testKeyCode, Qt::KeyboardModifiers testKeyboardModifiers, States testState) const;
216
217 bool operator==(const Entry &rhs) const;
218
219 private:
220 void insertModifier(QString &item, int modifier) const;
221 void insertState(QString &item, int state) const;
222 QByteArray unescape(const QByteArray &text) const;
223
224 int _keyCode;
225 Qt::KeyboardModifiers _modifiers;
226 Qt::KeyboardModifiers _modifierMask;
227 States _state;
228 States _stateMask;
229
230 Command _command;
231 QByteArray _text;
232 };
233
234 /** Constructs a new keyboard translator with the given @p name */
235 explicit KeyboardTranslator(const QString &name);
236
237 /** Returns the name of this keyboard translator */
238 QString name() const;
239
240 /** Sets the name of this keyboard translator */
241 void setName(const QString &name);
242
243 /** Returns the descriptive name of this keyboard translator */
244 QString description() const;
245
246 /** Sets the descriptive name of this keyboard translator */
247 void setDescription(const QString &description);
248
249 /**
250 * Looks for an entry in this keyboard translator which matches the given
251 * key code, keyboard modifiers and state flags.
252 *
253 * Returns the matching entry if found or a null Entry otherwise ( ie.
254 * entry.isNull() will return true )
255 *
256 * @param keyCode A key code from the Qt::Key enum
257 * @param modifiers A combination of modifiers
258 * @param state Optional flags which specify the current state of the terminal
259 */
260 Entry findEntry(int keyCode, Qt::KeyboardModifiers modifiers, States state = NoState) const;
261
262 /**
263 * Adds an entry to this keyboard translator's table. Entries can be looked up according
264 * to their key sequence using findEntry()
265 */
266 void addEntry(const Entry &entry);
267
268 /**
269 * Replaces an entry in the translator. If the @p existing entry is null,
270 * then this is equivalent to calling addEntry(@p replacement)
271 */
272 void replaceEntry(const Entry &existing, const Entry &replacement);
273
274 /**
275 * Removes an entry from the table.
276 */
277 void removeEntry(const Entry &entry);
278
279 /** Returns a list of all entries in the translator. */
280 QList<Entry> entries() const;
281
282 private:
283 // All entries in this translator, indexed by their keycode
284 QMultiHash<int, Entry> _entries;
285
286 QString _name;
287 QString _description;
288 };
289 Q_DECLARE_OPERATORS_FOR_FLAGS(KeyboardTranslator::States)
Q_DECLARE_OPERATORS_FOR_FLAGS(KeyboardTranslator::Commands)290 Q_DECLARE_OPERATORS_FOR_FLAGS(KeyboardTranslator::Commands)
291
292 inline int KeyboardTranslator::Entry::keyCode() const
293 {
294 return _keyCode;
295 }
296
setKeyCode(int aKeyCode)297 inline void KeyboardTranslator::Entry::setKeyCode(int aKeyCode)
298 {
299 _keyCode = aKeyCode;
300 }
301
setModifiers(Qt::KeyboardModifiers modifiers)302 inline void KeyboardTranslator::Entry::setModifiers(Qt::KeyboardModifiers modifiers)
303 {
304 _modifiers = modifiers;
305 }
306
modifiers()307 inline Qt::KeyboardModifiers KeyboardTranslator::Entry::modifiers() const
308 {
309 return _modifiers;
310 }
311
setModifierMask(Qt::KeyboardModifiers mask)312 inline void KeyboardTranslator::Entry::setModifierMask(Qt::KeyboardModifiers mask)
313 {
314 _modifierMask = mask;
315 }
316
modifierMask()317 inline Qt::KeyboardModifiers KeyboardTranslator::Entry::modifierMask() const
318 {
319 return _modifierMask;
320 }
321
isNull()322 inline bool KeyboardTranslator::Entry::isNull() const
323 {
324 return *this == Entry();
325 }
326
setCommand(Command aCommand)327 inline void KeyboardTranslator::Entry::setCommand(Command aCommand)
328 {
329 _command = aCommand;
330 }
331
command()332 inline KeyboardTranslator::Command KeyboardTranslator::Entry::command() const
333 {
334 return _command;
335 }
336
setText(const QByteArray & aText)337 inline void KeyboardTranslator::Entry::setText(const QByteArray &aText)
338 {
339 _text = unescape(aText);
340 }
341
oneOrZero(int value)342 inline int oneOrZero(int value)
343 {
344 return value ? 1 : 0;
345 }
346
text(bool expandWildCards,Qt::KeyboardModifiers keyboardModifiers)347 inline QByteArray KeyboardTranslator::Entry::text(bool expandWildCards, Qt::KeyboardModifiers keyboardModifiers) const
348 {
349 QByteArray expandedText = _text;
350
351 if (expandWildCards) {
352 int modifierValue = 1;
353 modifierValue += oneOrZero(keyboardModifiers & Qt::ShiftModifier);
354 modifierValue += oneOrZero(keyboardModifiers & Qt::AltModifier) << 1;
355 modifierValue += oneOrZero(keyboardModifiers & Qt::ControlModifier) << 2;
356
357 for (int i = 0; i < _text.length(); i++) {
358 if (expandedText[i] == '*') {
359 expandedText[i] = '0' + modifierValue;
360 }
361 }
362 }
363
364 return expandedText;
365 }
366
setState(States aState)367 inline void KeyboardTranslator::Entry::setState(States aState)
368 {
369 _state = aState;
370 }
371
state()372 inline KeyboardTranslator::States KeyboardTranslator::Entry::state() const
373 {
374 return _state;
375 }
376
setStateMask(States aStateMask)377 inline void KeyboardTranslator::Entry::setStateMask(States aStateMask)
378 {
379 _stateMask = aStateMask;
380 }
381
stateMask()382 inline KeyboardTranslator::States KeyboardTranslator::Entry::stateMask() const
383 {
384 return _stateMask;
385 }
386 }
387
388 Q_DECLARE_METATYPE(Konsole::KeyboardTranslator::Entry)
389 Q_DECLARE_METATYPE(const Konsole::KeyboardTranslator *)
390
391 #endif // KEYBOARDTRANSLATOR_H
392