Skip to content

Latest commit

 

History

History
314 lines (273 loc) · 12.7 KB

configuring.md

File metadata and controls

314 lines (273 loc) · 12.7 KB
Raw

Configuring Kando

Kando comes with an example menu which you can use to get started. However, you should soon adapt the menu to your needs and create your own menus.

Kando comes with a graphical menu editor which allows you to create and edit your own menus. 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.

In the editor, you can create new menus, and edit existing menus. Drag new items from the toolbar to the menu preview, reorder them, and change their properties on the right side of the screen.

Tip

There are several advanced options which are not yet exposed in the editor UI. See the Config-File Documentation for all advanced options.

🚀 Tips for Creating Efficient Menu Layouts

When designing your own menus, keep the following tips in mind:

  • Avoid too many items in a single menu. Instead, create submenus. Eight items per menu is a good rule of thumb, and you should never have more than twelve items in a single menu.
  • Deeply nested menus are not a problem. Kando is designed to handle deeply nested menus. You can use the marking mode to quickly select items which are in subsubsubmenus.
  • Use the fixed-angle locks to create a clean layout. Even if you have an odd number of items, you can use fixed angles to lock items to the top, bottom, left, or right side of the menu.

✨ Adding Custom Icon Themes

To add your own icons to Kando, follow these steps:

  1. Create a new icon-themes directory in Kando's configuration directory if it does not yet exist. Depending on your OS, this will be the following locations:
    • Windows: %appdata%\kando\icon-themes
    • macOS: ~/Library/Application Support/kando/icon-themes
    • Linux: ~/.config/kando/icon-themes
  2. Create a new directory for your icon theme in the icon-themes directory. You can give it any name you like.
  3. Add your icons to the new directory. The icons can be in various formats, but we recommend using SVG files.
  4. Restart Kando. Icon themes are only loaded when Kando starts.
  5. Select your icon theme in the icon-theme dropdown in the icon picker in Kando's menu editor.

Caution

Kando will also load icon themes from resources/app/.webpack/renderer/assets/icon-themes/ in the installation directory. This can be interesting if you are packaging icon themes using a package manager. However, as an end user, you should not put your icon themes there, as they might be overwritten during an update.

Some Tips for Creating Icon Themes

  • You can organize your icons in subdirectories. Kando will load them recursively. The directory will be part of the icon's name and therefore you can use the search bar to filter by directory.
  • There are many great icon sets available on the internet. Here are some which you could try:
    • Numix Circle: Just use the files from the Numix-Circle/48/apps directory.
    • Papirus: Here you could use the content from the Papirus/64x64 directory.
    • Tela: Here you find the icons in the src/scalable directory.

🖱️ Opening Menus without the Keyboard

While Kando does not have a cross-platform way to open menus with a mouse button, there are many platform-dependent third-party tools which can help you with this. With some creativity, you can open menus not only with mouse buttons but also with gestures, desktop widgets, or in many other ways.

You can either make the third-party tool open the menu by simulation the shortcut for the menu, or it can directly call the Kando executable with the --menu "menu name" argument.

  • Windows: %localappdata%\Kando\app-<version number>\Kando.exe --menu "Menu Name"
  • macOS: /Applications/Kando.app/Contents/MacOS/Kando --menu "Menu Name"
  • Linux: /usr/bin/kando --menu "Menu Name"

Below are some applications which can help you to open menus in various ways. If you discovered a cool new way to open menus, please let us know! You can either open an issue, open a pull request, or join the Discord server to discuss your idea!

Windows

  • AutoHotkey is a powerful scripting language for Windows. You can use it to run the kando command when you press a mouse button or to remap a mouse button to a keyboard shortcut which opens a Kando menu.
  • GestureSign allows opening a Kando menu with multi-touch taps and gestures on both touchpad and touchscreen.

macOS

  • Karabiner-Elements can be used to remap mouse buttons to keyboard shortcuts.
  • BetterTouchTool allows opening a Kando menu via touchpad gestures.
  • BetterMouse is a tool which allows you to remap mouse buttons to keyboard shortcuts.

Linux

  • Input Remapper is a tool which allows you to remap mouse buttons to keyboard shortcuts. It works both on X11 and Wayland.
  • Touchegg is a multitouch gesture recognizer for Linux. You can use it to open a Kando menu with touchpad gestures. It only works on X11.
  • KDE Plasma comes with built-in support for remapping mouse buttons to keyboard shortcuts. You can find this feature in the system settings under "System Settings" / "Mouse & Touchpad" / "Add Binding".
  • There's a Configurable Button widget for KDE Plasma which allows running kando --menu "menu name" when clicked.
  • On GNOME Shell, you can use the CHC-E (Custom Hot Corners - Extended) extension to run arbitrary commands when you move your mouse to a corner of the screen.

⌨️ Menu Shortcuts vs. Simulated Hotkeys

With Kando, you can bind a menu to a keyboard shortcut and use menu items to simulate keyboard hotkeys or macros. This is a bit confusing as all are configured similarly, but use different formats.

Below is the configuration of a menu bound to Ctrl+V and a menu item simulating Ctrl+V. As you can see, the format for the key combination is different.

Menu-Shortcut Configuration Hotkey-Item Configuration
shortcut hotkey

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 and macro 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 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: Command Cmd Control Ctrl CommandOrControl CmdOrCtrl Alt Option AltGr Shift Super Meta

Available Key Names: 0-9 A-Z F1-F24 ) ! @ # $ % ^ & * ( : ; ' + = < , _ - > . ? / ~ ` { ] [ | \ } " Plus Space Tab Capslock Numlock Scrolllock Backspace Delete Insert Return Enter Up Down Left Right Home End PageUp PageDown Escape Esc VolumeUp VolumeDown VolumeMute MediaNextTrack MediaPreviousTrack MediaStop MediaPlayPause PrintScreen num0-num9 numdec numadd numsub nummult numdiv

Valid Simulated Hotkeys (using key codes)

Macro items simulate keyboard hotkeys by sending key codes. Below is a list of all available 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: AltLeft AltRight ControlLeft ControlRight MetaLeft MetaRight ShiftLeft ShiftRight

Available Non-Modifier Key Codes: Again ArrowDown ArrowLeft ArrowRight ArrowUp AudioVolumeDown AudioVolumeMute AudioVolumeUp Backquote Backslash Backspace BracketLeft BracketRight BrowserBack BrowserFavorites BrowserForward BrowserHome BrowserRefresh BrowserSearch BrowserStop CapsLock Comma ContextMenu Convert Copy Cut Delete Digit0-Digit9 Eject End Enter Equal Escape F1-F24 Find Help Home Insert IntlBackslash IntlRo IntlYen KanaMode KeyA-KeyZ Lang1-Lang5 LaunchApp1 LaunchApp2 LaunchMail MediaPlayPause MediaSelect MediaStop MediaTrackNext MediaTrackPrevious Minus NonConvert NumLock Numpad0-Numpad9 NumpadAdd NumpadComma NumpadDecimal NumpadDivide NumpadEnter NumpadEqual NumpadMultiply NumpadParenLeft NumpadParenRight NumpadSubtract Open PageDown PageUp Paste Pause Period Power PrintScreen Quote ScrollLock Select Semicolon Slash Sleep Space Tab Undo WakeUp

Getting Started Index Config Files