From 1b6b2cb898f049d65c4760c872417216a4894076 Mon Sep 17 00:00:00 2001 From: Edgar Bonet Date: Wed, 20 Apr 2022 14:48:30 +0200 Subject: [PATCH 1/4] keyboardModifiers: rewrite the introductory text The main purpose of the page Language/Functions/USB/Keyboard/keyboardModifiers.adoc is to list the macros representing keys. Refocus the text accordingly. --- .../USB/Keyboard/keyboardModifiers.adoc | 29 +++++++++++-------- 1 file changed, 17 insertions(+), 12 deletions(-) diff --git a/Language/Functions/USB/Keyboard/keyboardModifiers.adoc b/Language/Functions/USB/Keyboard/keyboardModifiers.adoc index 55dabfbe..8d005363 100644 --- a/Language/Functions/USB/Keyboard/keyboardModifiers.adoc +++ b/Language/Functions/USB/Keyboard/keyboardModifiers.adoc @@ -14,19 +14,26 @@ title: Keyboard Modifiers and Special Keys [float] === Description -The `Keyboard.write()` and `Keyboard.press()` and `Keyboard.release()` commands don’t work with every possible ASCII character, only those that correspond to a key on the keyboard. For example, backspace works, but many of the other non-printable characters produce unpredictable results. For capital letters (and other keys), what’s sent is shift plus the character (i.e. the equivalent of pressing both of those keys on the keyboard). +When given a printable ASCII character as an argument, the functions `Keyboard.write()`, `Keyboard.press()` and `Keyboard.release()` simulate actuations on the corresponding keys. These functions can also handle ASCII characters that require pressing a key in combination with Shift or, on international keyboards, AltGr. For example: +[source,arduino] +---- +Keyboard.write('a'); // press and release the 'A' key +Keyboard.write('A'); // press Shift and 'A', then release both +---- +A typical keyboard, however, has many keys that do not match a printable ASCII character. In order to simulate those keys, the library provides a set of macros that can be passed as arguments to `Keyboard.write()`, `Keyboard.press()` and `Keyboard.release()`. For example, the key combination Shift-F2 can be generated by: +[source,arduino] +---- +Keyboard.press(KEY_LEFT_SHIFT); // press and hold Shift +Keyboard.press(KEY_F2); // press and hold F2 +Keyboard.releaseAll(); // release both +---- +Note that, in order to press multiple keys simultaneously, one has to use link:../keyboardpress[`Keyboard.press()`] rather than link:../keyboardwrite[`Keyboard.write()`], as the latter just “hits” the keys (it presses and immediate releases them). [%hardbreaks] -For more on ASCII values and the characters or functions they represent, see http://www.asciitable.com/[asciitable.com] +The available macros are listed below: [float] === Keyboard modifiers -A modifier key is a special key on a computer keyboard that modifies the normal action of another key when the two are pressed in combination. -[%hardbreaks] -For multiple key presses use link:../keyboardpress[Keyboard.press]() -[%hardbreaks] -The definitions of the modifier keys are listed below: -[%hardbreaks] - +These are eight keys within the alphanumeric cluster of the keyboard that are meant to modify the normal action of another key when the two are pressed in combination. Whereas Shift and AltGr are used to access extra characters, the others are mostly used for keyboard shortcuts. |=== |Key |Hexadecimal value |Decimal value @@ -43,9 +50,7 @@ The definitions of the modifier keys are listed below: [float] === Special keys -These are four keys within the alphanumeric cluster of a keyboard (Tab, Caps Lock, Backspace and Return) as well as all keys from outside that cluster (Escape, function keys, Home, End, arrow keys...). - -The following special keys have been defined: +These are all the keys that do not match a printable ASCII character and are not modifiers, including all keys outside the alphanumeric cluster. |=== |Key |Hexadecimal value |Decimal value From 42081fa836411589b5748d6fdf00396b493a6331 Mon Sep 17 00:00:00 2001 From: Edgar Bonet Date: Sat, 2 Apr 2022 18:23:45 +0200 Subject: [PATCH 2/4] keyboardModifiers: split keys into smaller groups Language/Functions/USB/Keyboard/keyboardModifiers.adoc contains a long list of macros corresponding to keys. Make this list easier to parse by organizing the keys into meaningful groups. --- .../USB/Keyboard/keyboardModifiers.adoc | 38 ++++++++++++++----- 1 file changed, 29 insertions(+), 9 deletions(-) diff --git a/Language/Functions/USB/Keyboard/keyboardModifiers.adoc b/Language/Functions/USB/Keyboard/keyboardModifiers.adoc index 8d005363..42f0b1a9 100644 --- a/Language/Functions/USB/Keyboard/keyboardModifiers.adoc +++ b/Language/Functions/USB/Keyboard/keyboardModifiers.adoc @@ -52,24 +52,44 @@ These are eight keys within the alphanumeric cluster of the keyboard that are me === Special keys These are all the keys that do not match a printable ASCII character and are not modifiers, including all keys outside the alphanumeric cluster. +[float] +==== Within the alphanumeric cluster + |=== |Key |Hexadecimal value |Decimal value -|KEY_UP_ARROW |0xDA |218 -|KEY_DOWN_ARROW |0xD9 |217 -|KEY_LEFT_ARROW |0xD8 |216 -|KEY_RIGHT_ARROW |0xD7 |215 -|KEY_BACKSPACE |0xB2 |178 |KEY_TAB |0xB3 |179 +|KEY_CAPS_LOCK |0xC1 |193 +|KEY_BACKSPACE |0xB2 |178 |KEY_RETURN |0xB0 |176 -|KEY_ESC |0xB1 |177 +|=== + +[float] +==== Navigation cluster + +|=== +|Key |Hexadecimal value |Decimal value + |KEY_INSERT |0xD1 |209 |KEY_DELETE |0xD4 |212 -|KEY_PAGE_UP |0xD3 |211 -|KEY_PAGE_DOWN |0xD6 |214 |KEY_HOME |0xD2 |210 |KEY_END |0xD5 |213 -|KEY_CAPS_LOCK |0xC1 |193 +|KEY_PAGE_UP |0xD3 |211 +|KEY_PAGE_DOWN |0xD6 |214 +|KEY_UP_ARROW |0xDA |218 +|KEY_DOWN_ARROW |0xD9 |217 +|KEY_LEFT_ARROW |0xD8 |216 +|KEY_RIGHT_ARROW |0xD7 |215 +|=== + +[float] +==== Escape and function keys +The library can simulate function keys up to F24, even though few keyboards have the F13… F24 keys. + +|=== +|Key |Hexadecimal value |Decimal value + +|KEY_ESC |0xB1 |177 |KEY_F1 |0xC2 |194 |KEY_F2 |0xC3 |195 |KEY_F3 |0xC4 |196 From a7b4ff990af68a2007842c50f933c8cb3d1eaf43 Mon Sep 17 00:00:00 2001 From: Edgar Bonet Date: Sat, 2 Apr 2022 20:34:54 +0200 Subject: [PATCH 3/4] keyboardModifiers: add notes to ambiguous keys In Language/Functions/USB/Keyboard/keyboardModifiers.adoc, add explanatory notes for keys with ambiguous names: - KEY_{LEFT,RIGHT}_GUI are the OS logo keys, "command" on Mac - KEY_{LEFT,RIGHT}_ALT is "option" on Mac - KEY_RIGHT_ALT can be labeled "AltGr". --- .../USB/Keyboard/keyboardModifiers.adoc | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/Language/Functions/USB/Keyboard/keyboardModifiers.adoc b/Language/Functions/USB/Keyboard/keyboardModifiers.adoc index 42f0b1a9..30e85b93 100644 --- a/Language/Functions/USB/Keyboard/keyboardModifiers.adoc +++ b/Language/Functions/USB/Keyboard/keyboardModifiers.adoc @@ -36,16 +36,16 @@ The available macros are listed below: These are eight keys within the alphanumeric cluster of the keyboard that are meant to modify the normal action of another key when the two are pressed in combination. Whereas Shift and AltGr are used to access extra characters, the others are mostly used for keyboard shortcuts. |=== -|Key |Hexadecimal value |Decimal value - -|KEY_LEFT_CTRL |0x80 |128 -|KEY_LEFT_SHIFT |0x81 |129 -|KEY_LEFT_ALT |0x82 |130 -|KEY_LEFT_GUI |0x83 |131 -|KEY_RIGHT_CTRL |0x84 |132 -|KEY_RIGHT_SHIFT |0x85 |133 -|KEY_RIGHT_ALT |0x86 |134 -|KEY_RIGHT_GUI |0x87 |135 +|Key |Hexadecimal value |Decimal value |Notes + +|KEY_LEFT_CTRL |0x80 |128 | +|KEY_LEFT_SHIFT |0x81 |129 | +|KEY_LEFT_ALT |0x82 |130 |option (⌥) on Mac +|KEY_LEFT_GUI |0x83 |131 |OS logo, command (⌘) on Mac +|KEY_RIGHT_CTRL |0x84 |132 | +|KEY_RIGHT_SHIFT |0x85 |133 | +|KEY_RIGHT_ALT |0x86 |134 |also AltGr, option (⌥) on Mac +|KEY_RIGHT_GUI |0x87 |135 |OS logo, command (⌘) on Mac |=== [float] From eba85e412125418ec3d480ff24edbed292666888 Mon Sep 17 00:00:00 2001 From: Edgar Bonet Date: Sat, 7 May 2022 14:31:32 +0200 Subject: [PATCH 4/4] keyboardModifiers: Implement review suggestions Apply changes suggested by @per1234 on pull-request review: - fix typo - use common conventions for key names and key combinations - reduce unnecessary verbosity. Co-authored-by: per1234 --- .../USB/Keyboard/keyboardModifiers.adoc | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/Language/Functions/USB/Keyboard/keyboardModifiers.adoc b/Language/Functions/USB/Keyboard/keyboardModifiers.adoc index 30e85b93..f6b86b55 100644 --- a/Language/Functions/USB/Keyboard/keyboardModifiers.adoc +++ b/Language/Functions/USB/Keyboard/keyboardModifiers.adoc @@ -20,37 +20,37 @@ When given a printable ASCII character as an argument, the functions `Keyboard.w Keyboard.write('a'); // press and release the 'A' key Keyboard.write('A'); // press Shift and 'A', then release both ---- -A typical keyboard, however, has many keys that do not match a printable ASCII character. In order to simulate those keys, the library provides a set of macros that can be passed as arguments to `Keyboard.write()`, `Keyboard.press()` and `Keyboard.release()`. For example, the key combination Shift-F2 can be generated by: +A typical keyboard, however, has many keys that do not match a printable ASCII character. In order to simulate those keys, the library provides a set of macros that can be passed as arguments to `Keyboard.write()`, `Keyboard.press()` and `Keyboard.release()`. For example, the key combination Shift+F2 can be generated by: [source,arduino] ---- Keyboard.press(KEY_LEFT_SHIFT); // press and hold Shift Keyboard.press(KEY_F2); // press and hold F2 Keyboard.releaseAll(); // release both ---- -Note that, in order to press multiple keys simultaneously, one has to use link:../keyboardpress[`Keyboard.press()`] rather than link:../keyboardwrite[`Keyboard.write()`], as the latter just “hits” the keys (it presses and immediate releases them). +Note that, in order to press multiple keys simultaneously, one has to use link:../keyboardpress[`Keyboard.press()`] rather than link:../keyboardwrite[`Keyboard.write()`], as the latter just “hits” the keys (it presses and immediately releases them). [%hardbreaks] The available macros are listed below: [float] === Keyboard modifiers -These are eight keys within the alphanumeric cluster of the keyboard that are meant to modify the normal action of another key when the two are pressed in combination. Whereas Shift and AltGr are used to access extra characters, the others are mostly used for keyboard shortcuts. +These keys are meant to modify the normal action of another key when the two are pressed in combination. |=== |Key |Hexadecimal value |Decimal value |Notes |KEY_LEFT_CTRL |0x80 |128 | |KEY_LEFT_SHIFT |0x81 |129 | -|KEY_LEFT_ALT |0x82 |130 |option (⌥) on Mac -|KEY_LEFT_GUI |0x83 |131 |OS logo, command (⌘) on Mac +|KEY_LEFT_ALT |0x82 |130 |Option (⌥) on Mac +|KEY_LEFT_GUI |0x83 |131 |OS logo, Command (⌘) on Mac |KEY_RIGHT_CTRL |0x84 |132 | |KEY_RIGHT_SHIFT |0x85 |133 | -|KEY_RIGHT_ALT |0x86 |134 |also AltGr, option (⌥) on Mac -|KEY_RIGHT_GUI |0x87 |135 |OS logo, command (⌘) on Mac +|KEY_RIGHT_ALT |0x86 |134 |also AltGr, Option (⌥) on Mac +|KEY_RIGHT_GUI |0x87 |135 |OS logo, Command (⌘) on Mac |=== [float] === Special keys -These are all the keys that do not match a printable ASCII character and are not modifiers, including all keys outside the alphanumeric cluster. +These are all the keys that do not match a printable ASCII character and are not modifiers. [float] ==== Within the alphanumeric cluster @@ -84,7 +84,7 @@ These are all the keys that do not match a printable ASCII character and are not [float] ==== Escape and function keys -The library can simulate function keys up to F24, even though few keyboards have the F13… F24 keys. +The library can simulate function keys up to F24. |=== |Key |Hexadecimal value |Decimal value