From 92d50dd73fd5b1fe82d596dc6af9b17ff72c5096 Mon Sep 17 00:00:00 2001 From: Spike <126838489+Spike-from-NH@users.noreply.github.com> Date: Thu, 27 Feb 2025 16:12:59 -0500 Subject: [PATCH] Clerical edits to "Possible values.md" (#907) * Massage Intro Start with definition, then use cases, then valid syntax. Use "legend" rather than "symbol" for the visible legend on the keyboard Rephrase to avoid "exhaustive". Other simplifications. * Edit section "Modifiers" Separate into two tables, each preceded by relevant introduction * Shuffle sections Retitle "Special keys"; as used in the Intro, this term refers to all the keywords in this file. Put two contrasting sections together, add "In contrast," and reword. --- doc/Possible-key-values.md | 61 ++++++++++++++++++++++---------------- 1 file changed, 36 insertions(+), 25 deletions(-) diff --git a/doc/Possible-key-values.md b/doc/Possible-key-values.md index 2073627..a5defef 100644 --- a/doc/Possible-key-values.md +++ b/doc/Possible-key-values.md @@ -1,30 +1,36 @@ # Key values -A key value is the denomination of a key accepted in the "Add keys to the keyboard" option or for the `nw`, ..., `se` attributes in custom layouts (or `key0` ... `key8`). -It can be: +A key value defines what a key on the keyboard does when pressed or swiped. -- The name of a special key. An exhaustive list of the special keys follows. +Key values appear in the following places: + +- In custom layouts, they are the value of: the `c` attribute, the compass-point attributes `nw` ... `se`, and the old-style `key0` ... `key8` attributes. +- Internally, they are used in the definition of the "Add keys to the keyboard" setting. + +Key values can be any of the following: + +- The name of a special key. A complete list of valid special keys follows. - An arbitrary sequence of characters not containing `:`. This results in a key that writes the specified characters. -- Using the syntax `symbol:key_def`. - `symbol` is the symbol that appears on the keyboard, it cannot contain `:`. +- The syntax `legend:key_def`. + `legend` is the visible legend on the keyboard. It cannot contain `:`. `key_def` can be: + The name of a special key, as listed below. - + `'Arbitrary string'` An arbitrary string that can contain `:`. `'` can be added to the string as `` \' ``. + + `'string'` An arbitrary string that can contain `:`. `'` can be added to the string as `` \' ``. + `keyevent:keycode` An Android keycode. They are listed as `KEYCODE_...` in [KeyEvent](https://developer.android.com/reference/android/view/KeyEvent#summary). Examples: - + `⏯:keyevent:85` A play/pause key (which probably doesn't do anything in most apps). - + `my@:'my.email@domain.com'` An arbitrary string key + + `⏯:keyevent:85` A play/pause key (which has no effect in most apps). + + `my@:'my.email@domain.com'` A key that sends an arbitrary string - A macro, `symbol:key_def1,key_def2,...`. This results in a key that behaves as if the sequence of `key_def` had been pressed in order. Examples: - + `CA:ctrl,a,ctrl,c` The sequence `ctrl+a`, `ctrl+c`. - + `Cd:ctrl,backspace` The shortcut `ctrl+backspace`. + + `CA:ctrl,a,ctrl,c` A key with legend CA that sends the sequence `ctrl+a`, `ctrl+c`. + + `Cd:ctrl,backspace` A key with legend Cd that sends the shortcut `ctrl+backspace`. ## Escape codes Value | Escape code for @@ -46,19 +52,24 @@ Value | Escape code for `"` | `"` ## Modifiers -System modifiers are sent to the app, which is free to do whatever they want in response. -The other modifiers only exist within the keyboard. +System modifiers are sent to the app, which can take app-specific action. + Value | Meaning :---------- | :------ `shift` | System modifier. `ctrl` | System modifier. `alt` | System modifier. `meta` | System modifier. Equivalent to the Windows key. -`fn` | Activates Fn mode, which assigns letters and symbols to special characters. e.g. `fn` `!` = `¡` -`compose` | Compose key. Enables composing characters using Linux-like shortcuts; e.g. `Compose` `A` `single quote` types `Á` (A with acute accent). -`capslock` | Actives and locks Shift -## Special keys +The other modifiers take effect only within the keyboard. + +Value | Meaning +:---------- | :------ +`fn` | Activates Fn mode, which assigns letters and symbols to special characters. Example: `fn` `!` = `¡` +`compose` | Compose key. Enables composing characters using Linux-like shortcuts. Example: `Compose` `A` `'` types `Á` (A with acute accent). +`capslock` | Activates and locks Shift. + +## App function keys These keys are sent to apps, which are free to ignore them. The keyboard does not perform editing in response to these keys. `esc`, `enter`, @@ -74,6 +85,15 @@ These keys are sent to apps, which are free to ignore them. The keyboard does no `selectAll`, `pasteAsPlainText`, `undo`, `redo` +## Keyboard editing actions +In contrast, these keys perform editing on the text without sending anything to the app. +Value | Meaning +:----------------- | :------ +`cursor_left` | Moves the cursor to the left with the slider gesture. +`cursor_right` | Moves the cursor to the right with the slider gesture. +`cursor_up` | Moves the cursor up with the slider gesture. Warning: this might make the cursor leave the text box. +`cursor_down` | Moves the cursor down with the slider gesture. Warning: this might make the cursor leave the text box. + ## Whitespace Value | Meaning :------ | :------ @@ -83,15 +103,6 @@ Value | Meaning `zwj` | Zero-width joiner. `zwnj` | Zero-width non-joiner. -## Keyboard editing actions -These keys perform editing on the text without sending keys that the app can interpret differently or ignore. -Value | Meaning -:----------------- | :------ -`cursor_left` | Moves the cursor to the left with the slider gesture. -`cursor_right` | Moves the cursor to the right with the slider gesture. -`cursor_up` | Moves the cursor up with the slider gesture. Warning: this might make the cursor leave the text box. -`cursor_down` | Moves the cursor down with the slider gesture. Warning: this might make the cursor leave the text box. - ## Other modifiers and diacritics Value | Meaning :------------------- | :------