@database "keymap"
@master "AMIDEV:NDK/Autodocs/keymap.doc"

@Node Main "keymap.doc"
@toc "Autodocs/AG/INDEX/Main"
    @{" AskKeyMapDefault() " Link "AskKeyMapDefault()"}
    @{" MapANSI() " Link "MapANSI()"}
    @{" MapRawKey() " Link "MapRawKey()"}
    @{" SetKeyMapDefault() " Link "SetKeyMapDefault()"}
@EndNode

@Node "AskKeyMapDefault()" "keymap.library/AskKeyMapDefault"

@{b}   NAME@{ub}
	AskKeyMapDefault -- Ask for a pointer to the current default
	                    keymap. (V36)

@{b}   SYNOPSIS@{ub}
	keyMap = AskKeyMapDefault()

	struct @{"KeyMap" Link "INCLUDE:libraries/keymap.h/Main" 19} *AskKeyMapDefault( VOID );

@{b}   FUNCTION@{ub}
	Return a pointer to the keymap used by the keymap library for
	@{"MapRawKey" Link "keymap/MapRawKey()"} and @{"MapANSI" Link "keymap/MapANSI()"} when a keymap is not specified.

@{b}   RESULTS@{ub}
	keyMap - a pointer to a keyMap structure.  This key map is
	    guaranteed to be permanently allocated: it will remain in
	    memory till the machine is reset.

@{b}   BUGS@{ub}
	The keymap.h include file should be in the libraries/ or perhaps
	resources/ directory, but is in the devices/ directory for
	compatibility reasons.

@{b}   SEE ALSO@{ub}
	@{"devices/keymap.h" Link "INCLUDE:devices/keymap.h/Main" 0}, @{"keymap.library/SetKeyMapDefault()" Link "SetKeyMapDefault()"},
	console.device ...KEYMAP functions

@EndNode

@Node "MapANSI()" "keymap.library/MapANSI"

@{b}   NAME@{ub}
	MapANSI -- Encode an ANSI string into keycodes. (V36)

@{b}   SYNOPSIS@{ub}
	actual = MapANSI( string, count, buffer, length, keyMap )
	D0                A0      D0     A1      D1      A2

	@{"LONG" Link "INCLUDE:exec/types.h/Main" 112} MapANSI( @{"STRPTR" Link "INCLUDE:exec/types.h/Main" 137}, @{"LONG" Link "INCLUDE:exec/types.h/Main" 112}, @{"STRPTR" Link "INCLUDE:exec/types.h/Main" 137}, @{"LONG" Link "INCLUDE:exec/types.h/Main" 112}, struct @{"KeyMap" Link "INCLUDE:libraries/keymap.h/Main" 19} * );

@{b}   FUNCTION@{ub}
	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.


@{b}   INPUTS@{ub}
	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" Link "INCLUDE:libraries/keymap.h/Main" 19} structure pointer, or null if the default
	    key map is to be used.

@{b}   RESULT@{ub}
	actual - the number of code/qualifier pairs in the buffer,
	    or negative to describe an error (see below).

@{b}   EXAMPLE@{ub}
	...
	#include @{"<devices/inputevent.h>" Link "INCLUDE:devices/inputevent.h/Main" 0}

	#define	STIMSIZE	3	\* two dead keys, one key *\
	unsigned char rBuffer[STIMSIZE*2];
	...
	    KeymapBase = (struct @{"Library" Link "INCLUDE:exec/libraries.h/Main" 32} *) OpenLibrary("keymap.library", 0);
	    ...
	    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 = MapANSI(buffer, 1, rBuffer, STIMSIZE, 0);
		r = rBuffer;
		event.ie_Prev2DownCode = 0;
		event.ie_Prev2DownQual = 0;
		event.ie_Prev1DownCode = 0;
		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++;
		    case 2:
			event.ie_Prev1DownCode = *r++;
			event.ie_Prev1DownQual = *r++;
		    case 1:
			event.ie_Code = *r++;
			event.ie_Qualifier = *r;

			actual = 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");
			}
		}
	    }
	...

@{b}   ERRORS@{ub}
	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)

@{b}   SEE ALSO@{ub}
	@{"devices/inputevent.h" Link "INCLUDE:devices/inputevent.h/Main" 0}, @{"devices/keymap.h" Link "INCLUDE:devices/keymap.h/Main" 0}

@EndNode

@Node "MapRawKey()" "keymap.library/MapRawKey"

@{b}   NAME@{ub}
	MapRawKey -- Decode single raw key input event to an ANSI
	             string. (V36)

@{b}   SYNOPSIS@{ub}
	actual = MapRawKey(event, buffer, length, keyMap)
	D0                 A0     A1      D1      A2

	WORD MapRawKey( struct @{"InputEvent" Link "INCLUDE:devices/inputevent.h/Main" 255} *, @{"STRPTR" Link "INCLUDE:exec/types.h/Main" 137}, WORD,
	    struct Keymap * );

@{b}   FUNCTION@{ub}
	This console function converts input events of type
	IECLASS_RAWKEY to ANSI bytes, based on the keyMap, and
	places the result into the buffer.

@{b}   INPUTS@{ub}
	event -  an @{"InputEvent" Link "INCLUDE:devices/inputevent.h/Main" 255} 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" Link "INCLUDE:libraries/keymap.h/Main" 19} structure pointer, or null if the default
	    key map is to be used.

@{b}   RESULT@{ub}
	actual - the number of characters in the buffer, or -1 if
	    a buffer overflow was about to occur.

@{b}   EXAMPLE@{ub}
	...
	#define	BUFFERLEN	80	\* length of longest expected mapping \*
	char buffer[BUFFERLEN];
	struct @{"InputEvent" Link "INCLUDE:devices/inputevent.h/Main" 255} ie;
	...
	    KeymapBase = OpenLibrary("keymap.library", 0);
	    ...
	    ie.ie_Class = IECLASS_RAWKEY;
	    ie.ie_SubClass = 0;
	    for (;;) {
		WaitPort(window->UserPort);
		while (im = (struct @{"IntuiMessage" Link "INCLUDE:intuition/intuition.h/Main" 768} *) GetMsg(window->UserPort)) {
		    switch (im->Class) {
			case RAWKEY:
			    ie.ie_Code = im->Code;
			    ie.ie_Qualifier = im->Qualifier;
			    \* recover dead key codes & qualifiers *\
			    ie.ie_EventAddress = (APTR *) *((ULONG *)im->IAddress);
			    actual = MapRawKey(&ie, buffer, BUFFERLEN, 0);
			    for (i = 0; i < actual; i++)
				ReportChar(buffer[i]);
			    break;
			...
		    }
		    ...
		}
	    }

@{b}   ERRORS@{ub}
	if actual is -1, a buffer overflow condition was detected.
	Not all of the characters in the buffer are valid.

@{b}   SEE ALSO@{ub}
	@{"devices/inputevent.h" Link "INCLUDE:devices/inputevent.h/Main" 0}, @{"devices/keymap.h" Link "INCLUDE:devices/keymap.h/Main" 0}

@EndNode

@Node "SetKeyMapDefault()" "keymap.library/SetKeyMapDefault"

@{b}   NAME@{ub}
	SetKeyMapDefault -- Set the current default keymap. (V36)

@{b}   SYNOPSIS@{ub}
	SetKeyMapDefault(keyMap)

	void SetKeyMapDefault( struct @{"KeyMap" Link "INCLUDE:libraries/keymap.h/Main" 19} * );

@{b}   FUNCTION@{ub}
	A pointer to key map specified is cached by the keymap library
	for use by @{"MapRawKey" Link "keymap/MapRawKey()"} and @{"MapANSI" Link "keymap/MapANSI()"} when a keymap is not specified.

@{b}   INPUTS@{ub}
	keyMap - a pointer to a keyMap structure.  This key map must be
	    permanently allocated: it must remain in memory till the
	    machine is reset.  It is appropriate that this keyMap be a
	    node on the keymap.resource list.

@{b}   BUGS@{ub}
	The keymap.h include file should be in the libraries/ or perhaps
	resources/ directory, but is in the devices/ directory for
	compatability reasons.

@{b}   SEE ALSO@{ub}
	@{"devices/keymap.h" Link "INCLUDE:devices/keymap.h/Main" 0}, @{"keymap.library/AskKeyMapDefault()" Link "AskKeyMapDefault()"},
	console.device ...KEYMAP functions

@EndNode