| 1 |
Information on keyboard layouts for developers |
| 2 |
============================================== |
| 3 |
|
| 4 |
DOSBox-X is not compatible with keyboard layouts it's not prepared for. |
| 5 |
|
| 6 |
DOSBox-X was developed around the US keyboard layout like DOSBox, mainly |
| 7 |
due to limitations around the SDL1 library. SDL is responsible for input |
| 8 |
handling, and SDL1 in particular only supports US keyboards. |
| 9 |
|
| 10 |
The SDL1 library used in this source tree, unlike the official library, |
| 11 |
does not attempt to hack around the issue by forcing Windows to load |
| 12 |
the US keyboard layout for itself. |
| 13 |
|
| 14 |
This document serves as a guide to begin modifying the source code in |
| 15 |
this project to add support for your keyboard layout. |
| 16 |
|
| 17 |
You can also find a list of supported keyboard layouts and further details |
| 18 |
about keyboard layouts and other regional information in the DOSBox-X Wiki: |
| 19 |
https://dosbox-x.com/wiki |
| 20 |
|
| 21 |
Below is the source code that handles the keyboard layouts. |
| 22 |
|
| 23 |
VK_* mapping in SDL1 (Windows): |
| 24 |
- vs/sdl/src/video/windib/SDL_dibevents.c: DIB_InitOSKeymapPriv() |
| 25 |
|
| 26 |
DOSBox-X keyboard layout enum: |
| 27 |
- include/keymap.h (DKM_*) constants |
| 28 |
- src/gui/sdlmain.cpp KeyboardLayoutDetect(), DKM_to_string(), DKM_to_descriptive_string() |
| 29 |
- src/gui/sdlmain_linux.cpp (if working on Linux) |
| 30 |
|
| 31 |
You may want to familiarize yourself with the Windows LCID for the locale |
| 32 |
you'd like to add, as well as the VK_* scan codes generated by the keyboard |
| 33 |
for that locale, so that SDL1 mapping can be updated properly. |
| 34 |
|
| 35 |
In Linux, you may want to examine the X11 server keymap table and mod map |
| 36 |
table and look at the X11 codes visible in the mapper to determine how |
| 37 |
to add support. |
| 38 |
|
| 39 |
The SDL1 library in Windows fills a fixed array used to map VK_* keyboard |
| 40 |
codes to SDLK_* scan codes. Filling in the correct SDLK_* values given the |
| 41 |
current keyboard locale is an important first step in getting your keyboard |
| 42 |
layout to work. |
| 43 |
|
| 44 |
The general rule is to try to pick the SDLK_* code according to the unshifted |
| 45 |
unmodded character it would type. On US keyboards for example, the '1' key |
| 46 |
enters '1' unshifted and '!' shifted. |
| 47 |
|
| 48 |
If there is no SDLK_* code for the key, modify the SDL1 header where the |
| 49 |
SDLK_* enumeration exists, locate the WORLD key enumerations and pick one |
| 50 |
not yet already aliased, and define an alias for the new key, then return |
| 51 |
that. |
| 52 |
|
| 53 |
It is important for clean DOSBox-X development that DOSBox-X not have to |
| 54 |
examine the keyboard locale within itself the meaning of the WORLD code, |
| 55 |
and that it can go by the new aliases of the WORLD codes to know what |
| 56 |
foreign key to match by. |
| 57 |
|
| 58 |
Example: WORLD_11 and WORLD_21 redefined to represent the Yen and Ro keys |
| 59 |
on Japanese keyboards (see SDL_keysym.h in this source tree). |
| 60 |
Those WORLD code are to be used ONLY for those keys, and not |
| 61 |
anything else! |
| 62 |
|
| 63 |
NOTE: |
| 64 |
- To assist with scan codes and keyboard input, the mapper interface will |
| 65 |
show as much extra information as practical on keyboard input. |
| 66 |
|
| 67 |
Windows builds will show the VK_* code. |
| 68 |
|
| 69 |
Linux builds will show the X11 keyboard code. |
| 70 |
|
| 71 |
This information should assist with adding additional keyboard layouts. |