Skip to content

Commit 6d9d1f2

Browse files
conventoangeloconventoangelo
authored
feat: add key modifiers to layout configuration (#202)
* feat: add alwaysPressedKeys to KeyboardLayout and update user config handling * feat: add support for top labels (tap-hold keys) * feat: add long key and top label font size customization * docs: add documentation for key modifiers and text settings * docs: replace title attributes from images in key modifiers with captions * fix: fallback to empty string on incomplete key configuration Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * chore: run dart format
1 parent 02d12df commit 6d9d1f2

17 files changed

Lines changed: 627 additions & 233 deletions

‎README.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -152,6 +152,7 @@ This project was initially developed to help with the creator's system-wide prac
152152
- **Auto-hide**: The keyboard hides automatically when not in use
153153
- **Keymap styles**: Supports staggered, matrix, and split matrix (5-col and [6-col](/docs/advanced/6-column-layouts.md)) styles
154154
- **User configurations**: Add and use [custom keyboard layouts](/docs/advanced/custom-layouts.md) through configuration files
155+
- **Key modifiers**: Add top labels and held-state keys to custom layouts with [key modifier objects](/docs/advanced/key-modifiers.md)
155156
- **Side-by-side layouts**: Display [alternative layouts](/docs/advanced/alternative-layouts.md) alongside the default layout
156157
- **Top row/Number row**: Optional row above the main keyboard for numbers or user-configured keys
157158
- **[Layer switching](/docs/advanced/layer-switching.md)**: Switch between multiple custom keyboard layers for QMK, ZMK, or other programmable keyboard firmware using configurable triggers and toggle modes
@@ -180,7 +181,6 @@ OverKeys can be installed through several methods:
180181
<sub>Note: Please check if `winget` version is updated to the latest version as in the repo. Otherwise, use the [installer](https://github.com/conventoangelo/OverKeys/releases/latest) to have the latest version.</sub>
181182

182183
2. **Using the Installer**
183-
184184
- Download and run the latest [EXE installer](https://github.com/conventoangelo/OverKeys/releases/latest).
185185

186186
3. **Portable Version**
@@ -202,13 +202,15 @@ Complete documentation for OverKeys is available in the [docs](docs/index.md) fo
202202
### User Guide
203203

204204
- [Preferences](/docs/user-guide/preferences.md)
205+
- [Text Settings](/docs/user-guide/text.md)
205206
- [Learning Mode](/docs/user-guide/learning-mode.md)
206207
- [Built-in Layouts](#features)
207208

208209
### Advanced Features
209210

210211
- [Custom Font](/docs/advanced/custom-font.md)
211212
- [Custom Layouts](/docs/advanced/custom-layouts.md)
213+
- [Key Modifiers](/docs/advanced/key-modifiers.md)
212214
- [Alternative Layouts](/docs/advanced/alternative-layouts.md)
213215
- [6-Column Layouts](/docs/advanced/6-column-layouts.md)
214216
- [Layer Switching](/docs/advanced/layer-switching.md)
@@ -223,7 +225,6 @@ Complete documentation for OverKeys is available in the [docs](docs/index.md) fo
223225

224226
Contributions are what make the open-source community such an amazing place to learn and collaborate. Any contributions to **OverKeys** are greatly appreciated. If you have suggestions for improvements, bug fixes, or new features, please feel free to open an issue or submit a pull request. For detailed contribution guidelines, see the [CONTRIBUTING.md](.github/CONTRIBUTING.md) file.
225227

226-
227228
<p align="right">(<a href="#readme-top">back to top</a>)</p>
228229

229230
## License

‎docs/advanced/image-1.png‎

456 KB
Loading

‎docs/advanced/image.png‎

460 KB
Loading

‎docs/advanced/key-modifiers.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# Key Modifiers
2+
3+
OverKeys supports richer key entries inside custom layouts so you can show a top label, track a different underlying key, and keep certain keys visually held. This is useful for layer-style layouts, modifier keys, and layouts that need two labels on the same key. This was greatly inspired from the key modifier support in [caksoylar's keymap-drawer](https://github.com/caksoylar/keymap-drawer).
4+
5+
## Overview
6+
7+
In `userLayouts`, each key can still be a plain string. You can also use an object with these fields:
8+
9+
- `t`: Tracked key used for key press detection and shift mapping
10+
- `h`: Top label shown near the top of the key
11+
- `type`: Optional key state hint; use `held` to keep the key rendered as pressed
12+
13+
Plain string entries continue to work exactly as before, so you can mix both formats within the same layout.
14+
15+
![Space as tracked key and shift as the top label.](image.png)
16+
*Space as tracked key and shift as the top label.*
17+
18+
![NUM layer change key with type pressed](image-1.png)
19+
*NUM layer change key with type pressed*
20+
21+
## Example
22+
23+
```jsonc
24+
{
25+
"userLayouts": [
26+
{
27+
"name": "Layer",
28+
"keys": [
29+
["A", { "h": "Shift", "t": "T", "type": "held" }],
30+
["B", "C"],
31+
],
32+
},
33+
],
34+
}
35+
```
36+
37+
In this example:
38+
39+
- `A` is rendered as a normal key
40+
- The second key displays `Shift` at the top and `T` as the tracked key
41+
- `type: "held"` keeps the key styled like it is active, useful for modifier keys or layer keys that should stay visually active
42+
43+
## Setup Instructions
44+
45+
### Turning the setting on
46+
47+
1. Open OverKeys
48+
2. Right-click the OverKeys icon in the system tray
49+
3. Select **Preferences**
50+
4. Go to the **Advanced** tab
51+
5. Toggle **Turn on advanced settings**
52+
6. Toggle **Use user layouts** if you want the custom layout to be loaded
53+
54+
### Using the Configuration File
55+
56+
1. Right-click the OverKeys tray icon
57+
2. Select **Preferences**
58+
3. Go to the **Advanced** tab
59+
4. Click **Open Config**
60+
5. Edit the `userLayouts` array using the object form where needed
61+
6. Save the file
62+
7. Right-click the tray icon and click **Reload config** to apply changes
63+
64+
## Behavior Notes
65+
66+
- `t` controls the actual key OverKeys tracks for press state and alias/shift behavior
67+
- `h` is only visual and can be omitted when you do not need a separate top label
68+
- `held` is useful for modifier or layer keys that should stay visually active
69+
70+
## Troubleshooting
71+
72+
- If a modifier key does not display correctly, make sure the JSON object uses the exact field names `h`, `t`, and `type`
73+
- If the tracked key is missing, OverKeys falls back to the top label or the object value when possible
74+
- If the label looks cramped, adjust the text sizes in the [Text Settings](../user-guide/text.md) page

‎docs/index.md‎

Lines changed: 47 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -1,45 +1,47 @@
1-
# OverKeys Documentation
2-
3-
Welcome to the OverKeys documentation! This guide will help you get started with OverKeys, a customizable, open-source on-screen keyboard visualizer for alternative layouts.
4-
5-
## Getting Started
6-
7-
- [Installation](getting-started/installation.md) - Install and set up OverKeys on your Windows machine
8-
- [Basic Usage](getting-started/basic-usage.md) - Learn how to use OverKeys's core features
9-
10-
## User Guide
11-
12-
- [Preferences](user-guide/preferences.md) - Configure OverKeys to match your needs
13-
- [Learning Mode](user-guide/learning-mode.md) - Use the specialized color scheme for learning new layouts
14-
- [Supported Layouts](../README.md#features) - View the list of built-in keyboard layouts
15-
16-
## Advanced Features
17-
18-
- [Custom Font](advanced/custom-font.md) - Use a system-installed font not found in the dropdown
19-
- [Custom Layouts](advanced/custom-layouts.md) - Create and use your own keyboard layouts
20-
- [Alternative Layouts](advanced/alternative-layouts.md) - Quickly switch between different layouts
21-
- [6-Column Layouts](advanced/6-column-layouts.md) - Set up OverKeys for a 6-column split matrix keyboard
22-
- [Layer Switching](advanced/layer-switching.md) - Switch between multiple custom keyboard layers with custom triggers
23-
- [Ignored Keys](advanced/ignored-keys.md) - Prevent specific keys from triggering the keyboard overlay
24-
- [Kanata Integration](advanced/kanata-integration.md) - Connect OverKeys with Kanata for advanced functionality
25-
- [Custom Aliases](advanced/custom-aliases.md) - Define custom aliases for key combinations
26-
- [Shift Mappings](advanced/shift-mappings.md) - Customize shift-key behavior for specific characters
27-
- [Supported Keys](advanced/supported-keys.md) - Complete list of keys you can use in custom layouts
28-
- [Locales](advanced/locales.md) - Add locale-specific keys in user configuration for key press recognition
29-
30-
## Additional Resources
31-
32-
- [Project README](../README.md) - Overview of the project
33-
- [Changelog](../CHANGELOG.md) - Release history and features
34-
- [GitHub Repository](https://github.com/conventoangelo/OverKeys) - Source code and issue tracking
35-
36-
## Common Tasks
37-
38-
- [Creating a custom layout](advanced/custom-layouts.md#creating-custom-layouts)
39-
- [Setting up alternative layout switching](advanced/alternative-layouts.md)
40-
- [Finding key names for custom layouts](advanced/supported-keys.md)
41-
- [Troubleshooting custom layouts](advanced/custom-layouts.md#troubleshooting)
42-
43-
## Support
44-
45-
If you encounter any issues or have questions, please visit the [GitHub Discussions](https://github.com/conventoangelo/OverKeys/discussions) page or [report a bug](https://github.com/conventoangelo/OverKeys/issues/new?template=bug_report.md).
1+
# OverKeys Documentation
2+
3+
Welcome to the OverKeys documentation! This guide will help you get started with OverKeys, a customizable, open-source on-screen keyboard visualizer for alternative layouts.
4+
5+
## Getting Started
6+
7+
- [Installation](getting-started/installation.md) - Install and set up OverKeys on your Windows machine
8+
- [Basic Usage](getting-started/basic-usage.md) - Learn how to use OverKeys's core features
9+
10+
## User Guide
11+
12+
- [Preferences](user-guide/preferences.md) - Configure OverKeys to match your needs
13+
- [Text Settings](user-guide/text.md) - Tune key label sizing for long labels and top labels
14+
- [Learning Mode](user-guide/learning-mode.md) - Use the specialized color scheme for learning new layouts
15+
- [Supported Layouts](../README.md#features) - View the list of built-in keyboard layouts
16+
17+
## Advanced Features
18+
19+
- [Custom Font](advanced/custom-font.md) - Use a system-installed font not found in the dropdown
20+
- [Custom Layouts](advanced/custom-layouts.md) - Create and use your own keyboard layouts
21+
- [Key Modifiers](advanced/key-modifiers.md) - Add top labels and held-state keys to custom layouts
22+
- [Alternative Layouts](advanced/alternative-layouts.md) - Quickly switch between different layouts
23+
- [6-Column Layouts](advanced/6-column-layouts.md) - Set up OverKeys for a 6-column split matrix keyboard
24+
- [Layer Switching](advanced/layer-switching.md) - Switch between multiple custom keyboard layers with custom triggers
25+
- [Ignored Keys](advanced/ignored-keys.md) - Prevent specific keys from triggering the keyboard overlay
26+
- [Kanata Integration](advanced/kanata-integration.md) - Connect OverKeys with Kanata for advanced functionality
27+
- [Custom Aliases](advanced/custom-aliases.md) - Define custom aliases for key combinations
28+
- [Shift Mappings](advanced/shift-mappings.md) - Customize shift-key behavior for specific characters
29+
- [Supported Keys](advanced/supported-keys.md) - Complete list of keys you can use in custom layouts
30+
- [Locales](advanced/locales.md) - Add locale-specific keys in user configuration for key press recognition
31+
32+
## Additional Resources
33+
34+
- [Project README](../README.md) - Overview of the project
35+
- [Changelog](../CHANGELOG.md) - Release history and features
36+
- [GitHub Repository](https://github.com/conventoangelo/OverKeys) - Source code and issue tracking
37+
38+
## Common Tasks
39+
40+
- [Creating a custom layout](advanced/custom-layouts.md#creating-custom-layouts)
41+
- [Setting up alternative layout switching](advanced/alternative-layouts.md)
42+
- [Finding key names for custom layouts](advanced/supported-keys.md)
43+
- [Troubleshooting custom layouts](advanced/custom-layouts.md#troubleshooting)
44+
45+
## Support
46+
47+
If you encounter any issues or have questions, please visit the [GitHub Discussions](https://github.com/conventoangelo/OverKeys/discussions) page or [report a bug](https://github.com/conventoangelo/OverKeys/issues/new?template=bug_report.md).

0 commit comments

Comments
 (0)