Skip to content

Latest commit

 

History

History
234 lines (199 loc) · 10.7 KB

config-files.md

File metadata and controls

234 lines (199 loc) · 10.7 KB

The Config Files

All settings are stored in two configuration files JSON files which you can also edit manually. config.json stores the general configuration of the application and menus.json stores the configuration of the individual menus. Depending on your platform, the configuration files are located in different directories:

  • Windows: %appdata%\kando\
  • macOS: ~/Library/Application Support/kando/
  • Linux: ~/.config/kando/

📝 JSON Format: Both configuration files are JSON files. You can edit them with any text editor.

🔥 Hot Reloading: Whenever you save a file, Kando will automatically reload the configuration.

✅ Validation: Kando will validate the configuration files and print errors to the console if it finds any. In this case, the configuration will not be reloaded. If a configuration file is invalid at startup, Kando will use the default configuration instead.

The General Configuration: config.json

This file contains the general configuration of Kando.

Property Default Value Description
menuTheme "default" The directory name of the menu theme to use. Kando will first look for a directory with this name in the menu-themes subdirectory of the config directory. If it does not find one, it will look for a directory with this name in .webpack/renderer/assets/menu-themes in Kando's installation directory.
darkMenuTheme "default" The name of the theme which should be used if the system is in dark mode.
menuThemeColors {} A map of accent color overrides for each theme. A color override for the "default" theme could look like this: { "default": {"background-color": "#RRGGBB"}}.
darkMenuThemeColors {} Same as above, however this one will be used if the system is in dark mode.
enableDarkModeForMenuThemes false Whether Kando should use the dark menu theme if the system is in dark mode.
sidebarVisible true Whether the left sidebar is currently visible.
zoomFactor 1.0 The zoom factor of the menu. This can be used to scale the menu on high-resolution screens.
enableVersionCheck true If set to true, Kando will check for new version regularly, and show a notification if a new version is available.

The Menu Configuration: menus.json

This file contains the configuration of the individual menus. There are two top-level JSON objects: menus contains a list of Menu Descriptions and templates contains a list of Menu Descriptions or Menu Item Descriptions.

{
  "menus": [
    {
      // First Menu Description.
      // ...
    },
    {
      // Second Menu Description.
      // ...
    },
    // ...
  ],
  "templates": [
    // Can contain Menu Descriptions and Menu Item Descriptions.
  ]
}

Tip

You can have a look at a the example menu configurations here!

Menu Descriptions

The items in the menus list are called menu descriptions. 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. See 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".
root 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.
conditions {} A dictionary of conditions which must be met for the menu to be shown. See below for details.

Menu Conditions

The conditions property of a menu description can contain a dictionary of conditions. Only if all conditions are met, the menu will be shown.

Property Default Value Description
appName "" The name of the application which must be focused for the menu to be shown. If it is a simple string, the condition is met if the name of the focused application contains the given string (case-insensitive). If the string starts with a /, it is interpreted as a regular expression.
windowName "" The name of the window which must be focused for the menu to be shown. It is interpreted in the same way as appName.
screenArea {} A dictionary with the optional properties xMin, xMax, yMin, and yMax. The menu will only be shown if the mouse cursor is within the given screen area. The values are given in pixels and are relative to the top-left corner of the screen. If a value is not given, the area is unbounded in this direction.

Menu Item Descriptions

The layout of the menu is described by a tree of menu items. Each menu item is a JSON object with the following properties:

Property Default Value Description
name "undefined" The name of the menu item. This is shown in the center of the menu when the item is hovered. The name of the root item defines the name of the menu.
iconTheme "" This can either be one of the built-in icon themes ("material-symbols-rounded", "simple-icons", "simple-icons-colored", or "emoji") or a subdirectory of the icon-themes subdirectory in Kando's config directory. The built-in icon themes use icons from Google's Material Symbols or Simple Icons respectively.
icon "" The name of the icon from the given icon theme or an emoji like "🚀".
angle auto If given, this defines the angle of the menu item in degrees. If this is not given, the angle is calculated automatically. 0° means that the item is at the top of the menu, 90° means that the item is on the right side of the menu, and so on. All sibling items are evenly distributed around the items with given angles.
type "submenu" The type of the menu item. There are several types available. See below for details.
data {} Depending on the type of the item, this can contain additional data. See below for details.
children [] If the menu item is a submenu, this contains a list of child items. See below for details.

Menu Item Types

For now, the type property of a menu item can be one of the following values. New types will be added in the future.

"submenu"

This is the default type. It is used to create a submenu. The children property of the menu item must contain a list of child items.

"command"

This type is used to execute a shell command. The data property of the menu item must contain a command property which contains the shell command to execute. The optional delayed property will ensure that the command is executed after the Kando window is closed. This can be useful if the command targets another window. For instance, this menu item will open Inkscape on Linux:

{
  "name": "Inkscape",
  "icon": "inkscape",
  "iconTheme": "simple-icons",
  "type": "command",
  "data": {
    "command": "/usr/bin/inkscape",
    "delayed": false
  }
}

"uri"

This type is used to open any kind of URI. The data property of the menu item must contain a uri property which contains the URI to open. For instance, this menu item will open GitHub in the default browser:

{
  "name": "GitHub",
  "icon": "github",
  "iconTheme": "simple-icons",
  "type": "uri",
  "data": {
    "uri": "https://github.com"
  }
}

"hotkey"

This type is used to simulate simple 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 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:

{
  "name": "Paste",
  "icon": "content_paste_go",
  "iconTheme": "material-symbols-rounded",
  "type": "hotkey",
  "data": {
    "hotkey": "ControlLeft+KeyV",
    "delayed": true
  }
}

"macro"

This type is used to simulate a more comples sequence of keyboard events. The data property of the menu item must contain a macro property which contains the sequence of key codes to simulate. See Menu Shortcuts vs. Simulated Hotkeys for details on key code format. The optional delayed property will ensure that the macro is simulated after the Kando window is closed. This can be used if the macro should be captured by another window. For instance, this menu item will type "Hi" on most keyboard layouts:

{
  "type": "macro",
  "data": {
    "macro": [
      {
        "type": "keyDown",
        "key": "ShiftLeft",
        "delay": 10
      },
      {
        "type": "keyDown",
        "key": "KeyH",
        "delay": 10
      },
      {
        "type": "keyUp",
        "key": "KeyH",
        "delay": 10
      },
      {
        "type": "keyUp",
        "key": "ShiftLeft",
        "delay": 10
      },
      {
        "type": "keyDown",
        "key": "KeyI",
        "delay": 10
      },
      {
        "type": "keyUp",
        "key": "KeyI",
        "delay": 10
      }
    ],
    "delayed": true
  },
  "name": "Hello World",
  "icon": "keyboard_keys",
  "iconTheme": "material-symbols-rounded"
}

Configuring Kando Index Creating Menu Themes