Skip to content

Rewrite keyboardModifiers.adoc #875

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
May 7, 2022
Merged

Rewrite keyboardModifiers.adoc #875

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
1b6b2cb
keyboardModifiers: rewrite the introductory text
edgar-bonet Apr 20, 2022
42081fa
keyboardModifiers: split keys into smaller groups
edgar-bonet Apr 2, 2022
a7b4ff9
keyboardModifiers: add notes to ambiguous keys
edgar-bonet Apr 2, 2022
eba85e4
keyboardModifiers: Implement review suggestions
edgar-bonet May 7, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
85 changes: 55 additions & 30 deletions Language/Functions/USB/Keyboard/keyboardModifiers.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,57 +14,82 @@ 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 immediately 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 keys are meant to modify the normal action of another key when the two are pressed in combination.

|===
|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]
=== 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...).
These are all the keys that do not match a printable ASCII character and are not modifiers.

The following special keys have been defined:
[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.

|===
|Key |Hexadecimal value |Decimal value

|KEY_ESC |0xB1 |177
|KEY_F1 |0xC2 |194
|KEY_F2 |0xC3 |195
|KEY_F3 |0xC4 |196
Expand Down