Skip to content

Commit

Permalink
docs: Move aliases to column
Browse files Browse the repository at this point in the history
  • Loading branch information
@caksoylar
caksoylar committed Jan 11, 2025
1 parent f08d7f0 commit 80f50cc
Showing 1 changed file with 27 additions and 24 deletions.
51 changes: 27 additions & 24 deletions KEYMAP_SPEC.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -151,16 +151,17 @@ x x x x x x x x x
This field is an ordered mapping of layer names to a list of `LayoutKey` specs that represent the keys on that layer.
A `LayoutKey` can be defined with either a string value or with a mapping with the following fields:

| field name (aliases) | type | default value | description |
| ------------------ | ----- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tap (t, center)` | `str` | `""` | the tap action of a key, drawn on the center of the key; spaces will be converted to line breaks[^3] |
| `hold (h, bottom)` | `str` | `""` | the hold action of a key, drawn on the bottom of the key |
| `shifted (s, top)` | `str` | `""` | the "shifted" action of a key, drawn on the top of the key |
| `left` | `str` | `""` | left legend, drawn on the left-center of the key |
| `right` | `str` | `""` | right legend, drawn on the right-center of the key |
| `type` | `str` | `""` | the styling of the key that corresponds to the [SVG class](CONFIGURATION.md#svg_style)[^4]. predefined types are `held` (a red shading to denote held down keys), `ghost` (dashed outline to denote optional keys in a layout), `trans` (lighter text for transparent keys) |
| field name | aliases | type | default value | description |
| ---------- | ------------- | ----- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tap` | `t`, `center` | `str` | `""` | the tap action of a key, drawn on the center of the key; spaces will be converted to line breaks[^3] |
| `hold` | `h`, `bottom` | `str` | `""` | the hold action of a key, drawn on the bottom of the key |
| `shifted` | `s`, `top` | `str` | `""` | the "shifted" action of a key, drawn on the top of the key |
| `left` | | `str` | `""` | left legend, drawn on the left-center of the key |
| `right` | | `str` | `""` | right legend, drawn on the right-center of the key |
| `type` | | `str` | `""` | the styling of the key that corresponds to the [SVG class](CONFIGURATION.md#svg_style)[^4]. predefined types are `held` (a red shading to denote held down keys), `ghost` (dashed outline to denote optional keys in a layout), `trans` (lighter text for transparent keys) |

[^3]: You can prevent line breaks by using double spaces `" "` to denote a single non-breaking space.

[^4]: Text styling can be overridden in the `svg_extra_style` field under `draw_config` using the `"tap"`, `"hold"`, `"shifted"`, `"left"` and `"right"` CSS classes if desired.

Using a string value such as `"A"` for a key spec is equivalent to defining a mapping with only the tap field, i.e., `{tap: "A"}`.
Expand All @@ -187,27 +188,29 @@ layers:

This is an optional field that contains a list of `ComboSpec`s, each of which is a mapping that can have the following fields:

| field name (alias) | type | default value | description |
| ------------------- | ------------------------------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `key_positions (p)` | `list[int]` | required | list of key indices that trigger the combo[^5] |
| `key (k)` | `LayoutKey`[^6] | required | key produced by the combo when triggered, `LayoutKey`'s `type` field will be combined with the type field of `ComboSpec` |
| `layers (l)` | `list[str]` | `[]`[^7] | list of layers the combo can trigger on, specified using layer names in `layers` field |
| `align (a)` | `"mid" \| "top" \| "bottom" \| "left" \| "right"` | `"mid"` | where to draw the combo: `mid` draws on the mid-point of triggering keys' center coordinates, or to the `top`/`bottom`/`left`/`right` of the triggering keys |
| `offset (o)` | `float` | `0.0` | additional offset to `top`/`bottom`/`left`/`right` positioning, specified in units of key width/height: useful for combos that would otherwise overlap |
| `dendron (d)` | `null \| bool` | `null` | whether to draw dendrons going from combo to triggering key coordinates, default is to draw for non-`mid` alignments and draw for `mid` if key coordinates are far from the combo |
| `slide (s)` | `null \| float (-1 <= val <= 1)` | `null` | slide the combo box along an axis between keys -- can be used for moving `top`/`bottom` combo boxes left/right, `left`/`right` boxes up/down, or `mid` combos between two keys |
| `arc_scale` | `float` | `1.0` | scale the arcs going left/right for `top`/`bottom` or up/down for `left`/`right` aligned combos |
| `type` | `str` | `""` | the styling of the key that corresponds to the [CSS class](CONFIGURATION.md#svg_style), see `LayoutKey` definition above |
| `width (w)` | `float` | `null` | the width of the combo box (in pixels), defaults to `draw_config.combo_w` if null |
| `height (h)` | `float` | `null` | the height of the combo box (in pixels), defaults to `draw_config.combo_h` if null |
| `rotation (r)` | `float` | `0.0` | the rotation of the combo box in degrees -- only applies to the box itself and not any dendrons |
| `draw_separate` | `null \| bool` | `null` | whether to draw the combo separate from layers, using a dedicated diagram. defaults to `draw_config.separate_combo_diagrams` if null |
| `hidden` | `bool` | `false` | do not draw this combo at all -- useful when you have the combo in the parse output but you want to ignore it through your config |
| field name | alias | type | default value | description |
| --------------- | ----- | ------------------------------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `key_positions` | `p` | `list[int]` | required | list of key indices that trigger the combo[^5] |
| `key` | `k` | `LayoutKey`[^6] | required | key produced by the combo when triggered, `LayoutKey`'s `type` field will be combined with the type field of `ComboSpec` |
| `layers` | `l` | `list[str]` | `[]`[^7] | list of layers the combo can trigger on, specified using layer names in `layers` field |
| `align` | `a` | `"mid" \| "top" \| "bottom" \| "left" \| "right"` | `"mid"` | where to draw the combo: `mid` draws on the mid-point of triggering keys' center coordinates, or to the `top`/`bottom`/`left`/`right` of the triggering keys |
| `offset` | `o` | `float` | `0.0` | additional offset to `top`/`bottom`/`left`/`right` positioning, specified in units of key width/height: useful for combos that would otherwise overlap |
| `dendron` | `d` | `null \| bool` | `null` | whether to draw dendrons going from combo to triggering key coordinates, default is to draw for non-`mid` alignments and draw for `mid` if key coordinates are far from the combo |
| `slide` | `s` | `null \| float (-1 <= val <= 1)` | `null` | slide the combo box along an axis between keys -- can be used for moving `top`/`bottom` combo boxes left/right, `left`/`right` boxes up/down, or `mid` combos between two keys |
| `arc_scale` | | `float` | `1.0` | scale the arcs going left/right for `top`/`bottom` or up/down for `left`/`right` aligned combos |
| `type` | | `str` | `""` | the styling of the key that corresponds to the [CSS class](CONFIGURATION.md#svg_style), see `LayoutKey` definition above |
| `width` | `w` | `float` | `null` | the width of the combo box (in pixels), defaults to `draw_config.combo_w` if null |
| `height` | `h` | `float` | `null` | the height of the combo box (in pixels), defaults to `draw_config.combo_h` if null |
| `rotation` | `r` | `float` | `0.0` | the rotation of the combo box in degrees -- only applies to the box itself and not any dendrons |
| `draw_separate` | | `null \| bool` | `null` | whether to draw the combo separate from layers, using a dedicated diagram. defaults to `draw_config.separate_combo_diagrams` if null |
| `hidden` | | `bool` | `false` | do not draw this combo at all -- useful when you have the combo in the parse output but you want to ignore it through your config |

All fields except `key_positions`, `key`, `type` and `hidden` are ignored when combo is drawn in a separate diagram using `draw_separate` or `draw_config.separate_combo_diagrams`.

[^5]: Key indices start from `0` on the first key position and increase by columns and then rows, corresponding to their ordering in the `layers` field. This matches the `key-positions` property in ZMK combo definitions.

[^6]: Just like for keys in a layer under the `layers` field, `key` field can be specified with a string value as a shortcut, or a mapping (where the `type` field will be ignored).

[^7]: The default value of empty list corresponds to all layers in the keymap, similar to the `layers` property in ZMK.

_Example:_
Expand Down

0 comments on commit 80f50cc

Please sign in to comment.