Debian Codegraph @

README.keyboard-layout-handling

raw
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.