Keymaps

this page is under construction (this will not get implemented before 2.4 is out, because of breakage) Gpz 22:39, 24 June 2012 (UTC)

Reason for this page: handling auf keymaps is currently a bit messy in some places, and seems unnecessary complex to maintain (eg hardcoded filenames in archdep code dont make updating a lot easier). The idea is to handle it at one central place, with a minimum set of resources which are valid for all emulators. This will make both adding new keyboard types and updating the respective ports easier in the future. At the same time a somewhat more same default behaviour that always works "as expected" automatically will be achived, based on the general assumption that the casual user never even wants to be bothered with setting up keymaps at all :)

considerations

• host (pc) keyboards have a "machine" and "locale" type. the "machine" type is defined by the port (windows, x11, sdl etc) and the "locale" type by what type of keyboard the user has connected (we currently have different maps for US and DE keyboards)

• emulated keyboards have a "positional" and a "symbolic" type. the former referring to the actual hardware (keyboard matrix and key positions) and the later referring to what is actually written on the keycaps. (for example the localized c128 keyboards would all have the same "positional" type, but different "symbolic" types.

• we support two fundamentally different type of keyboard mappings, "symbolic" and "positional".

implementation

resources

• "KeymapIndex" - (integer) selects active keymap (default:0) (0: symbolic, 1: positional, 2: user defined symbolic, 3: user defined positional)
• "KeymapSymFile" - (string) name of the keymap to use for symbolic mapping (default:empty) (automatically set, see below)
• "KeymapPosFile" - (string) name of the keymap to use for positional mapping (default:empty) (automatically set, see below)
• "KeymapUserSymFile" - (string) name of user defined symbolic keymap (default:empty)
• "KeymapUserPosFile" - (string) name of user defined positional keymap (default:empty)

• "KeyboardType" - (Integer) emulated keyboard type. (default:0) (C128 0: International, 1: Finnish,French, 3: German, 4: Italian, 5: Norwegian, 6: Swedish - PET: 0 "bkuk" 1: "gkuk" 2: "bkde" - others: 0)

• "KeyboardMapping" - (integer) host keyboard type (default:0) (0: standard US keyboard, 1: standard german keyboard)

defaults

• when the emulator starts the first time and finds either "KeymapSymFile" or "KeymapPosFile" empty, an archdep function should be called which returns the type of keyboard connected, "KeyboardMapping" is initialized with that value, and the resulting keymap loaded

loading the keymap

a central function which is called if any of "KeymapIndex", "KeyboardType", "KeyboardMapping" changed handles loading the new keymap.

• if "KeymapIndex" is not 0 or 1, then load the respective user keymap and skip any further automatic actions

• else try loading a keymap with the filename constructed as below.

• if that fails, find a proper fallback:
  • if a positional map is not available, not much can be done other than switching to symbolic mapping instead, so do that...
  • remove the <mapping> part from the filename, ie try to load <port>_<type>_sym.vkm (for ports that have more than one emulated keyboard type, this MUST exist)
  • as last resort, always use <port>_sym.vkm (which MUST exist)

• generally after loading update "KeymapIndex", "KeyboardType", "KeyboardMapping" to reflect the keymap that was actually loaded

constructing the filename

the filename of a keymap will be constructed according to this scheme:

<port>_<type>_<idx>_<mapping>.vkm

where:

• <port> is a string constant defined in archdep code (eg "x11", "sdl", "win" etc)
• <type> is a string returned by a machine specific function. this function should return an empty string if "KeyboardType" is 0 (else eg "bkuk", "gkuk", "bkde" etc)
• <idx> is a string derived from "KeymapIndex", where 0 is "sym" and 1 is "pos"
• <mapping> is a string derived from "KeyboardMapping", where 0 is an empty string and 1 is "de" (... 2: "fi" 3: "se" etc if needed)

(this should in many cases not even require renaming any .vkm files)

---

migrating the code

menus

after the change, all user interfaces should have the following options:

• "set keymapping" - select between "symbolic", "positional", "symbolic (user)", "positional (user) and change "KeymapIndex" accordingly
• "set keyboard layout" - select between "us" and "de" and change "KeyboardMapping" accordingly

• "define user define symbolic keymap" - set up "KeymapUserSymFile"
• "define user define positional keymap" - set up "KeymapUserPosFile"

additionally for machines which have more than one type of keyboard:

• "set keyboard type" - select emulated keyboard (C128 0: International, 1: Finnish,French, 3: German, 4: Italian, 5: Norwegian, 6: Swedish - PET: 0 "bkuk" 1: "gkuk" 2: "bkde" - others: 0) and set up "KeyboardType" accordingly

change

• option -symkeymap <name> - set "KeymapUserSymFile" to <name> and set "KeymapIndex" to 2
• option -poskeymap <name> - set "KeymapUserPosFile" to <name> and set "KeymapIndex" to 3

remove

resources: KeymapSymDeFile, KeymapBusinessUKSymFile, KeymapBusinessUKPosFile, KeymapGraphicsSymFile, KeymapGraphicsPosFile, KeymapBusinessDESymFile, KeymapBusinessDEPosFile

options: -symdekeymap, -buksymkeymap, -bukposkeymap, -grsymkeymap, -grposkeymap, -bdesymkeymap, -bdeposkeymap