Keymaps

NOTE: i am working at this locally atm and updating the page while doing so. will commit when at least unix/sdl/win32 are working ok Gpz (talk) 01:29, 9 April 2015 (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 sane 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, DE, UK, FI, NO, DA etc... 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. fortunately the total combinations of these is small, so we can define one type per such combination.

• 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:automatically set, see below)
• "KeymapPosFile" - (string) name of the keymap to use for positional mapping (default:automatically set, see below)
• "KeymapUserSymFile" - (string) name of user defined symbolic keymap (default: "<port>_sym.vkm")
• "KeymapUserPosFile" - (string) name of user defined positional keymap (default: "<port>_pos.vkm")

• "KeyboardType" - (Integer) emulated keyboard type. (default:0)
  • C128 0: International, 1: Finnish,French, 3: German, 4: Italian, 5: Norwegian, 6: Swedish
  • PET: (pet-resources.h) 0 "buus" 1: "buuk" 2: "bude" 3: "bujp" 4: "grus"
  • others: 0

This resource will get updated when the machine model changes, and can be individually updated in the user interface.

• "KeyboardMapping" - (integer) host keyboard type (default:0)
  • 0 "" (us mapping)
  • 1 "uk"
  • 2 "de"
  • 3 "da"
  • 4 "no"
  • 5 "fi"
  • 6 "gr"
  • 7 "it"

this list may be expanded as needed

command line options

• "-keymap" - sets "KeymapIndex"
• "-symkeymap" sets "KeymapUserSymFile" directly
• "-poskeymap" sets "KeymapUserPosFile" directly

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 -> src/arch/<port>/archdep*: kbd_arch_get_host_mapping()

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" and "KeymapSymFile"/"KeymapPosFile" to reflect the keymap that was actually loaded

constructing the filename

generally 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) -> KBD_PORT_PREFIX in src/arch/<port>/kbd.h
• <type> is a string returned by a machine specific function. this function should return NULL if the type string would be empty (the machine has no keyboard types) else eg "bkuk", "gkuk", "bkde" etc. (the returned string should be no more than 4 characters) -> machine_get_keyboard_type_name()
• <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)

• a solution must be found for targets that only support 8.3 filenames, sth like

• • if "<type><idx><mapping>" is 4 characters (or less), use <port>_<type><idx><mapping>.vkm
    • else:
      • get short <port> string from constant defined in archdep code (max 2 characters, eg "md" for msdos)
      • get short <type> string from a machine specific function. this function should return an empty string if "KeyboardType" is 0 (else eg "buk", "guk", "bde" etc) (the returned string should be no more than 3 characters)
      • <idx> is a string derived from "KeymapIndex", where 0 is "s" and 1 is "p"
      • use <port><type><idx><mapping>.vkm

---

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-defined symbolic keymap" - set up "KeymapUserSymFile"
• "define user-defined 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>
• option -poskeymap <name> - set "KeymapUserPosFile" to <name>

remove

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

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