NAME
        MapRawKey -- Decode single raw key input event to an ANSI
                     string. (V36)

   SYNOPSIS
        actual = MapRawKey(event, buffer, length, keyMap)
        D0                 A0     A1      D1      A2

        WORD MapRawKey( struct inputevent *, strptr, word,
            struct 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
        ...
        #define BUFFERLEN       80      /* length of longest expected mapping /*
        char buffer[BUFFERLEN];
        struct inputevent ie;
        ...
            KeymapBase = OpenLibrary("keymap.library", 0);
            ...
            ie.ie_Class = IECLASS_RAWKEY;
            ie.ie_SubClass = 0;
            for (;;) {
                WaitPort(window->UserPort);
                while (im = (struct intuimessage *) 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;
                        ...
                    }
                    ...
                }
            }

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

   SEE ALSO
        devices/inputevent.h, devices/keymap.h