cheerfulScumbagandGitHub
2a1efe0468
* feat: add keybind cheatsheet * docs: refresh keybind cheatsheet preview * docs: use official generated keybind thumbnail * feat(keybind-cheatsheet): preload cached snapshots Move parser and cache ownership into an event-driven data service so the panel opens from a prepared last-known-good snapshot. Document the plugin's inspiration and independent v5 implementation.
171 lines
6.3 KiB
Markdown
171 lines
6.3 KiB
Markdown
# Keybind Cheatsheet
|
|
|
|
Keybind Cheatsheet opens a searchable Noctalia panel containing the active
|
|
Mango, Hyprland, or Niri shortcuts. It follows split configuration files,
|
|
formats common hardware keys, and keeps custom descriptions and hidden rows.
|
|
|
|
|
|
|
|
## Acknowledgements
|
|
|
|
Keybind Cheatsheet was inspired by the original
|
|
[Keybind Cheatsheet for Noctalia v4](https://github.com/4rmcyt/noctalia-plugins/tree/main/keybind-cheatsheet)
|
|
created by [blackbartblues](https://github.com/blackbartblues).
|
|
|
|
This Noctalia v5 plugin is an independent implementation rather than a direct
|
|
port. It has its own user interface, service and cache lifecycle, persistence
|
|
model, tests, and integration with the current Noctalia plugin API.
|
|
|
|
## Plugin
|
|
|
|
| Field | Value |
|
|
| --- | --- |
|
|
| ID | `kenn/keybind-cheatsheet` |
|
|
| Entries | Data service: `data`; bar widget: `keybinds`; panel: `cheatsheet` |
|
|
|
|
`kenn` is the plugin's fixed publisher namespace, not your local Linux
|
|
username. Copy the plugin IDs in the commands below unchanged. User-specific
|
|
configuration paths use the portable `~/.config/...` form.
|
|
|
|
## Requirements
|
|
|
|
Install `hyprctl` on `PATH` when using a Hyprland Lua configuration. Mango,
|
|
Niri, and classic Hyprland configurations do not spawn external commands.
|
|
|
|
No clipboard command is required. Color paste uses Noctalia's native clipboard
|
|
API.
|
|
|
|
## Usage
|
|
|
|
Enable the plugin, then add the `keybinds` widget from Noctalia's bar widget
|
|
picker. Clicking its keyboard glyph toggles the cheatsheet.
|
|
|
|
Open or close the panel without a bar widget:
|
|
|
|
```sh
|
|
noctalia msg panel-toggle kenn/keybind-cheatsheet:cheatsheet
|
|
```
|
|
|
|
Bind that command in the active compositor.
|
|
|
|
Mango:
|
|
|
|
```ini
|
|
bind=SUPER,F1,spawn,noctalia msg panel-toggle kenn/keybind-cheatsheet:cheatsheet
|
|
```
|
|
|
|
Hyprland classic configuration:
|
|
|
|
```ini
|
|
bind = SUPER, F1, exec, noctalia msg panel-toggle kenn/keybind-cheatsheet:cheatsheet
|
|
```
|
|
|
|
Niri:
|
|
|
|
```kdl
|
|
Mod+F1 { spawn "noctalia" "msg" "panel-toggle" "kenn/keybind-cheatsheet:cheatsheet"; }
|
|
```
|
|
|
|
Type in the search field to filter by key, description, action, or category.
|
|
Use the header pencil to enter edit mode. Edit mode keeps hidden bindings
|
|
visible with muted content while descriptions and visibility are changed with
|
|
the row's pencil and eye buttons; leaving edit mode applies those visibility
|
|
choices to the main keymap. The palette button opens key-color controls with
|
|
native color picking, clipboard paste, and reset actions.
|
|
|
|
## Supported configuration
|
|
|
|
| Compositor | Default | Parsing |
|
|
| --- | --- | --- |
|
|
| Mango | `~/.config/mango/config.conf` | `bind`, `axisbind`, `mousebind`, `gesturebind`, `switchbind`, `source`, and `source-optional` |
|
|
| Hyprland classic | `~/.config/hypr/hyprland.conf` | `bind*` directives, variables, and recursive `source` paths |
|
|
| Hyprland Lua | `~/.config/hypr/hyprland.lua` | Live `hyprctl binds -j` data plus category and description scanning through `require()` files |
|
|
| Niri | `~/.config/niri/config.kdl` | KDL `binds` blocks, action categorization, and recursive `include` paths |
|
|
|
|
Includes support `*`, `?`, and bracket glob components. Traversal is limited to
|
|
32 levels and 256 files, and repeated paths are visited once to stop cycles.
|
|
|
|
Category comments use the same forms as the earlier Noctalia plugin:
|
|
|
|
```ini
|
|
# Applications
|
|
bind=SUPER,T,spawn,foot #"Terminal"
|
|
```
|
|
|
|
```ini
|
|
# 1. Applications
|
|
bind = SUPER, T, exec, foot #"Terminal"
|
|
```
|
|
|
|
```kdl
|
|
// #"Applications"
|
|
Mod+T hotkey-overlay-title="Terminal" { spawn "foot"; }
|
|
```
|
|
|
|
Hyprland Lua category scanning recognizes `-- 1. Applications` headings and
|
|
literal `description` or `desc` fields. Concatenated descriptions such as
|
|
`"Workspace " .. i` are treated as prefixes.
|
|
|
|
## Settings
|
|
|
|
| Setting | Type | Default | Description |
|
|
| --- | --- | --- | --- |
|
|
| `compositor` | `select` | `auto` | Detect Mango, Hyprland, or Niri, or force one parser. |
|
|
| `mango_config` | `file` | `~/.config/mango/config.conf` | Main Mango configuration. |
|
|
| `hyprland_config` | `file` | `~/.config/hypr/hyprland.conf` | Main classic Hyprland configuration. |
|
|
| `hyprland_lua_config` | `file` | `~/.config/hypr/hyprland.lua` | Lua file scanned for categories. |
|
|
| `hyprland_parser` | `select` | `auto` | Select live Lua or classic parsing. |
|
|
| `niri_config` | `file` | `~/.config/niri/config.kdl` | Main Niri configuration. |
|
|
| `columns` | `int` | `3` | Maximum balanced columns, from 1 to 4. |
|
|
| `show_undescribed` | `bool` | `true` | Show bindings that have no description. |
|
|
| `show_actions` | `bool` | `false` | Show the compositor action under descriptions. |
|
|
| `glyph` | `glyph` | `keyboard` | Bar widget icon. |
|
|
|
|
Noctalia v5 owns panel dimensions and does not expose runtime auto-height.
|
|
This plugin uses a wide 1500 x 760 panel, scrolling, and a responsive cap on
|
|
the requested column count.
|
|
|
|
## IPC
|
|
|
|
Refresh the snapshot after editing compositor configuration:
|
|
|
|
```sh
|
|
noctalia msg plugin kenn/keybind-cheatsheet:data all refresh
|
|
```
|
|
|
|
The data service refreshes even when the panel is closed. Opening and reopening
|
|
the panel only renders the prepared snapshot. The bar entry also accepts
|
|
`toggle` and `refresh` when a widget instance exists:
|
|
|
|
```sh
|
|
noctalia msg plugin kenn/keybind-cheatsheet:keybinds focused toggle
|
|
noctalia msg plugin kenn/keybind-cheatsheet:keybinds focused refresh
|
|
```
|
|
|
|
For parser development, run the fixture suite inside Noctalia:
|
|
|
|
```sh
|
|
noctalia msg plugin kenn/keybind-cheatsheet:data all self-test
|
|
```
|
|
|
|
The report is logged and written to the plugin's persistent data directory as
|
|
`selftest.json`.
|
|
|
|
## Notes
|
|
|
|
One event-driven data service loads the durable binding cache and parses the
|
|
selected compositor configuration once when Noctalia loads the plugin. It then
|
|
remains idle until settings change or a refresh is explicitly requested. It
|
|
uses no update interval, filesystem watcher, polling loop, network request, or
|
|
persistent subprocess. Hyprland Lua mode runs the fixed command
|
|
`hyprctl binds -j` asynchronously.
|
|
|
|
The last successful parsed snapshot is stored as `bindings-cache.json`. The
|
|
panel reads the shared in-memory snapshot and performs no configuration I/O in
|
|
`onOpen()`. A failed refresh keeps the previous bindings visible and reports
|
|
the error without replacing the durable cache.
|
|
|
|
Custom descriptions, hidden binding identities, and color overrides are stored
|
|
in Noctalia's per-plugin state directory as `preferences.json`. The file
|
|
contains no command output or configuration contents.
|