1  # The MIT License (MIT)
  2  #
  3  # Copyright (c) 2017 Scott Shawcroft for Adafruit Industries
  4  #
  5  # Permission is hereby granted, free of charge, to any person obtaining a copy
  6  # of this software and associated documentation files (the "Software"), to deal
  7  # in the Software without restriction, including without limitation the rights
  8  # to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  9  # copies of the Software, and to permit persons to whom the Software is
 10  # furnished to do so, subject to the following conditions:
 11  #
 12  # The above copyright notice and this permission notice shall be included in
 13  # all copies or substantial portions of the Software.
 14  #
 15  # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 16  # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 17  # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 18  # AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 19  # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 20  # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 21  # THE SOFTWARE.
 22  #
 23  
 24  """
 25  `adafruit_hid.keycode.Keycode`
 26  ====================================================
 27  
 28  * Author(s): Scott Shawcroft, Dan Halbert
 29  """
 30  
 31  
 32  class Keycode:
 33      """USB HID Keycode constants.
 34  
 35      This list is modeled after the names for USB keycodes defined in
 36      https://www.usb.org/sites/default/files/documents/hut1_12v2.pdf#page=53.
 37      This list does not include every single code, but does include all the keys on
 38      a regular PC or Mac keyboard.
 39  
 40      Remember that keycodes are the names for key *positions* on a US keyboard, and may
 41      not correspond to the character that you mean to send if you want to emulate non-US keyboard.
 42      For instance, on a French keyboard (AZERTY instead of QWERTY),
 43      the keycode for 'q' is used to indicate an 'a'. Likewise, 'y' represents 'z' on
 44      a German keyboard. This is historical: the idea was that the keycaps could be changed
 45      without changing the keycodes sent, so that different firmware was not needed for
 46      different variations of a keyboard.
 47      """
 48  
 49      # pylint: disable-msg=invalid-name
 50      A = 0x04
 51      """``a`` and ``A``"""
 52      B = 0x05
 53      """``b`` and ``B``"""
 54      C = 0x06
 55      """``c`` and ``C``"""
 56      D = 0x07
 57      """``d`` and ``D``"""
 58      E = 0x08
 59      """``e`` and ``E``"""
 60      F = 0x09
 61      """``f`` and ``F``"""
 62      G = 0x0A
 63      """``g`` and ``G``"""
 64      H = 0x0B
 65      """``h`` and ``H``"""
 66      I = 0x0C
 67      """``i`` and ``I``"""
 68      J = 0x0D
 69      """``j`` and ``J``"""
 70      K = 0x0E
 71      """``k`` and ``K``"""
 72      L = 0x0F
 73      """``l`` and ``L``"""
 74      M = 0x10
 75      """``m`` and ``M``"""
 76      N = 0x11
 77      """``n`` and ``N``"""
 78      O = 0x12
 79      """``o`` and ``O``"""
 80      P = 0x13
 81      """``p`` and ``P``"""
 82      Q = 0x14
 83      """``q`` and ``Q``"""
 84      R = 0x15
 85      """``r`` and ``R``"""
 86      S = 0x16
 87      """``s`` and ``S``"""
 88      T = 0x17
 89      """``t`` and ``T``"""
 90      U = 0x18
 91      """``u`` and ``U``"""
 92      V = 0x19
 93      """``v`` and ``V``"""
 94      W = 0x1A
 95      """``w`` and ``W``"""
 96      X = 0x1B
 97      """``x`` and ``X``"""
 98      Y = 0x1C
 99      """``y`` and ``Y``"""
100      Z = 0x1D
101      """``z`` and ``Z``"""
102  
103      ONE = 0x1E
104      """``1`` and ``!``"""
105      TWO = 0x1F
106      """``2`` and ``@``"""
107      THREE = 0x20
108      """``3`` and ``#``"""
109      FOUR = 0x21
110      """``4`` and ``$``"""
111      FIVE = 0x22
112      """``5`` and ``%``"""
113      SIX = 0x23
114      """``6`` and ``^``"""
115      SEVEN = 0x24
116      """``7`` and ``&``"""
117      EIGHT = 0x25
118      """``8`` and ``*``"""
119      NINE = 0x26
120      """``9`` and ``(``"""
121      ZERO = 0x27
122      """``0`` and ``)``"""
123      ENTER = 0x28
124      """Enter (Return)"""
125      RETURN = ENTER
126      """Alias for ``ENTER``"""
127      ESCAPE = 0x29
128      """Escape"""
129      BACKSPACE = 0x2A
130      """Delete backward (Backspace)"""
131      TAB = 0x2B
132      """Tab and Backtab"""
133      SPACEBAR = 0x2C
134      """Spacebar"""
135      SPACE = SPACEBAR
136      """Alias for SPACEBAR"""
137      MINUS = 0x2D
138      """``-` and ``_``"""
139      EQUALS = 0x2E
140      """``=` and ``+``"""
141      LEFT_BRACKET = 0x2F
142      """``[`` and ``{``"""
143      RIGHT_BRACKET = 0x30
144      """``]`` and ``}``"""
145      BACKSLASH = 0x31
146      r"""``\`` and ``|``"""
147      POUND = 0x32
148      """``#`` and ``~`` (Non-US keyboard)"""
149      SEMICOLON = 0x33
150      """``;`` and ``:``"""
151      QUOTE = 0x34
152      """``'`` and ``"``"""
153      GRAVE_ACCENT = 0x35
154      r""":literal:`\`` and ``~``"""
155      COMMA = 0x36
156      """``,`` and ``<``"""
157      PERIOD = 0x37
158      """``.`` and ``>``"""
159      FORWARD_SLASH = 0x38
160      """``/`` and ``?``"""
161  
162      CAPS_LOCK = 0x39
163      """Caps Lock"""
164  
165      F1 = 0x3A
166      """Function key F1"""
167      F2 = 0x3B
168      """Function key F2"""
169      F3 = 0x3C
170      """Function key F3"""
171      F4 = 0x3D
172      """Function key F4"""
173      F5 = 0x3E
174      """Function key F5"""
175      F6 = 0x3F
176      """Function key F6"""
177      F7 = 0x40
178      """Function key F7"""
179      F8 = 0x41
180      """Function key F8"""
181      F9 = 0x42
182      """Function key F9"""
183      F10 = 0x43
184      """Function key F10"""
185      F11 = 0x44
186      """Function key F11"""
187      F12 = 0x45
188      """Function key F12"""
189  
190      PRINT_SCREEN = 0x46
191      """Print Screen (SysRq)"""
192      SCROLL_LOCK = 0x47
193      """Scroll Lock"""
194      PAUSE = 0x48
195      """Pause (Break)"""
196  
197      INSERT = 0x49
198      """Insert"""
199      HOME = 0x4A
200      """Home (often moves to beginning of line)"""
201      PAGE_UP = 0x4B
202      """Go back one page"""
203      DELETE = 0x4C
204      """Delete forward"""
205      END = 0x4D
206      """End (often moves to end of line)"""
207      PAGE_DOWN = 0x4E
208      """Go forward one page"""
209  
210      RIGHT_ARROW = 0x4F
211      """Move the cursor right"""
212      LEFT_ARROW = 0x50
213      """Move the cursor left"""
214      DOWN_ARROW = 0x51
215      """Move the cursor down"""
216      UP_ARROW = 0x52
217      """Move the cursor up"""
218  
219      KEYPAD_NUMLOCK = 0x53
220      """Num Lock (Clear on Mac)"""
221      KEYPAD_FORWARD_SLASH = 0x54
222      """Keypad ``/``"""
223      KEYPAD_ASTERISK = 0x55
224      """Keypad ``*``"""
225      KEYPAD_MINUS = 0x56
226      """Keyapd ``-``"""
227      KEYPAD_PLUS = 0x57
228      """Keypad ``+``"""
229      KEYPAD_ENTER = 0x58
230      """Keypad Enter"""
231      KEYPAD_ONE = 0x59
232      """Keypad ``1`` and End"""
233      KEYPAD_TWO = 0x5A
234      """Keypad ``2`` and Down Arrow"""
235      KEYPAD_THREE = 0x5B
236      """Keypad ``3`` and PgDn"""
237      KEYPAD_FOUR = 0x5C
238      """Keypad ``4`` and Left Arrow"""
239      KEYPAD_FIVE = 0x5D
240      """Keypad ``5``"""
241      KEYPAD_SIX = 0x5E
242      """Keypad ``6`` and Right Arrow"""
243      KEYPAD_SEVEN = 0x5F
244      """Keypad ``7`` and Home"""
245      KEYPAD_EIGHT = 0x60
246      """Keypad ``8`` and Up Arrow"""
247      KEYPAD_NINE = 0x61
248      """Keypad ``9`` and PgUp"""
249      KEYPAD_ZERO = 0x62
250      """Keypad ``0`` and Ins"""
251      KEYPAD_PERIOD = 0x63
252      """Keypad ``.`` and Del"""
253      KEYPAD_BACKSLASH = 0x64
254      """Keypad ``\\`` and ``|`` (Non-US)"""
255  
256      APPLICATION = 0x65
257      """Application: also known as the Menu key (Windows)"""
258      POWER = 0x66
259      """Power (Mac)"""
260      KEYPAD_EQUALS = 0x67
261      """Keypad ``=`` (Mac)"""
262      F13 = 0x68
263      """Function key F13 (Mac)"""
264      F14 = 0x69
265      """Function key F14 (Mac)"""
266      F15 = 0x6A
267      """Function key F15 (Mac)"""
268      F16 = 0x6B
269      """Function key F16 (Mac)"""
270      F17 = 0x6C
271      """Function key F17 (Mac)"""
272      F18 = 0x6D
273      """Function key F18 (Mac)"""
274      F19 = 0x6E
275      """Function key F19 (Mac)"""
276  
277      LEFT_CONTROL = 0xE0
278      """Control modifier left of the spacebar"""
279      CONTROL = LEFT_CONTROL
280      """Alias for LEFT_CONTROL"""
281      LEFT_SHIFT = 0xE1
282      """Shift modifier left of the spacebar"""
283      SHIFT = LEFT_SHIFT
284      """Alias for LEFT_SHIFT"""
285      LEFT_ALT = 0xE2
286      """Alt modifier left of the spacebar"""
287      ALT = LEFT_ALT
288      """Alias for LEFT_ALT; Alt is also known as Option (Mac)"""
289      OPTION = ALT
290      """Labeled as Option on some Mac keyboards"""
291      LEFT_GUI = 0xE3
292      """GUI modifier left of the spacebar"""
293      GUI = LEFT_GUI
294      """Alias for LEFT_GUI; GUI is also known as the Windows key, Command (Mac), or Meta"""
295      WINDOWS = GUI
296      """Labeled with a Windows logo on Windows keyboards"""
297      COMMAND = GUI
298      """Labeled as Command on Mac keyboards, with a clover glyph"""
299      RIGHT_CONTROL = 0xE4
300      """Control modifier right of the spacebar"""
301      RIGHT_SHIFT = 0xE5
302      """Shift modifier right of the spacebar"""
303      RIGHT_ALT = 0xE6
304      """Alt modifier right of the spacebar"""
305      RIGHT_GUI = 0xE7
306      """GUI modifier right of the spacebar"""
307  
308      # pylint: enable-msg=invalid-name
309      @classmethod
310      def modifier_bit(cls, keycode):
311          """Return the modifer bit to be set in an HID keycode report if this is a
312          modifier key; otherwise return 0."""
313          return (
314              1 << (keycode - 0xE0) if cls.LEFT_CONTROL <= keycode <= cls.RIGHT_GUI else 0
315          )