doc/keyboard-test.txt

Test protocol for keyboard handling
===================================

Platform specific tests/issues are marked with [].

These tests are primarily about what is sent over the protocol and some
may be difficult or impossible to test using normal applications. One
such case is that xev will see fake KeyRelease events on key repeat,
even when no such events were sent by the client. In these cases you
can turn on debug logging in either the client or the server by
specifying "-Log *:stderr:100".

We currently have a limitation in Xvnc where it can run out of symbols,
resulting in nothing being sent to the applications. Just run setxkbmap
with any layout to reset the symbol table.

Client (classic, non-raw, mode)
-------------------------------

- Normal symbols:

  - ASCII characters
  - Latin 1 character
  - Unicode BMP characters
  - Unicode non-BMP characters (does any layout actually have these?)

- Dead keys:

  These are not available on a single layout, so you need to switch to
  test everything. The useful layouts also differ per platform:

    X11: US International for most, Greek for some specific diacretics
    Win: US International, Czech, Greek Polytonic, Vietnamese
    OS X: ABC Extended (FIXME: lots of broken keys),
          Greek (FIXME: cannot be used with TigerVNC)

  - Grave
  - Acute
  - Circumflex
  - Tilde
  - Macron (FIXME: broken on Win)
  - Breve
  - Dot above
  - Dot below
  - Diaeresis
  - Ring above
  - Double acute
  - Caron
  - Cedilla
  - Ogonek
  - Ypogegrammeni (iota below) (FIXME: broken on Win)
  - Dialytika tonos [Win] (Diaresis on X11, and maybe OS X?)
  - Comma above (FIXME: broken on Win)
  - Reversed comma above (FIXME: broken on Win)
  - Horn [X11?]
  - Hook above [Win?]
  - Hook below [X11?, Win?]
  - Dakuten (Katakana voiced mark) (Only Input Methods layouts?)
  - Handakuten (Katakana semi-voiced mark) (Only Input Methods layouts?)
  - FIXME: Many more that we currently probably don't support

  - No composition on client

- Modifiers:

  X11: You can usually toggle Hyper/Super and Compose/Scroll_Lock using
       XKB options.

  - CapsLock, NumLock
  - Shift, Ctrl
  - Alt, AltGr, Super [Win, X11]
  - Ctrl+AltGr [Win]
  - Meta [X11]
  - Left/right identification (FIXME: broken release for Shift on Win)
  - CmdL => AltL, CmdR => SuperL, AltL => ModeSwitch, AltR => Level3Shift [OS X]
  - Hyper sends Super [X11]

  - CapsLock, Shift and AltGr affect symbol lookup
  - Ctrl does not affect symbol lookup
  - Ctrl+Alt+<ANY> sends the same symbol as <ANY>
  - "Shift press, A press, Shift release, A release" should not send "a release"

- Numpad:

  - NumLock affects symbol lookup [Win, X11]
  - Numpad specific symbols are sent
  - Decimal key should send Decimal for layouts with . as a symbol, and
    Separator for layouts with , as a symbol
  - Shift inverts NumLock behaviour [X11]
  - Shift turns NumLock off, but not on [Win] (FIXME: fake Shifts also sent)

- Multimedia keys:

  OS X: FIXME: all broken

  - Back, Forward, Refresh, Stop
  - HomePage, Search, Favourites (FIXME: broken on Win)
  - Mail, Calculator
  - Volume up, down, mute
  - Media next, previous, stop, play
  - Sleep (FIXME: broken on Win)
  - FIXME: probably more keys exist

- Non-character keys:

  - F1-F24 (FIXME: F14-F15 broken on OS X)
  - Tab, Space, Backspace, Return, Esc
  - LeftTab sends Tab [X11]
  - PrntScrn, ScrollLock, Pause [X11, Win]
  - Help [X11?, OS X]
  - Insert [X11, Win]
  - Delete, Home, End, PageUp, PageDown
  - Arrow keys
  - Menu
  - Alt+PrntScrn sends Sys_Req [Win]

- French layout (AZERTY and inverted shift behaviour for many keys)

- Local layout changes are respected

Client (raw mode)
-----------------

- All physical keys (modifiers or type of symbol shouldn't matter)

  - Normal keys
  - Dead keys
  - Numpad
  - Multimedia keys
  - Non-character keys

Client (both modes)
-------------------

- Key repeat should not send repeated release events

- Keys are released on loss of focus

- Local input methods are disabled/enabled with focus

- System keys should be grabbed in full screen (FIXME: lots missing on Win)

  The exact keys depends on the system and configuration, but it
  is usually variants of these:

  - Alt+Tab
  - Super (and Super+other)
  - Multimedia keys
  - Ctrl+Alt+Delete
  - Ctrl+Esc
  - F8-F12

- Lock key states:

  - Adjusted on server when connecting
  - Adjusted on server when regaining focus
  - Server changes are honored when focused
  - Server changes are not honored when not focused

  - CapsLock
  - NumLock (hidden state on macOS)
  - ScollLock* [X11, Win]

  * Usually needs to be enabled with: xmodmap -e "add mod3 = Scroll_Lock"

- Virtual keyboard (as much of the above as is possible)

Server
------

- Fake key events

  An extra press or release should be added before the real key press
  in order to get the correct state to get the desired symbol. A second
  fake event should be added after the real key press to restore state.
  No extra events should be added for a key release.

  Possible fake keys:

  - Shift
  - AltGr

  - Shift+Tab bypasses this and never fake releases Shift

- Alternative keys

  A semantically equivalent key is sent when the desired key cannot be
  reached in the current keyboard state:

  - Left modifier <=> Right modifier (e.g. Alt_R for Alt_L)
  - Keypad key <=> Standard key
  - ISO_Level3_Shift <=> Mode_Switch

- Meta for Shift+Alt (if server keymap agrees)

- Lock key heuristics (for clients without lock key extension)

  - CapsLock is corrected when A-Z or a-z are pressed
  - CapsLock is corrected when Shift and A-Z or a-z are pressed*
  - NumLock is corrected when 0-9 on the keypad are pressed

  * Gives incorrect behaviour if the client doesn't have "Shift cancels
    CapsLock behaviour", e.g. macOS