= 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
** https://github.com/jtroo/kanata/issues/240

== Windows 10+11 LLHOOK

* Mouse inputs cannot be used for processing or remapping
** https://github.com/jtroo/kanata/issues/108
** https://github.com/jtroo/kanata/issues/170
* Some input key combinations (e.g. Win+L) cannot be intercepted before
  running their default action
** https://github.com/jtroo/kanata/issues/192
** https://github.com/jtroo/kanata/discussions/428
* OS-level key remapping behaves differently vs. Linux or Interception
** Does not affect winiov2 variant
** https://github.com/jtroo/kanata/issues/152
* Certain applications that also use the LLHOOK mechanism may not behave correctly
** https://github.com/jtroo/kanata/issues/55
** https://github.com/jtroo/kanata/issues/250
** https://github.com/jtroo/kanata/issues/430
** https://github.com/espanso/espanso/issues/1488
* AltGr 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
** https://github.com/jtroo/kanata/issues/78
** https://github.com/jtroo/kanata/issues/667
** Workaround: use the correct https://github.com/jtroo/kanata/discussions/354[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
** https://github.com/jtroo/kanata/issues/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
** https://github.com/oblitum/Interception/issues/25
* Some less-frequently used keys are not supported or handled correctly
** https://github.com/jtroo/kanata/issues/127
** https://github.com/jtroo/kanata/issues/164
** https://github.com/jtroo/kanata/issues/425
** https://github.com/jtroo/kanata/issues/532

== Linux

* Key repeats can occur when they normally wouldn't in some cases
** https://github.com/jtroo/kanata/discussions/422
** https://github.com/jtroo/kanata/issues/450
* Unicode support has limitations, using xkb is a more consistent solution
** https://github.com/jtroo/kanata/discussions/703
* Key actions can behave incorrectly due to the rapidity of key events
** https://github.com/jtroo/kanata/discussions/733
** https://github.com/jtroo/kanata/issues/740
** adjusting https://github.com/jtroo/kanata/blob/main/docs/config.adoc#rapid-event-delay[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
link:../src/kanata/mod.rs[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