kanata-tray

kanata-tray

A simple wrapper for kanata to control it from tray icon. Works on Windows, Linux and macOS.

Features

• Tray icon with buttons for starting/stopping kanata
• Easy switching between multiple kanata configurations and versions.
• Customizable displayed tray icon when kanata changes layers.
• Works out-of-the box with no configuration, but can be configured with toml file.

Configuration

Default config file will be autogenerated for you on the first run. You can access it from from: Click Tray Icon > Configure.

Config file name is kanata-tray.toml.

The config folder location:

• Linux ~/.config/kanata-tray.
• Windows C:\Users\<YourUsername>\AppData\Roaming\kanata-tray
• macOS $HOME/Library/Application\ Support/kanata-tray

Alternatively, you can place your config file in the same folder as kanata-tray executable, and it will be have higher priority than the global config in user folder.

Examples

An example of customized configuration file:

'$schema' = 'https://raw.githubusercontent.com/rszyma/kanata-tray/main/doc/config_schema.json'

[general]
allow_concurrent_presets = false

[defaults]
kanata_executable = '~/bin/kanata' # if empty or omitted, system $PATH will be searched.
kanata_config = '' # if empty or not omitted, kanata default config locations will be used.
tcp_port = 5829 # if not specified, defaults to 5829

[defaults.layer_icons]
mouse = 'mouse.png' 
qwerty = 'qwerty.ico'
'*' = 'other_layers.ico'

[presets.'main cfg']
kanata_config = '~/.config/kanata/test.kbd'
autorun = true
# kanata_executable = ''
# layer_icons = {  }
# tcp_port = 1234

[presets.'test cfg']
kanata_config = '~/.config/kanata/test.kbd'

Explanation

presets - a config item, that adds an entry to tray menu. Each preset can have different settings for running kanata with: kanata_config, kanata_executable, autorun, layer_icons, tcp_port.

preset.autorun - when set to true, preset will run at kanata-tray startup.

preset.layer_icons - maps kanata layer names to custom icons. Custom icons should be placed in icons folder in config directory, next to kanata-tray.toml. Accepted icon types on Linux are .ico, .png, .jpg; on Windows only .ico is supported. You can assign an icon to special identifier '*' to change icon for other layers not specified in [layer_icons].

defaults - a config item, that allows to overwrite default values for all presets. It accepts same configuration options that presets do.

general.allow_concurrent_presets - when enabled, allows running multiple presets at the same time. When disabled, switching presets will stop currently running preset (if any). Disabled by default.

Other notes:

• You can use ~ in paths to substitute to your "home" directory.
• On Windows: make sure to surround paths with single-quotes ' instead of double-quotes, otherwise paths will not work (because \ would be treated as escape character).

Config completion in editors

In VSCode to get editor support for your kanata-tray config, install Even Better TOML extension and the following line at the top of your kanata-tray.toml file.

"$schema" = "https://raw.githubusercontent.com/rszyma/kanata-tray/main/doc/config_schema.json"

Supported Kanata Versions

Minimal supported version of kanata is v1.6.0.

More specifically, builds after commit 010338b (because it fixed an issue with TCP server)

Linux Dependencies

For Linux, make sure to install required packages first:

Arch:

pacman -S libayatana-appindicator

also if you want to build from source:

pacman -S base-devel gtk3 go just

Ubuntu:

sudo apt-get install libayatana-appindicator3-dev 

also if you want to build from source:

sudo apt-get install gcc libgtk-3-dev golang just

OpenSUSE Tumbleweed:

sudo zypper in libayatana-appindicator3-devel

Installation

Prebuild binaries for Windows and Linux: releases page

To build from source see recipes in justfile.