🔀 Merge pull request #427 from kando-menu/feature/improve-docs

README.md

@@ -15,31 +15,26 @@ SPDX-License-Identifier: CC-BY-4.0
 [![Discord](https://img.shields.io/discord/1124300911574003732?logo=discord&label=Discord&color=%235865f2)](https://discord.gg/hZwbVSDkhy)
 [![docs](https://img.shields.io/badge/Documentation-online-purple.svg?labelColor=303030)](docs/README.md)
 
-**Kando** will be a pie menu for the desktop.
-It will be highly customizable and will allow you to create your own menus and actions.
-For instance, you can use it to control your music player, to open your favorite websites or to simulate shortcuts.
-It will be available for Windows, Linux and macOS.
+**Kando** is a highly customizable pie menu for the desktop which allows you to create your own menus and actions.
+For instance, you can use it to control your music player, to open your favorite websites, or to simulate shortcuts.
+It is available for Windows, Linux and macOS.
 
 # The Vision
 
-> [!WARNING]
-> This project is in an early stage of development.  You can read regular updates on the project on [my Ko-fi page](https://ko-fi.com/schneegans).
-
 I am the developer of [Fly-Pie](https://github.com/Schneegans/Fly-Pie/), which is a similar project but limited to the GNOME desktop.
 I have been working on Fly-Pie for more than 3 years now and I am very happy with the result.
 However, I have always wanted to create a similar application for the desktop in general.
 This is why I started this project.
 
-**Kando is very similar to Fly-Pie in terms of interaction and appearance.
-At the same time, there will be some major differences.
-You can read more in this [blog post](https://ko-fi.com/post/Introducing-Ken-Do-L3L7L0FQ2)!**
-
 <p align="center">
   <img src="docs/img/kando.gif"/>
 </p>
 
+**Kando** is very similar to Fly-Pie in terms of interaction and appearance.
+At the same time, there are some major differences.
+You can read more in this [blog post](https://ko-fi.com/post/Introducing-Ken-Do-L3L7L0FQ2)!
+
 
-The prototype already features the same interaction methods as Fly-Pie (point-and-click, marking mode, and turbo mode).
 
 # Platform Support
 

docs/README.md

@@ -9,7 +9,7 @@ SPDX-License-Identifier: CC-BY-4.0
 
 Kando is a cross-platform pie menu which is still under heavy development.
 This documentation is also work-in-progress, but it will already give you an overview of the project and help you to get started.
-If you have any questions, please feel free to [open a discussion](https://github.com/orgs/kando-menu/discussions).
+If you have any questions, please feel free to [join the Discord server](https://discord.gg/hZwbVSDkhy) or [open a discussion on GitHub](https://github.com/orgs/kando-menu/discussions).
 If you want to improve this documentation, please [open a pull request](https://github.com/kando-menu/kando/pulls)!
 
 ## General Information

docs/changelog.md

@@ -17,6 +17,14 @@ Security   - in case of vulnerabilities.
 Kando uses [semantic versioning](https://semver.org).
 This changelog follows the rules of [Keep a Changelog](http://keepachangelog.com/).
 
+## [unreleased]
+
+**Release Date:** TBD
+
+#### Added
+
+- Some documentation about the [format of the shortcuts and hotkeys used in Kando](configuring.md#menu-shortcuts-vs-simulated-hotkeys).
+
 ## [Kando 0.9.0](https://github.com/kando-menu/kando/releases/tag/v0.9.0)
 
 <a href="https://www.youtube.com/watch?v=_3KkDnfu_CE">

docs/configuring.md

@@ -7,8 +7,17 @@ SPDX-License-Identifier: CC-BY-4.0
 
 # Configuring Kando
 
-> [!WARNING]
-> This project is currently in a very early stage of development. There is not yet a graphical configuration tool and the configuration file format is not yet stable. You can read regular updates on the project on [my Ko-fi page](https://ko-fi.com/schneegans)!
+Kando comes with a graphical menu editor which allows you to create and edit your own menus.
+All configuration is stored JSON files which you can also edit manually.
+
+## The Menu Editor
+
+<img src="img/settings-button.jpg" align="right" width="150px"></img>
+
+There are three ways to open the menu editor:
+1. **When a menu is shown:** Click the gear icon in the bottom right corner of the screen.
+2. **From the system tray:** Right-click the Kando icon and select "Show Settings".
+3. **From the command line:** Run `kando --settings`.
 
 ## The Configuration Files
 
@@ -38,7 +47,7 @@ Property | Default Value | Description
 ### The Menu Configuration: `menus.json`
 
 This file contains the configuration of the individual menus.
-The top-level JSON object is called `menus` and contains a list of menu descriptions:
+There are two top-level JSON objects: `menus` contains a list of _Menu Descriptions_ and `stash` contains a list of currently stashed menu items as _Menu Item Descriptions_.
 
 ```js
 {
@@ -52,6 +61,9 @@ The top-level JSON object is called `menus` and contains a list of menu descript
       // ...
     },
     // ...
+  ],
+  "stash": [
+    // Currently stashed Menu Items.
   ]
 }
 ```
@@ -67,7 +79,7 @@ They are JSON objects with the following properties:
 
 Property | Default Value | Description
 -------- | ------------- | -----------
-`shortcut` | `""` | The shortcut which opens the menu. This is a string which can contain multiple keys separated by `+`. For example, `"Ctrl+Shift+K"` or `"Cmd+Shift+K"`. If empty, the menu will not have a shortcut.
+`shortcut` | `""` | The shortcut which opens the menu. This is a string which can contain multiple keys separated by `+`. For example, `"Ctrl+Shift+K"` or `"Cmd+Shift+K"`. If empty, the menu will not have a shortcut. See [Menu Shortcuts vs. Simulated Hotkeys](#menu-shortcuts-vs-simulated-hotkeys) for details.
 `shortcutID` | `""` | On some platforms, Kando can not bind shortcuts directly. In this case, you can use this property to assign an ID which can be used in the global shortcut configuration of your desktop environment. This should be lowercase and contain only ASCII characters and dashes. For example, `"main-trigger"`.
 `nodes` | _mandatory_ | The root menu item of the menu given as a Menu Item Description. See below for details.
 `centered` | `false` | Whether the menu should be centered on the screen. If this is `false`, the menu will be opened at the position of the mouse cursor.
@@ -120,20 +132,231 @@ New types will be added in the future.
 }
 ```
 
-**`"hotkey"`:** This type is used to simulate a keyboard shortcut. The `data` property of the menu item must contain a `hotkey` property which contains the shortcut to simulate. The optional `delayed` property will ensure that the hotkey is simulated _after_ the Kando window is closed. This can be used if the hotkey should be captured by another window. For instance, this menu item will paste the clipboard content:
+**`"hotkey"`:** This type is used to simulate keyboard events. The `data` property of the menu item must contain a `hotkey` property which contains the hotkey to simulate. See [Menu Shortcuts vs. Simulated Hotkeys](#menu-shortcuts-vs-simulated-hotkeys) for details on the format of the `hotkey` property. The optional `delayed` property will ensure that the hotkey is simulated _after_ the Kando window is closed. This can be used if the hotkey should be captured by another window. For instance, this menu item will paste the clipboard content:
 ```json
 {
   "name": "Paste",
   "icon": "content_paste_go",
   "iconTheme": "material-symbols-rounded",
   "type": "hotkey",
   "data": {
-    "hotkey": "Control+V",
+    "hotkey": "ControlLeft+KeyV",
     "delayed": true
   }
 }
 ```
 
+## Menu Shortcuts vs. Simulated Hotkeys
+
+With Kando, you can bind a menu to a keyboard shortcut and use menu items to simulate keyboard hotkeys.
+This is a bit confusing as both are configured similarly, but use different formats.
+
+Below is the configuration of a menu bound to <kbd>Ctrl</kbd>+<kbd>V</kbd> and a menu item simulating <kbd>Ctrl</kbd>+<kbd>V</kbd>.
+As you can see, the format for the key combination is different.
+
+Menu-Shortcut Configuration | Hotkey-Item Configuration
+--------------------------- | -------------------------
+![shortcut](img/menu-settings.jpg) | ![hotkey](img/hotkey-settings.jpg)
+
+The reason for this is complex: Depending on the platform, Kando uses different mechanisms to bind menus to shortcuts.
+All of these require _key names_ for the shortcuts.
+The hotkey items on the other hand simulate _key codes_.
+Each key on your keyboard has a unique _key code_.
+The keyboard layout you have set in your OS assigns a _key name_ to each _key code_.
+For instance, the key with the _code_ `KeyZ` gets the _name_ `Y` with a German keyboard layout.
+
+### Valid Menu Shortcuts (using _key names_)
+
+On most platforms, Kando uses the [Electron Accelerator](https://www.electronjs.org/docs/api/accelerator) format to bind shortcuts.
+Hence, each shortcut may contain any number of modifiers and must end with a key name.
+All names are case-insensitive and must be separated by `+`.
+
+**Available Modifier Names:**
+<kbd>Command</kbd>
+<kbd>Cmd</kbd>
+<kbd>Control</kbd>
+<kbd>Ctrl</kbd>
+<kbd>CommandOrControl</kbd>
+<kbd>CmdOrCtrl</kbd>
+<kbd>Alt</kbd>
+<kbd>Option</kbd>
+<kbd>AltGr</kbd>
+<kbd>Shift</kbd>
+<kbd>Super</kbd>
+<kbd>Meta</kbd>
+
+**Available Key Names:** <kbd>0</kbd>-<kbd>9</kbd>
+<kbd>A</kbd>-<kbd>Z</kbd>
+<kbd>F1</kbd>-<kbd>F24</kbd>
+<kbd>)</kbd>
+<kbd>!</kbd>
+<kbd>@</kbd>
+<kbd>#</kbd>
+<kbd>$</kbd>
+<kbd>%</kbd>
+<kbd>^</kbd>
+<kbd>&</kbd>
+<kbd>*</kbd>
+<kbd>(</kbd>
+<kbd>:</kbd>
+<kbd>;</kbd>
+<kbd>'</kbd>
+<kbd>+</kbd>
+<kbd>=</kbd>
+<kbd><</kbd>
+<kbd>,</kbd>
+<kbd>_</kbd>
+<kbd>-</kbd>
+<kbd>></kbd>
+<kbd>.</kbd>
+<kbd>?</kbd>
+<kbd>/</kbd>
+<kbd>~</kbd>
+<kbd>`</kbd>
+<kbd>{</kbd>
+<kbd>]</kbd>
+<kbd>[</kbd>
+<kbd>|</kbd>
+<kbd>\\</kbd>
+<kbd>}</kbd>
+<kbd>"</kbd>
+<kbd>Plus</kbd>
+<kbd>Space</kbd>
+<kbd>Tab</kbd>
+<kbd>Capslock</kbd>
+<kbd>Numlock</kbd>
+<kbd>Scrolllock</kbd>
+<kbd>Backspace</kbd>
+<kbd>Delete</kbd>
+<kbd>Insert</kbd>
+<kbd>Return</kbd>
+<kbd>Enter</kbd>
+<kbd>Up</kbd>
+<kbd>Down</kbd>
+<kbd>Left</kbd>
+<kbd>Right</kbd>
+<kbd>Home</kbd>
+<kbd>End</kbd>
+<kbd>PageUp</kbd>
+<kbd>PageDown</kbd>
+<kbd>Escape</kbd>
+<kbd>Esc</kbd>
+<kbd>VolumeUp</kbd>
+<kbd>VolumeDown</kbd>
+<kbd>VolumeMute</kbd>
+<kbd>MediaNextTrack</kbd>
+<kbd>MediaPreviousTrack</kbd>
+<kbd>MediaStop</kbd>
+<kbd>MediaPlayPause</kbd>
+<kbd>PrintScreen</kbd>
+<kbd>num0</kbd>-<kbd>num9</kbd>
+<kbd>numdec</kbd>
+<kbd>numadd</kbd>
+<kbd>numsub</kbd>
+<kbd>nummult</kbd>
+<kbd>numdiv</kbd>
+
+### Valid Simulated Hotkeys (using _key codes_)
+
+The configuration of the hotkey items should also contain any number of modifier key codes followed by a single non-modifier key code, all separated by `+`.
+Note that not all key codes are available on all platforms.
+
+**Available Modifier Key Codes:** 
+<kbd>AltLeft</kbd>
+<kbd>AltRight</kbd>
+<kbd>ControlLeft</kbd>
+<kbd>ControlRight</kbd>
+<kbd>MetaLeft</kbd>
+<kbd>MetaRight</kbd>
+<kbd>ShiftLeft</kbd>
+<kbd>ShiftRight</kbd>
+
+**Available Non-Modifier Key Codes:**
+<kbd>Again</kbd>
+<kbd>ArrowDown</kbd>
+<kbd>ArrowLeft</kbd>
+<kbd>ArrowRight</kbd>
+<kbd>ArrowUp</kbd>
+<kbd>AudioVolumeDown</kbd>
+<kbd>AudioVolumeMute</kbd>
+<kbd>AudioVolumeUp</kbd>
+<kbd>Backquote</kbd>
+<kbd>Backslash</kbd>
+<kbd>Backspace</kbd>
+<kbd>BracketLeft</kbd>
+<kbd>BracketRight</kbd>
+<kbd>BrowserBack</kbd>
+<kbd>BrowserFavorites</kbd>
+<kbd>BrowserForward</kbd>
+<kbd>BrowserHome</kbd>
+<kbd>BrowserRefresh</kbd>
+<kbd>BrowserSearch</kbd>
+<kbd>BrowserStop</kbd>
+<kbd>CapsLock</kbd>
+<kbd>Comma</kbd>
+<kbd>ContextMenu</kbd>
+<kbd>Convert</kbd>
+<kbd>Copy</kbd>
+<kbd>Cut</kbd>
+<kbd>Delete</kbd>
+<kbd>Digit0</kbd>-<kbd>Digit9</kbd>
+<kbd>Eject</kbd>
+<kbd>End</kbd>
+<kbd>Enter</kbd>
+<kbd>Equal</kbd>
+<kbd>Escape</kbd>
+<kbd>F1</kbd>-<kbd>F24</kbd>
+<kbd>Find</kbd>
+<kbd>Help</kbd>
+<kbd>Home</kbd>
+<kbd>Insert</kbd>
+<kbd>IntlBackslash</kbd>
+<kbd>IntlRo</kbd>
+<kbd>IntlYen</kbd>
+<kbd>KanaMode</kbd>
+<kbd>KeyA</kbd>-<kbd>KeyZ</kbd>
+<kbd>Lang1</kbd>-<kbd>Lang5</kbd>
+<kbd>LaunchApp1</kbd>
+<kbd>LaunchApp2</kbd>
+<kbd>LaunchMail</kbd>
+<kbd>MediaPlayPause</kbd>
+<kbd>MediaSelect</kbd>
+<kbd>MediaStop</kbd>
+<kbd>MediaTrackNext</kbd>
+<kbd>MediaTrackPrevious</kbd>
+<kbd>Minus</kbd>
+<kbd>NonConvert</kbd>
+<kbd>NumLock</kbd>
+<kbd>Numpad0</kbd>-<kbd>Numpad9</kbd>
+<kbd>NumpadAdd</kbd>
+<kbd>NumpadComma</kbd>
+<kbd>NumpadDecimal</kbd>
+<kbd>NumpadDivide</kbd>
+<kbd>NumpadEnter</kbd>
+<kbd>NumpadEqual</kbd>
+<kbd>NumpadMultiply</kbd>
+<kbd>NumpadParenLeft</kbd>
+<kbd>NumpadParenRight</kbd>
+<kbd>NumpadSubtract</kbd>
+<kbd>Open</kbd>
+<kbd>PageDown</kbd>
+<kbd>PageUp</kbd>
+<kbd>Paste</kbd>
+<kbd>Pause</kbd>
+<kbd>Period</kbd>
+<kbd>Power</kbd>
+<kbd>PrintScreen</kbd>
+<kbd>Quote</kbd>
+<kbd>ScrollLock</kbd>
+<kbd>Select</kbd>
+<kbd>Semicolon</kbd>
+<kbd>Slash</kbd>
+<kbd>Sleep</kbd>
+<kbd>Space</kbd>
+<kbd>Tab</kbd>
+<kbd>Undo</kbd>
+<kbd>WakeUp</kbd>
+
 <p align="center"><img src ="img/hr.svg" /></p>
 
 <p align="center">