platform-known-issues.adoc

Platform-dependent known issues

Preface

This document contains a list of known issues which are unique to a given platform. The platform supported by the core maintainer (jtroo) are Windows 11 and Linux. Windows 10 is expected to work fine, but as Windows 10 end-of-support is approaching in 2025, jtroo no longer has any devices with it installed.

On Windows, there are two backing mechanisms that can be used for keyboard input/output and they have different issues. These will be differentiated by the words "LLHOOK" and "Interception", which map to the binaries kanata.exe and kanata_wintercept.exe respectively.

Windows 11 LLHOOK

• The emoji picker does not work properly

  • #240

Windows 10+11 LLHOOK

• Mouse inputs cannot be used for processing or remapping

  • #108

  • #170

• Some input key combinations (e.g. Win+L) cannot be intercepted before running their default action

  • #192

  • #428

• OS-level key remapping behaves differently vs. Linux or Interception

  • Does not affect winiov2 variant

  • #152

• Certain applications that also use the LLHOOK mechanism may not behave correctly

  • #55

  • #250

  • #430

  • espanso/espanso#1488

• AltGr / ralt / Right Alt can misbehave

  • https://github.com/jtroo/kanata/blob/main/docs/config.adoc#windows-only-windows-altgr

• NumLock state can mess with arrow keys in unexpected ways

  • Does not affect winiov2 variant

  • #78

  • #667

  • Workaround: use the correct numlock state

• Without process-unmapped-keys yes, using arrow keys without also having the shift keys in defsrc will break shift highlighting

  • Does not affect winiov2 variant

  • #858

  • Workaround: add shift keys to defsrc or use process-unmapped-keys yes in defcfg

Windows 10+11 Interception

• Sleeping your system or unplugging/replugging devices enough times causes inputs to stop working

  • oblitum/Interception#25

• Some less-frequently used keys are not supported or handled correctly

  • #127

  • #164

  • #425

  • #532

Linux

• Key repeats can occur when they normally wouldn’t in some cases

  • #422

  • #450

• Unicode support has limitations, using xkb is a more consistent solution

  • #703

• Key actions can behave incorrectly due to the rapidity of key events

  • #733

  • #740

  • adjusting rapid-event-delay can potentially be a workaround

• Macro keys on certain gaming keyboards might stop being processed

  • Context: search for POTENTIAL PROBLEM - G-keys in the code.

  • Workaround: leave process-unmapped-keys disabled and explicitly map keys in defsrc instead

MacOS

• Only left, right, and middle mouse buttons are implemented for clicking

• Mouse input processing is not implemented