TABLE OF CONTENTS keymap.library/AskKeyMapDefault keymap.library/CloseKeyMapHandle keymap.library/KeyMapControlTagList keymap.library/MapANSI keymap.library/MapRawKey keymap.library/ObtainKeyMapInfoA keymap.library/ObtainRawKeyInfoA keymap.library/OpenKeyMapHandleA keymap.library/ReleaseKeyMapInfoA keymap.library/SetKeyMapDefault keymap.library/AskKeyMapDefault keymap.library/AskKeyMapDefault NAME AskKeyMapDefault -- Ask for a pointer to the current default keymap. (V36) SYNOPSIS struct KeyMap *keyMap = AskKeyMapDefault(); FUNCTION Return a pointer to the keymap used by the keymap library for MapRawKey and MapANSI when a keymap is not specified. RESULTS keyMap - a pointer to a keyMap structure. This key map is guaranteed to be permanently allocated: it will remain in memory untill the machine is reset. SEE ALSO libraries/keymap.h, SetKeyMapDefault(), console.device ...KEYMAP functions keymap.library/CloseKeyMapHandle keymap.library/CloseKeyMapHandle NAME CloseKeyMapHandle -- Close a keymap handle. (V50) SYNOPSIS VOID CloseKeyMapHandle(APTR handle); FUNCTION Close a keymap file obtained with OpenKeyMapHandleA() and return the resources to the system. After calling this function, all pointers obtained from ObtainKeyMapInfoA() are no longer valid. INPUTS handle - keymap handle obtained from OpenKeyMapHandleA(). A NULL handle has no effect. RESULTS none SEE ALSO OpenKeyMapHandleA(), ObtainKeyMapInfoA() keymap.library/KeyMapControlTagList keymap.library/KeyMapControlTagList NAME KeyMapControlTagList -- Set or obtain global keymap prefs. (V53.8) SYNOPSIS uint32 result = KayMapControlTagList(const struct TagItem *tags); uint32 result = KayMapControlTags(Tag tag1, ...); FUNCTION This function provides a single method for reading or setting various features available in keymap.library. This is the primary interface for keymap preferences tools, which use this function to implement the users prefered default settings. It is therefore recommended that applications use this function only to read what the user has chosen and not to flippantly override them. If you must change any values, read the previous setting and restore it after you have finished. You should never permanently change the users prefered settings without expressly having permission to do so. INPUTS tags - Tag list with additional parameters; see below. TAGS KMCTRL_SetAltAmigaSwap (BOOL) -- Sets whether the "Alt" and "Amiga" keys should be swapped or not. The "Amiga" keys are also known as the "Command" keys. Defaults to FALSE. KMCTRL_GetAltAmigaSwap (BOOL *) -- Gets whether the "Alt" and "Amiga" keys are swapped or not. RESULT result - Returns the number of tags successfully processed or zero on error. SEE ALSO libraries/keymap.h keymap.library/MapANSI keymap.library/MapANSI NAME MapANSI -- Encode an ANSI string into keycodes. (V36) SYNOPSIS int32 actual = MapANSI(CONST_STRPTR string, int32 count, STRPTR buffer, int32 length, const struct KeyMap *keyMap); FUNCTION This console function converts an ANSI byte string to the code/qualifier pairs of type IECLASS_RAWKEY that would generate the string and places those pairs in a buffer. A code/qualifier pair is a pair of bytes suitable for putting in the ie_Code and low byte of ie_Qualifier, and for subsequent events, shifted to the ie_Prev1DownCode/ ie_Prev1DownQual then ie_Prev2DownCode/ie_Prev2DownQual pairs for any dead or double dead key mapping. INPUTS string - the ANSI string to convert. count - the number of characters in the string. buffer - a byte buffer large enough to hold all anticipated code/qualifier pairs generated by this conversion. length - maximum anticipation, i.e. the buffer size in bytes divided by two (the size of the code/qualifier pair). keyMap - a KeyMap structure pointer, or null if the default key map is to be used. RESULT actual - the number of code/qualifier pairs in the buffer, or negative to describe an error (see below). EXAMPLE ... #include #define STIMSIZE 3 // two dead keys, one key TEXT rBuffer[STIMSIZE*2]; ... struct Library *KeymapBase; struct KeymapIFace *IKeymap = NULL; KeymapBase = IExec->OpenLibrary("keymap.library", 53); if (KeymapBase) { IKeymap = (struct KeymapIFace *) IExec->GetInterface(KeymapBase, "main", 1, NULL); } if (!KeymapBase || !IKeymap) { // Error handling and exit } ... event.ie_NextEvent = 0; event.ie_Class = IECLASS_RAWKEY; event.ie_SubClass = 0; // prove keymap code completeness and MapANSI reversibility for (code = 0; code < 256; code++) { buffer[0] = code; actual = IKeymap->MapANSI(buffer, 1, rBuffer, STIMSIZE, 0); r = rBuffer; event.ie_Prev2DownCode = 0x80; // Not 0 which may be a deadkey event.ie_Prev2DownQual = 0; event.ie_Prev1DownCode = 0x80; // Not 0 which may be a deadkey event.ie_Prev1DownQual = 0; switch (actual) { case -2: printf("MapANSI internal error"); goto reportChar; case -1: printf("MapANSI overflow error"); goto reportChar; case 0: printf("MapANSI ungeneratable code"); goto reportChar; case 3: event.ie_Prev2DownCode = *r++; event.ie_Prev2DownQual = *r++; // fall through case 2: event.ie_Prev1DownCode = *r++; event.ie_Prev1DownQual = *r++; // fall through case 1: event.ie_Code = *r++; event.ie_Qualifier = *r; actual = IKeymap->MapRawKey(&event, buffer, BUFFERLEN, 0); if ((actual != 1) || (buffer[0] != code)) { printf("MapANSI not reversible"); for (i = 0; i < actual; i++) ReportChar(buffer[i]); printf(" from"); reportChar: ReportChar(code); printf("\n"); } } } ... ERRORS if actual is 0, a character in the string was not generatable from the keyMap. if actual is -1, a buffer overflow condition was detected. if actual is -2, an internal error occurred (e.g. no memory) NOTE This function does not try to find rawkey combinations that include the CapsLock qualifier. Theoretically its possible that a character can only be typed with CapsLock on when using the text format keymap files introduced in V51, but such keymap files are considered to be broken. SEE ALSO devices/inputevent.h, libraries/keymap.h keymap.library/MapRawKey keymap.library/MapRawKey NAME MapRawKey -- Decode single raw key input event to an ANSI string. (V36) SYNOPSIS int16 actual = MapRawKey(const struct InputEvent *event, STRPTR buffer, int16 length, const struct KeyMap *keyMap); FUNCTION This console function converts input events of type IECLASS_RAWKEY to ANSI bytes, based on the keyMap, and places the result into the buffer. INPUTS event - an InputEvent structure pointer. The event list is not traversed. buffer - a byte buffer large enough to hold all anticipated characters generated by this conversion. length - maximum anticipation, i.e. the buffer size in bytes. keyMap - a KeyMap structure pointer, or null if the default key map is to be used. RESULT actual - the number of characters in the buffer, or -1 if a buffer overflow was about to occur. EXAMPLE ... struct Library *KeymapBase; struct KeymapIFace *IKeymap = NULL; #define BUFFERLEN 80 // length of longest expected mapping TEXT buffer[BUFFERLEN]; struct InputEvent ie; ... KeymapBase = IExec->OpenLibrary("keymap.library", 53); if (KeymapBase) { IKeymap = (struct KeymapIFace *) IExec->GetInterface(KeymapBase, "main", 1, NULL); } if (!KeymapBase || !IKeymap) { // Error handling and exit } ... ie.ie_Class = IECLASS_RAWKEY; ie.ie_SubClass = 0; for (;;) { IExec->WaitPort(window->UserPort); while ((im = (struct IntuiMessage *) IExec->GetMsg(window->UserPort)) != NULL) { switch (im->Class) { case IDCMP_RAWKEY: ie.ie_Code = im->Code; ie.ie_Qualifier = im->Qualifier; /* recover dead key codes & qualifiers */ ie.ie_EventAddress=(APTR *) *((ULONG *)im->IAddress); actual=IKeymap->MapRawKey(&ie, buffer, BUFFERLEN, 0); for (i = 0; i < actual; i++) ReportChar(buffer[i]); break; ... } ... } } ERRORS if actual is -1, a buffer overflow condition was detected. Not all of the characters in the buffer are valid. WARNING Do not preset ie_Prev1DownCode to 0. 0 is a valid keycode and you may get unexpected results with a keymap where keycode 0 is a deadkey when the current key is a deadable key. Use 0x80 as preset for ie_Prev1DownCode which stops scanning for previous deadkeys. NOTE With the text format keymap files introduced in V51, MapRawKey() shows correct behaviour when CapsLock is on and converts the typed character to uppercase. With old keymap files plus CapsLock plus Alt plus a key you get Shift-Alt-key even when its not the uppercase letter of Alt-key. In most cases an application should not be interested in the result of MapRawKey() when it knows in advance that the pressed key was a special key (which normally always maps to the same result). However, for applications which work with input streams which were generated by MapRawKey() and which cant know which rawkeys and qualifiers were pressed to generate this input stream, it follows a table which describes the ANSI sequences created by the "special" keys. The term in this table stands for the control sequence introducer, this can either be the character 0x9b or the sequence 0x1b, 0x5b ("["). By default MapRawKey() creates the one-byte variant, but your application should be prepared to handle the two-byte variant too, this may be required in future for support of UTF-8 keymaps, the 0x9b character conflicts with UTF-8 but [ does not. Pressed keys ANSI sequence generated by MapRawKey() --------------------------------------------------------------- Backspace 0x08 BS Tab 0x09 HT Shift-Tab Z Enter 0x0d CR Return 0x0d CR Ctrl-Return 0x0a LF Esc 0x1b ESC Alt-Esc CSI Del 0x7f DEL Insert 40~ (Missing on classic keyboard) Shift-Insert 50~ (Missing on classic keyboard) PageUp 41~ (Missing on classic keyboard) Shift-PageUp 51~ (Missing on classic keyboard) PageDown 42~ (Missing on classic keyboard) Shift-PageDown 52~ (Missing on classic keyboard) CrsrUp A Shift-CrsrUp T Alt-CrsrUp 3A Alt-Shift-CrsrUp 4A Ctrl-CrsrUp 5A Ctrl-Shift-CrsrUp 6A Ctrl-Alt-CrsrUp 7A Ctrl-Alt-Shift-CrsrUp 8A CrsrDown B Shift-CrsrDown S Alt-CrsrDown 3B Alt-Shift-CrsrDown 4B Ctrl-CrsrDown 5B Ctrl-Shift-CrsrDown 6B Ctrl-Alt-CrsrDown 7B Ctrl-Alt-Shift-CrsrDown 8B CrsrRight C Shift-CrsrRight @ Alt-CrsrRight 3C Alt-Shift-CrsrRight 4C Ctrl-CrsrRight 5C Ctrl-Shift-CrsrRight 6C Ctrl-Alt-CrsrRight 7C Ctrl-Alt-Shift-CrsrRight 8C CrsrLeft D Shift-CrsrLeft A Alt-CrsrLeft 3D Alt-Shift-CrsrLeft 4D Ctrl-CrsrLeft 5D Ctrl-Shift-CrsrLeft 6D Ctrl-Alt-CrsrLeft 7D Ctrl-Alt-Shift-CrsrLeft 8D F1 0~ Shift-F1 10~ Alt-F1 60~ Ctrl-F1 80~ F2 1~ Shift-F2 11~ Alt-F2 61~ Ctrl-F2 81~ F3 2~ Shift-F3 12~ Alt-F3 62~ Ctrl-F3 82~ F4 3~ Shift-F4 13~ Alt-F4 63~ Ctrl-F4 83~ F5 4~ Shift-F5 14~ Alt-F5 64~ Ctrl-F5 84~ F6 5~ Shift-F6 15~ Alt-F6 65~ Ctrl-F6 85~ F7 6~ Shift-F7 16~ Alt-F7 66~ Ctrl-F7 86~ F8 7~ Shift-F8 17~ Alt-F8 67~ Ctrl-F8 87~ F9 8~ Shift-F9 18~ Alt-F9 68~ Ctrl-F9 88~ F10 9~ Shift-F10 19~ Alt-F10 69~ Ctrl-F10 89~ F11 20~ (Missing on classic keyboard) Shift-F11 30~ (Missing on classic keyboard) Alt-F11 70~ (Missing on classic keyboard) Ctrl-F11 90~ (Missing on classic keyboard) F12 21~ (Missing on classic keyboard) Shift-F12 31~ (Missing on classic keyboard) Alt-F12 71~ (Missing on classic keyboard) Ctrl-F12 91~ (Missing on classic keyboard) Help ?~ PrintScreen 46~ (Missing on classic keyboard) Shift-PrintScreen 56~ (Missing on classic keyboard) Pause/Break 43~ (Missing on classic keyboard) Shift-Pause/Break 53~ (Missing on classic keyboard) Home 44~ (Missing on classic keyboard) Shift-Home 54~ (Missing on classic keyboard) End 45~ (Missing on classic keyboard) Shift-End 55~ (Missing on classic keyboard) SEE ALSO devices/inputevent.h, libraries/keymap.h keymap.library/ObtainKeyMapInfoA keymap.library/ObtainKeyMapInfoA NAME ObtainKeyMapInfoA -- Obtain info from a keymap handle. (V50) SYNOPSIS uint32 success = ObtainKeyMapInfoA(APTR handle, const struct TagItem *taglist); uint32 success = ObtainKeyMapInfo(APTR handle, Tag tag1, ...); FUNCTION Retrieve information from a keymap handle. This function was introduced to support different formats of keymap files. INPUTS hande - keymap handle returned by OpenKeyMapHandleA(). taglist - A taglist whose tag field elements are valid for inquiry, and whose associated data fields are pointers to the destination in which to place the requested data. Currently defined tags: KEYMAPINFO_SETCHARSET - IANA charset number of the charset the struct KeyMapNode shall be adjusted to. Must be specified in the same taglist but before the KEYMAPINFO_KEYMAPNODE tag. If not present, current system default charset is used (V51). KEYMAPINFO_KEYMAPNODE - place a pointer to a struct KeyMapNode at the location pointed to by ti_Data. KEYMAPINFO_GETCLASSICKEYBOARD - private, dont use. KEYMAPINFO_SETCLASSICKEYBOARD - private, dont use. KEYMAPINFO_INFOTEXT_ENGLISH - place a pointer to an english string or NULL at the location pointed to by ti_Data. The string describes the purpose of the keymap file (e.g. for Prefs/Input). It is taken from the keymap file itself, if not available, the file comment is used, if empty, NULL is used (V51). KEYMAPINFO_INFOTEXT_CHARSET - Place an ULONG with the IANA charset number or 0 at the location pointed to by ti_Data. This is the charset to use for display of the local description (see below) (V51). KEYMAPINFO_INFOTEXT_LOCAL - place a pointer to a local string or NULL at the location pointed to by ti_Data. The string describes the purpose of the keymap file (e.g. for Prefs/Input) in the local language (danish for a danish keymap). It is taken from the keymap file itself, if not available, NULL is used (V51). KEYMAPINFO_CLASSIC_ONLY - Place an ULONG with 0 for FALSE or not 0 for TRUE at the location pointed to by ti_Data. TRUE means this keymap should only be used for classic Amiga keyboard hardware (V51). KEYMAPINFO_PC_ONLY - Place an ULONG with 0 for FALSE or not 0 for TRUE at the location pointed to by ti_Data. TRUE means this keymap should only be used for "PC keyboard" hardware (V51). RESULTS This function returns a non-zero success indication, or zero in case of an error. When an error occurs, the function does return immediately and does not process the rest of the taglist. SEE ALSO libraries/keymap.h, keymap.library/OpenKeyMapHandleA(), keymap.library/ReleaseKeyMapInfoA() keymap.library/ObtainRawKeyInfoA keymap.library/ObtainRawKeyInfoA NAME ObtainRawKeyInfoA -- Obtain info about a rawkey. (V51.7) SYNOPSIS VOID ObtainRawKeyInfoA(const struct TagItem *taglist); VOID ObtainRawKeyInfo(Tag tag1, ...); FUNCTION Retrieve information about a rawkey. This function was introduced to support user-editable rawkey files. INPUTS taglist - A taglist whose RKI_SET_ tag data field elements specify which rawkey you mean, and whose RKI_GET_ tag data fields are pointers to the destination in which to place the requested data. Currently defined tags: RKI_SET_TYPE - Which type of data will be passed with the following RKI_SET_VALUE tags: RKITYPE_RAWKEY - 8bit IECLASS_RAWKEY values. RKITYPE_EXT_RAWKEY - 16bit extended rawkey values. RKITYPE_PS2_SET1 - PS/2 set1 make code, upto four bytes in an ULONG, e.g. 0x00E11D45 means the E1 1D 45 make code for Pause. RKITYPE_PS2_SET2 - PS/2 set2 make code, upto four bytes in an ULONG, e.g. 0x00E11477 means the E1 14 77 make code for Pause. RKITYPE_USB - USB HID usage class in the upper 16 bits and USB HID usage ID in the lower 16 bits, e.g. 0x00070062 for class 7 (keyboard/keypad) ID 62 (numeric pad "0"). The value is interpreted as a keydown code. RKITYPE_USB_UPCODE - Same as RKITYPE_USB but the value is interpreted as a keyup code. RKI_SET_VALUE - The data of the type specified by the last RKI_SET_TYPE tag which specifies about which rawkey you need information. RKI_GET_RAWKEY - Place an ULONG with the 8bit IECLASS_RAWKEY value or 0x000000FF for "undefined" at the location pointed to by ti_Data. RKI_GET_EXT_RAWKEY - Place an ULONG with the 16bit extended rawkey value or 0x000000FF for "undefined" at the location pointed to by ti_Data. RKI_GET_PS2_SET1 - Place an ULONG with upto four bytes specifying the PS/2 set 1 make code or 0x00000000 for "undefined" at the location pointed to by ti_Data. RKI_GET_PS2_SET2 - Place an ULONG with upto four bytes specifying the PS/2 set 2 make code or 0x00000000 for "undefined" at the location pointed to by ti_Data. RKI_GET_USB - Place an ULONG with the USB HID usage class in the upper 16 bits and the USB HID usage ID in the lower 16 bits or 0x00000000 for "undefined" at the location pointed to by ti_Data. RKI_GET_FLAGS - Place an ULONG with flags (0x00000000 for "undefined") at the location pointed to by ti_Data. The upper 16 bits are reserved, the lower 16 bits can contain the following flags: IEQUALIFIER_LSHIFT for the left Shift key IEQUALIFIER_RSHIFT for the right Shift key IEQUALIFIER_CAPSLOCK for the CapsLock key IEQUALIFIER_CONTROL for the Control keys IEQUALIFIER_LALT for the left Alt key IEQUALIFIER_RALT for the right Alt key IEQUALIFIER_LCOMMAND for the left Command key IEQUALIFIER_RCOMMAND for the right Command key IEQUALIFIER_NUMERICPAD for keypad keys IEQUALIFIER_REPEAT for repeatable keys Dont test for other flags, ignore them. Dont set the flags that define a specific key in keyup events. RKI_GET_NAME - place a pointer to an english string or NULL for "undefined" at the location pointed to by ti_Data. The string describes the purpose of special keys, e.g. "RETURN", "F12" or "PREV" for usage with commodities.library, "normal" keys have NULL as string description. RESULTS No return value, the results are returned in the locations specified with the RKI_GET_ tags. The function skips unknown tags and does not stop to process the taglist when an error occurs so you dont need to preset the results. NOTES The Pause key has E11D45E19DC5 as PS/2 Set 1 make code, E11477E1F014F077 as PS/2 Set2 make code and no break codes, as defined in the PS/2 specs. This function acts as if the key would have the PS/2 Set1 make code E11D45, the PS/2 Set1 break code E19DC5, the PS/2 Set2 make code E11477 and the PS/2 Set2 break code E1F014. For Ctrl-Pause (Break) it acts as if the key would have the PS/2 Set1 make code E046, the PS/2 Set1 break code E0C6, the PS/2 Set2 make code E07E and the PS/2 Set2 break code E0F07E. SEE ALSO libraries/keymap.h keymap.library/OpenKeyMapHandleA keymap.library/OpenKeyMapHandleA NAME OpenKeyMapHandleA -- Open a keymap handle. (V50) SYNOPSIS APTR handle = OpenKeyMapHandleA(CONST_STRPTR name, const struct TagItem *taglist); APTR handle = OpenKeyMapHandle(CONST_STRPTR name, Tag tag1, ...); FUNCTION Return a handle to a keymap file. If not already in memory, load the file from disk (KEYMAPS:name). This function was introduced to support different formats of keymap files. Starting with V51, keymap files can be in text format. INPUTS name - name of the keymap. "usa" and "usa1" specify the ROM keymap, other names specify the filename in the KEYMAPS: directory. taglist - for future expansion, currently no tags are specified. RESULTS handle - a handle to a keymap that can be passed to CloseKeyMapHandle() or ObtainKeyMapInfoA(), or NULL. SEE ALSO CloseKeyMapHandle(), ObtainKeyMapInfoA() keymap.library/ReleaseKeyMapInfoA keymap.library/ReleaseKeyMapInfoA NAME ReleaseKeyMapInfoA -- Release info obtained from a keymap handle. (V50) SYNOPSIS VOID ReleaseKeyMapInfoA(APTR handle, const struct TagItem *taglist); VOID ReleaseKeyMapInfo(APTR handle, Tag tag1, ...); FUNCTION Release information obtained from a keymap handle via ObtainKeyMapInfoA(). INPUTS hande - keymap handle returned by OpenKeyMapHandleA(). taglist - A taglist whose tag field elements are valid for release, and whose associated data fields are pointers to the data to be released. Currently defined tags: KEYMAPINFO_KEYMAPNODE - ti_Data contains a pointer to a struct KeyMapNode. KEYMAPINFO_INFOTEXT_ENGLISH - ti_Data contains a pointer to an english string (V51). KEYMAPINFO_INFOTEXT_LOCAL - ti_Data contains a pointer to a local string (V51). RESULTS none. SEE ALSO libraries/keymap.h, OpenKeyMapHandleA(), ObtainKeyMapInfoA() keymap.library/SetKeyMapDefault keymap.library/SetKeyMapDefault NAME SetKeyMapDefault -- Set the current default keymap. (V36) SYNOPSIS void SetKeyMapDefault(struct KeyMap *keyMap); FUNCTION A pointer to key map specified is cached by the keymap library for use by MapRawKey and MapANSI when a keymap is not specified. INPUTS keyMap - a pointer to a keyMap structure. This key map must be permanently allocated: it must remain in memory till the machine is reset. For usability of the keymap by old applications it is appropriate that this keyMap is a node on the keymap.resource list. SEE ALSO devices/keymap.h, libraries/keymap.h, AskKeyMapDefault(), console.device ...KEYMAP functions