1/**
2 * Copyright (c) 2006-2023 LOVE Development Team
3 *
4 * This software is provided 'as-is', without any express or implied
5 * warranty. In no event will the authors be held liable for any damages
6 * arising from the use of this software.
7 *
8 * Permission is granted to anyone to use this software for any purpose,
9 * including commercial applications, and to alter it and redistribute it
10 * freely, subject to the following restrictions:
11 *
12 * 1. The origin of this software must not be misrepresented; you must not
13 * claim that you wrote the original software. If you use this software
14 * in a product, an acknowledgment in the product documentation would be
15 * appreciated but is not required.
16 * 2. Altered source versions must be plainly marked as such, and must not be
17 * misrepresented as being the original software.
18 * 3. This notice may not be removed or altered from any source distribution.
19 **/
20
21#ifndef LOVE_KEYBOARD_KEYBOARD_H
22#define LOVE_KEYBOARD_KEYBOARD_H
23
24// LOVE
25#include "common/Module.h"
26#include "common/StringMap.h"
27
28// C++
29#include <vector>
30
31namespace love
32{
33namespace keyboard
34{
35
36class Keyboard : public Module
37{
38public:
39
40 /**
41 * Keyboard keys. They are dependent on the current layout of the keyboard.
42 **/
43 enum Key
44 {
45 KEY_UNKNOWN,
46
47 KEY_RETURN,
48 KEY_ESCAPE,
49 KEY_BACKSPACE,
50 KEY_TAB,
51 KEY_SPACE,
52 KEY_EXCLAIM,
53 KEY_QUOTEDBL,
54 KEY_HASH,
55 KEY_PERCENT,
56 KEY_DOLLAR,
57 KEY_AMPERSAND,
58 KEY_QUOTE,
59 KEY_LEFTPAREN,
60 KEY_RIGHTPAREN,
61 KEY_ASTERISK,
62 KEY_PLUS,
63 KEY_COMMA,
64 KEY_MINUS,
65 KEY_PERIOD,
66 KEY_SLASH,
67 KEY_0,
68 KEY_1,
69 KEY_2,
70 KEY_3,
71 KEY_4,
72 KEY_5,
73 KEY_6,
74 KEY_7,
75 KEY_8,
76 KEY_9,
77 KEY_COLON,
78 KEY_SEMICOLON,
79 KEY_LESS,
80 KEY_EQUALS,
81 KEY_GREATER,
82 KEY_QUESTION,
83 KEY_AT,
84
85 KEY_LEFTBRACKET,
86 KEY_BACKSLASH,
87 KEY_RIGHTBRACKET,
88 KEY_CARET,
89 KEY_UNDERSCORE,
90 KEY_BACKQUOTE,
91 KEY_A,
92 KEY_B,
93 KEY_C,
94 KEY_D,
95 KEY_E,
96 KEY_F,
97 KEY_G,
98 KEY_H,
99 KEY_I,
100 KEY_J,
101 KEY_K,
102 KEY_L,
103 KEY_M,
104 KEY_N,
105 KEY_O,
106 KEY_P,
107 KEY_Q,
108 KEY_R,
109 KEY_S,
110 KEY_T,
111 KEY_U,
112 KEY_V,
113 KEY_W,
114 KEY_X,
115 KEY_Y,
116 KEY_Z,
117
118 KEY_CAPSLOCK,
119
120 KEY_F1,
121 KEY_F2,
122 KEY_F3,
123 KEY_F4,
124 KEY_F5,
125 KEY_F6,
126 KEY_F7,
127 KEY_F8,
128 KEY_F9,
129 KEY_F10,
130 KEY_F11,
131 KEY_F12,
132
133 KEY_PRINTSCREEN,
134 KEY_SCROLLLOCK,
135 KEY_PAUSE,
136 KEY_INSERT,
137 KEY_HOME,
138 KEY_PAGEUP,
139 KEY_DELETE,
140 KEY_END,
141 KEY_PAGEDOWN,
142 KEY_RIGHT,
143 KEY_LEFT,
144 KEY_DOWN,
145 KEY_UP,
146
147 KEY_NUMLOCKCLEAR,
148 KEY_KP_DIVIDE,
149 KEY_KP_MULTIPLY,
150 KEY_KP_MINUS,
151 KEY_KP_PLUS,
152 KEY_KP_ENTER,
153 KEY_KP_1,
154 KEY_KP_2,
155 KEY_KP_3,
156 KEY_KP_4,
157 KEY_KP_5,
158 KEY_KP_6,
159 KEY_KP_7,
160 KEY_KP_8,
161 KEY_KP_9,
162 KEY_KP_0,
163 KEY_KP_PERIOD,
164 KEY_KP_COMMA,
165 KEY_KP_EQUALS,
166
167 KEY_APPLICATION,
168 KEY_POWER,
169 KEY_F13,
170 KEY_F14,
171 KEY_F15,
172 KEY_F16,
173 KEY_F17,
174 KEY_F18,
175 KEY_F19,
176 KEY_F20,
177 KEY_F21,
178 KEY_F22,
179 KEY_F23,
180 KEY_F24,
181 KEY_EXECUTE,
182 KEY_HELP,
183 KEY_MENU,
184 KEY_SELECT,
185 KEY_STOP,
186 KEY_AGAIN,
187 KEY_UNDO,
188 KEY_CUT,
189 KEY_COPY,
190 KEY_PASTE,
191 KEY_FIND,
192 KEY_MUTE,
193 KEY_VOLUMEUP,
194 KEY_VOLUMEDOWN,
195
196 KEY_ALTERASE,
197 KEY_SYSREQ,
198 KEY_CANCEL,
199 KEY_CLEAR,
200 KEY_PRIOR,
201 KEY_RETURN2,
202 KEY_SEPARATOR,
203 KEY_OUT,
204 KEY_OPER,
205 KEY_CLEARAGAIN,
206
207 KEY_THOUSANDSSEPARATOR,
208 KEY_DECIMALSEPARATOR,
209 KEY_CURRENCYUNIT,
210 KEY_CURRENCYSUBUNIT,
211
212 KEY_LCTRL,
213 KEY_LSHIFT,
214 KEY_LALT,
215 KEY_LGUI,
216 KEY_RCTRL,
217 KEY_RSHIFT,
218 KEY_RALT,
219 KEY_RGUI,
220
221 KEY_MODE,
222
223 KEY_AUDIONEXT,
224 KEY_AUDIOPREV,
225 KEY_AUDIOSTOP,
226 KEY_AUDIOPLAY,
227 KEY_AUDIOMUTE,
228 KEY_MEDIASELECT,
229 KEY_WWW,
230 KEY_MAIL,
231 KEY_CALCULATOR,
232 KEY_COMPUTER,
233 KEY_APP_SEARCH,
234 KEY_APP_HOME,
235 KEY_APP_BACK,
236 KEY_APP_FORWARD,
237 KEY_APP_STOP,
238 KEY_APP_REFRESH,
239 KEY_APP_BOOKMARKS,
240
241 KEY_BRIGHTNESSDOWN,
242 KEY_BRIGHTNESSUP,
243 KEY_DISPLAYSWITCH,
244 KEY_KBDILLUMTOGGLE,
245 KEY_KBDILLUMDOWN,
246 KEY_KBDILLUMUP,
247 KEY_EJECT,
248 KEY_SLEEP,
249
250 KEY_MAX_ENUM
251 };
252
253 /**
254 * Scancodes represent physical keys independent of the current layout.
255 * Their names may not match the names of the keys printed on the keyboard.
256 * Some of them are very esoteric...
257 **/
258 enum Scancode
259 {
260 SCANCODE_UNKNOWN,
261
262 SCANCODE_A,
263 SCANCODE_B,
264 SCANCODE_C,
265 SCANCODE_D,
266 SCANCODE_E,
267 SCANCODE_F,
268 SCANCODE_G,
269 SCANCODE_H,
270 SCANCODE_I,
271 SCANCODE_J,
272 SCANCODE_K,
273 SCANCODE_L,
274 SCANCODE_M,
275 SCANCODE_N,
276 SCANCODE_O,
277 SCANCODE_P,
278 SCANCODE_Q,
279 SCANCODE_R,
280 SCANCODE_S,
281 SCANCODE_T,
282 SCANCODE_U,
283 SCANCODE_V,
284 SCANCODE_W,
285 SCANCODE_X,
286 SCANCODE_Y,
287 SCANCODE_Z,
288
289 SCANCODE_1,
290 SCANCODE_2,
291 SCANCODE_3,
292 SCANCODE_4,
293 SCANCODE_5,
294 SCANCODE_6,
295 SCANCODE_7,
296 SCANCODE_8,
297 SCANCODE_9,
298 SCANCODE_0,
299
300 SCANCODE_RETURN,
301 SCANCODE_ESCAPE,
302 SCANCODE_BACKSPACE,
303 SCANCODE_TAB,
304 SCANCODE_SPACE,
305
306 SCANCODE_MINUS,
307 SCANCODE_EQUALS,
308 SCANCODE_LEFTBRACKET,
309 SCANCODE_RIGHTBRACKET,
310 SCANCODE_BACKSLASH,
311 SCANCODE_NONUSHASH,
312 SCANCODE_SEMICOLON,
313 SCANCODE_APOSTROPHE,
314 SCANCODE_GRAVE,
315 SCANCODE_COMMA,
316 SCANCODE_PERIOD,
317 SCANCODE_SLASH,
318
319 SCANCODE_CAPSLOCK,
320
321 SCANCODE_F1,
322 SCANCODE_F2,
323 SCANCODE_F3,
324 SCANCODE_F4,
325 SCANCODE_F5,
326 SCANCODE_F6,
327 SCANCODE_F7,
328 SCANCODE_F8,
329 SCANCODE_F9,
330 SCANCODE_F10,
331 SCANCODE_F11,
332 SCANCODE_F12,
333
334 SCANCODE_PRINTSCREEN,
335 SCANCODE_SCROLLLOCK,
336 SCANCODE_PAUSE,
337 SCANCODE_INSERT,
338 SCANCODE_HOME,
339 SCANCODE_PAGEUP,
340 SCANCODE_DELETE,
341 SCANCODE_END,
342 SCANCODE_PAGEDOWN,
343 SCANCODE_RIGHT,
344 SCANCODE_LEFT,
345 SCANCODE_DOWN,
346 SCANCODE_UP,
347
348 SCANCODE_NUMLOCKCLEAR,
349 SCANCODE_KP_DIVIDE,
350 SCANCODE_KP_MULTIPLY,
351 SCANCODE_KP_MINUS,
352 SCANCODE_KP_PLUS,
353 SCANCODE_KP_ENTER,
354 SCANCODE_KP_1,
355 SCANCODE_KP_2,
356 SCANCODE_KP_3,
357 SCANCODE_KP_4,
358 SCANCODE_KP_5,
359 SCANCODE_KP_6,
360 SCANCODE_KP_7,
361 SCANCODE_KP_8,
362 SCANCODE_KP_9,
363 SCANCODE_KP_0,
364 SCANCODE_KP_PERIOD,
365
366 SCANCODE_NONUSBACKSLASH,
367 SCANCODE_APPLICATION,
368 SCANCODE_POWER,
369 SCANCODE_KP_EQUALS,
370 SCANCODE_F13,
371 SCANCODE_F14,
372 SCANCODE_F15,
373 SCANCODE_F16,
374 SCANCODE_F17,
375 SCANCODE_F18,
376 SCANCODE_F19,
377 SCANCODE_F20,
378 SCANCODE_F21,
379 SCANCODE_F22,
380 SCANCODE_F23,
381 SCANCODE_F24,
382 SCANCODE_EXECUTE,
383 SCANCODE_HELP,
384 SCANCODE_MENU,
385 SCANCODE_SELECT,
386 SCANCODE_STOP,
387 SCANCODE_AGAIN,
388 SCANCODE_UNDO,
389 SCANCODE_CUT,
390 SCANCODE_COPY,
391 SCANCODE_PASTE,
392 SCANCODE_FIND,
393 SCANCODE_MUTE,
394 SCANCODE_VOLUMEUP,
395 SCANCODE_VOLUMEDOWN,
396 SCANCODE_KP_COMMA,
397 SCANCODE_KP_EQUALSAS400,
398
399 SCANCODE_INTERNATIONAL1,
400 SCANCODE_INTERNATIONAL2,
401 SCANCODE_INTERNATIONAL3,
402 SCANCODE_INTERNATIONAL4,
403 SCANCODE_INTERNATIONAL5,
404 SCANCODE_INTERNATIONAL6,
405 SCANCODE_INTERNATIONAL7,
406 SCANCODE_INTERNATIONAL8,
407 SCANCODE_INTERNATIONAL9,
408 SCANCODE_LANG1,
409 SCANCODE_LANG2,
410 SCANCODE_LANG3,
411 SCANCODE_LANG4,
412 SCANCODE_LANG5,
413 SCANCODE_LANG6,
414 SCANCODE_LANG7,
415 SCANCODE_LANG8,
416 SCANCODE_LANG9,
417
418 SCANCODE_ALTERASE,
419 SCANCODE_SYSREQ,
420 SCANCODE_CANCEL,
421 SCANCODE_CLEAR,
422 SCANCODE_PRIOR,
423 SCANCODE_RETURN2,
424 SCANCODE_SEPARATOR,
425 SCANCODE_OUT,
426 SCANCODE_OPER,
427 SCANCODE_CLEARAGAIN,
428 SCANCODE_CRSEL,
429 SCANCODE_EXSEL,
430
431 SCANCODE_KP_00,
432 SCANCODE_KP_000,
433 SCANCODE_THOUSANDSSEPARATOR,
434 SCANCODE_DECIMALSEPARATOR,
435 SCANCODE_CURRENCYUNIT,
436 SCANCODE_CURRENCYSUBUNIT,
437 SCANCODE_KP_LEFTPAREN,
438 SCANCODE_KP_RIGHTPAREN,
439 SCANCODE_KP_LEFTBRACE,
440 SCANCODE_KP_RIGHTBRACE,
441 SCANCODE_KP_TAB,
442 SCANCODE_KP_BACKSPACE,
443 SCANCODE_KP_A,
444 SCANCODE_KP_B,
445 SCANCODE_KP_C,
446 SCANCODE_KP_D,
447 SCANCODE_KP_E,
448 SCANCODE_KP_F,
449 SCANCODE_KP_XOR,
450 SCANCODE_KP_POWER,
451 SCANCODE_KP_PERCENT,
452 SCANCODE_KP_LESS,
453 SCANCODE_KP_GREATER,
454 SCANCODE_KP_AMPERSAND,
455 SCANCODE_KP_DBLAMPERSAND,
456 SCANCODE_KP_VERTICALBAR,
457 SCANCODE_KP_DBLVERTICALBAR,
458 SCANCODE_KP_COLON,
459 SCANCODE_KP_HASH,
460 SCANCODE_KP_SPACE,
461 SCANCODE_KP_AT,
462 SCANCODE_KP_EXCLAM,
463 SCANCODE_KP_MEMSTORE,
464 SCANCODE_KP_MEMRECALL,
465 SCANCODE_KP_MEMCLEAR,
466 SCANCODE_KP_MEMADD,
467 SCANCODE_KP_MEMSUBTRACT,
468 SCANCODE_KP_MEMMULTIPLY,
469 SCANCODE_KP_MEMDIVIDE,
470 SCANCODE_KP_PLUSMINUS,
471 SCANCODE_KP_CLEAR,
472 SCANCODE_KP_CLEARENTRY,
473 SCANCODE_KP_BINARY,
474 SCANCODE_KP_OCTAL,
475 SCANCODE_KP_DECIMAL,
476 SCANCODE_KP_HEXADECIMAL,
477
478 SCANCODE_LCTRL,
479 SCANCODE_LSHIFT,
480 SCANCODE_LALT,
481 SCANCODE_LGUI,
482 SCANCODE_RCTRL,
483 SCANCODE_RSHIFT,
484 SCANCODE_RALT,
485 SCANCODE_RGUI,
486
487 SCANCODE_MODE,
488
489 SCANCODE_AUDIONEXT,
490 SCANCODE_AUDIOPREV,
491 SCANCODE_AUDIOSTOP,
492 SCANCODE_AUDIOPLAY,
493 SCANCODE_AUDIOMUTE,
494 SCANCODE_MEDIASELECT,
495 SCANCODE_WWW,
496 SCANCODE_MAIL,
497 SCANCODE_CALCULATOR,
498 SCANCODE_COMPUTER,
499 SCANCODE_AC_SEARCH,
500 SCANCODE_AC_HOME,
501 SCANCODE_AC_BACK,
502 SCANCODE_AC_FORWARD,
503 SCANCODE_AC_STOP,
504 SCANCODE_AC_REFRESH,
505 SCANCODE_AC_BOOKMARKS,
506
507 SCANCODE_BRIGHTNESSDOWN,
508 SCANCODE_BRIGHTNESSUP,
509 SCANCODE_DISPLAYSWITCH,
510 SCANCODE_KBDILLUMTOGGLE,
511 SCANCODE_KBDILLUMDOWN,
512 SCANCODE_KBDILLUMUP,
513 SCANCODE_EJECT,
514 SCANCODE_SLEEP,
515
516 SCANCODE_APP1,
517 SCANCODE_APP2,
518
519 SCANCODE_MAX_ENUM
520 };
521
522 virtual ~Keyboard() {}
523
524 // Implements Module.
525 virtual ModuleType getModuleType() const { return M_KEYBOARD; }
526
527 /**
528 * Sets whether repeat keypress events should be sent if a key is held down.
529 * Does not affect text input events.
530 * @param enable Whether to send repeat key press events.
531 **/
532 virtual void setKeyRepeat(bool enable) = 0;
533
534 /**
535 * Gets whether repeat keypress events will be sent if a key is held down.
536 **/
537 virtual bool hasKeyRepeat() const = 0;
538
539 /**
540 * Checks whether certain keys are pressed or not.
541 * @param keylist A list of key identifiers.
542 * @return Whether any of the specified keys are pressed.
543 **/
544 virtual bool isDown(const std::vector<Key> &keylist) const = 0;
545
546 /**
547 * Checks whether certain scancodes are pressed or not.
548 * @param scancodelist A list of scancodes.
549 * @return Whether any of the specified scancodes are pressed.
550 **/
551 virtual bool isScancodeDown(const std::vector<Scancode> &scancodelist) const = 0;
552
553 /**
554 * Gets the key corresponding to the specified scancode according to the
555 * current keyboard layout.
556 **/
557 virtual Key getKeyFromScancode(Scancode scancode) const = 0;
558
559 /**
560 * Gets the scancode corresponding to the specified key according to the
561 * current keyboard layout.
562 **/
563 virtual Scancode getScancodeFromKey(Key key) const = 0;
564
565 /**
566 * Sets whether text input events should be received.
567 * @param enable Whether to receive text input events.
568 **/
569 virtual void setTextInput(bool enable) = 0;
570
571 /**
572 * Sets whether text input events should be received, and specifies where
573 * on the screen the text will appear. This is used as a hint so on-screen
574 * keyboards don't cover the text area.
575 **/
576 virtual void setTextInput(bool enable, double x, double y, double w, double h) = 0;
577
578 /**
579 * Gets whether text input events are enabled.
580 **/
581 virtual bool hasTextInput() const = 0;
582
583 /**
584 * Gets whether the system will display an on-screen keyboard when text input
585 * events are enabled.
586 **/
587 virtual bool hasScreenKeyboard() const = 0;
588
589 static bool getConstant(const char *in, Key &out);
590 static bool getConstant(Key in, const char *&out);
591
592 static bool getConstant(const char *in, Scancode &out);
593 static bool getConstant(Scancode in, const char *&out);
594
595private:
596
597 static StringMap<Key, KEY_MAX_ENUM>::Entry keyEntries[];
598 static StringMap<Key, KEY_MAX_ENUM> keys;
599
600 static StringMap<Scancode, SCANCODE_MAX_ENUM>::Entry scancodeEntries[];
601 static StringMap<Scancode, SCANCODE_MAX_ENUM> scancodes;
602
603}; // Keyboard
604
605} // keyboard
606} // love
607
608#endif // LOVE_KEYBOARD_KEYBOARD_H
609