README.keyboard-layout-handling

Information on keyboard layouts for developers
==============================================

DOSBox-X is not compatible with keyboard layouts it's not prepared for.

DOSBox-X was developed around the US keyboard layout like DOSBox, mainly
due to limitations around the SDL1 library. SDL is responsible for input
handling, and SDL1 in particular only supports US keyboards.

The SDL1 library used in this source tree, unlike the official library,
does not attempt to hack around the issue by forcing Windows to load
the US keyboard layout for itself.

This document serves as a guide to begin modifying the source code in
this project to add support for your keyboard layout.

You can also find a list of supported keyboard layouts and further details
about keyboard layouts and other regional information in the DOSBox-X Wiki:
https://dosbox-x.com/wiki

Below is the source code that handles the keyboard layouts.

VK_* mapping in SDL1 (Windows):
- vs/sdl/src/video/windib/SDL_dibevents.c: DIB_InitOSKeymapPriv()

DOSBox-X keyboard layout enum:
- include/keymap.h (DKM_*) constants
- src/gui/sdlmain.cpp KeyboardLayoutDetect(), DKM_to_string(), DKM_to_descriptive_string()
- src/gui/sdlmain_linux.cpp (if working on Linux)

You may want to familiarize yourself with the Windows LCID for the locale
you'd like to add, as well as the VK_* scan codes generated by the keyboard
for that locale, so that SDL1 mapping can be updated properly.

In Linux, you may want to examine the X11 server keymap table and mod map
table and look at the X11 codes visible in the mapper to determine how
to add support.

The SDL1 library in Windows fills a fixed array used to map VK_* keyboard
codes to SDLK_* scan codes. Filling in the correct SDLK_* values given the
current keyboard locale is an important first step in getting your keyboard
layout to work.

The general rule is to try to pick the SDLK_* code according to the unshifted
unmodded character it would type. On US keyboards for example, the '1' key
enters '1' unshifted and '!' shifted.

If there is no SDLK_* code for the key, modify the SDL1 header where the
SDLK_* enumeration exists, locate the WORLD key enumerations and pick one
not yet already aliased, and define an alias for the new key, then return
that.

It is important for clean DOSBox-X development that DOSBox-X not have to
examine the keyboard locale within itself the meaning of the WORLD code,
and that it can go by the new aliases of the WORLD codes to know what
foreign key to match by.

Example: WORLD_11 and WORLD_21 redefined to represent the Yen and Ro keys
         on Japanese keyboards (see SDL_keysym.h in this source tree).
         Those WORLD code are to be used ONLY for those keys, and not
         anything else!

NOTE:
- To assist with scan codes and keyboard input, the mapper interface will
  show as much extra information as practical on keyboard input.

  Windows builds will show the VK_* code.

  Linux builds will show the X11 keyboard code.

  This information should assist with adding additional keyboard layouts.