From 9f22e53a3ba8f064e69e3a84c371a7f29ee9e05c Mon Sep 17 00:00:00 2001
From: Jules Aguillon
Date: Sun, 29 Sep 2024 21:58:22 +0200
Subject: Add complex keys (#774)

This allows to add new kinds of keys that need more data without making
KeyValue's footprint bigger for common keys.

This changes the [_symbol] field into [_payload], which holds the same
as the previous field for more common keys but can hold bigger objects
for keys of the new "Complex" kind.

This also adds a complex key: String keys with a symbol different than
the outputted string.

Unit tests are added as the Java language is not helpful in making
robust code.---
 doc/Possible-key-values.md | 27 ++++++++++++++++++++++++++-
 1 file changed, 26 insertions(+), 1 deletion(-)

(limited to 'doc')

diff --git a/doc/Possible-key-values.md b/doc/Possible-key-values.md
index 57d5a90..c420f8d 100644
--- a/doc/Possible-key-values.md
+++ b/doc/Possible-key-values.md
@@ -119,7 +119,7 @@ Keys ending in `_placeholder` are normally hidden unless the Fn key is pressed.
 `ole`, `ole_placeholder`,
 `meteg`, `meteg_placeholder`
 
-## Unexpected Keyboard specific
+## Keyboard behavior keys
 Value                  | Meaning
 :--------------------- | :------
 `config`               | Gear icon; opens Unexpected Keyboard settings.
@@ -148,3 +148,28 @@ These keys are known to do nothing.
 These keys are normally hidden unless the Fn modifier is activated.
 
 `f11_placeholder` | `f12_placeholder`
+
+## Complex keys
+
+More complex keys are of this form:
+
+```
+:<kind> <attributes>:<payload>
+```
+
+Where `<kind>` is one of the kinds documented below and `<attributes>` is a
+space separated list of attributes. `<payload>` depends on the `<kind>`.
+
+Attributes are:
+- `symbol='Sym'` is the symbol to be shown on the keyboard.
+- `flags='<flags>'` is a collection of flags that change the behavior of the key.
+  `<flags>` is a coma separated list of:
+  + `dim`: Make the symbol dimmer.
+  + `small`: Make the symbol smaller.
+
+### Kind `str`
+
+Defines a key that outputs an arbitrary string. `<payload>` is a string wrapped
+in single-quotes (`'`), escaping of other single quotes is allowed with `\'`.
+
+For example: `:str symbol='Sym':'Output string'`
-- 
cgit v1.2.3