home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / Programming / Misc / TRSICAT.LZX / CATS_CD2_TRSI / Inc&AD2.1 / Text_Autodocs / keymap.doc < prev    next >
Encoding:
Text File  |  1992-09-11  |  6.6 KB  |  234 lines
  1. TABLE OF CONTENTS
  2.  
  3. keymap.library/AskKeyMapDefault
  4. keymap.library/MapANSI
  5. keymap.library/MapRawKey
  6. keymap.library/SetKeyMapDefault
  7. keymap.library/AskKeyMapDefault               keymap.library/AskKeyMapDefault
  8.  
  9.    NAME
  10.     AskKeyMapDefault -- Ask for a pointer to the current default
  11.                         keymap. (V36)
  12.  
  13.    SYNOPSIS
  14.     keyMap = AskKeyMapDefault()
  15.  
  16.     struct KeyMap *AskKeyMapDefault( VOID );
  17.  
  18.    FUNCTION
  19.     Return a pointer to the keymap used by the keymap library for
  20.     MapRawKey and MapANSI when a keymap is not specified. 
  21.  
  22.    RESULTS
  23.     keyMap - a pointer to a keyMap structure.  This key map is
  24.         guaranteed to be permanently allocated: it will remain in
  25.         memory till the machine is reset.
  26.  
  27.    BUGS
  28.     The keymap.h include file should be in the libraries/ or perhaps
  29.     resources/ directory, but is in the devices/ directory for
  30.     compatability reasons.
  31.  
  32.    SEE ALSO
  33.     devices/keymap.h, keymap.library/SetKeyMapDefault(),
  34.     console.device ...KEYMAP functions
  35.  
  36. keymap.library/MapANSI                                 keymap.library/MapANSI
  37.  
  38.    NAME
  39.     MapANSI -- Encode an ANSI string into keycodes. (V36)
  40.  
  41.    SYNOPSIS
  42.     actual = MapANSI( string, count, buffer, length, keyMap )
  43.     D0                A0      D0     A1      D1      A2
  44.  
  45.     LONG MapANSI( STRPTR, LONG, STRPTR, LONG, struct KeyMap * );
  46.  
  47.    FUNCTION
  48.     This console function converts an ANSI byte string to the
  49.     code/qualifier pairs of type IECLASS_RAWKEY that would
  50.     generate the string and places those pairs in a buffer.
  51.     A code/qualifier pair is a pair of bytes suitable for
  52.     putting in the ie_Code and low byte of ie_Qualifier,
  53.     and for subsequent events, shifted to the ie_Prev1DownCode/
  54.     ie_Prev1DownQual then ie_Prev2DownCode/ie_Prev2DownQual
  55.     pairs for any dead or double dead key mapping.
  56.     
  57.  
  58.    INPUTS
  59.     string - the ANSI string to convert.
  60.     count - the number of characters in the string.
  61.     buffer - a byte buffer large enough to hold all anticipated
  62.         code/qualifier pairs generated by this conversion.
  63.     length - maximum anticipation, i.e. the buffer size in bytes
  64.         divided by two (the size of the code/qualifier pair).
  65.     keyMap - a KeyMap structure pointer, or null if the default
  66.         key map is to be used.
  67.  
  68.    RESULT
  69.     actual - the number of code/qualifier pairs in the buffer,
  70.         or negative to describe an error (see below).
  71.  
  72.    EXAMPLE
  73.     ...
  74.     #include <devices/inputevent.h>
  75.     
  76.     #define    STIMSIZE    3    /* two dead keys, one key */
  77.     unsigned char rBuffer[STIMSIZE*2];
  78.     ...
  79.         KeymapBase = (struct Library *) OpenLibrary("keymap.library", 0);
  80.         ...
  81.         event.ie_NextEvent = 0;
  82.         event.ie_Class = IECLASS_RAWKEY;
  83.         event.ie_SubClass = 0;
  84.     
  85.         /* prove keymap code completeness and MapANSI reversibility */
  86.         for (code = 0; code < 256; code++) {
  87.         buffer[0] = code;
  88.         actual = MapANSI(buffer, 1, rBuffer, STIMSIZE, 0);
  89.         r = rBuffer;
  90.         event.ie_Prev2DownCode = 0;
  91.         event.ie_Prev2DownQual = 0;
  92.         event.ie_Prev1DownCode = 0;
  93.         event.ie_Prev1DownQual = 0;
  94.         switch (actual) {
  95.             case -2:
  96.             printf("MapANSI internal error");
  97.             goto reportChar;
  98.             case -1:
  99.             printf("MapANSI overflow error");
  100.             goto reportChar;
  101.             case 0:
  102.             printf("MapANSI ungeneratable code");
  103.             goto reportChar;
  104.     
  105.             case 3:
  106.             event.ie_Prev2DownCode = *r++;
  107.             event.ie_Prev2DownQual = *r++;
  108.             case 2:
  109.             event.ie_Prev1DownCode = *r++;
  110.             event.ie_Prev1DownQual = *r++;
  111.             case 1:
  112.             event.ie_Code = *r++;
  113.             event.ie_Qualifier = *r;
  114.     
  115.             actual = MapRawKey(&event, buffer, BUFFERLEN, 0);
  116.             if ((actual != 1) || (buffer[0] != code)) {
  117.                 printf("MapANSI not reversible");
  118.                 for (i = 0; i < actual; i++)
  119.                 ReportChar(buffer[i]);
  120.                 printf(" from");
  121.     reportChar:
  122.                 ReportChar(code);
  123.                 printf("\n");
  124.             }
  125.         }
  126.         }
  127.     ...
  128.  
  129.    ERRORS
  130.     if actual is 0, a character in the string was not generatable
  131.         from the keyMap.
  132.     if actual is -1, a buffer overflow condition was detected.
  133.     if actual is -2, an internal error occurred (e.g. no memory)
  134.  
  135.    SEE ALSO
  136.     devices/inputevent.h, devices/keymap.h
  137.  
  138. keymap.library/MapRawKey                             keymap.library/MapRawKey
  139.  
  140.    NAME
  141.     MapRawKey -- Decode single raw key input event to an ANSI
  142.                  string. (V36)
  143.  
  144.    SYNOPSIS
  145.     actual = MapRawKey(event, buffer, length, keyMap)
  146.     D0                 A0     A1      D1      A2
  147.  
  148.     WORD MapRawKey( struct InputEvent *, STRPTR, WORD,
  149.         struct Keymap * );
  150.  
  151.    FUNCTION
  152.     This console function converts input events of type
  153.     IECLASS_RAWKEY to ANSI bytes, based on the keyMap, and
  154.     places the result into the buffer.
  155.  
  156.    INPUTS
  157.     event -  an InputEvent structure pointer.  The event list is
  158.         not traversed.
  159.     buffer - a byte buffer large enough to hold all anticipated
  160.         characters generated by this conversion.
  161.     length - maximum anticipation, i.e. the buffer size in bytes.
  162.     keyMap - a KeyMap structure pointer, or null if the default
  163.         key map is to be used.
  164.  
  165.    RESULT
  166.     actual - the number of characters in the buffer, or -1 if
  167.         a buffer overflow was about to occur.
  168.  
  169.    EXAMPLE
  170.     ...
  171.     #define    BUFFERLEN    80    /* length of longest expected mapping /*
  172.     char buffer[BUFFERLEN];
  173.     struct InputEvent ie;
  174.     ...
  175.         KeymapBase = OpenLibrary("keymap.library", 0);
  176.         ...
  177.         ie.ie_Class = IECLASS_RAWKEY;
  178.         ie.ie_SubClass = 0;
  179.         for (;;) {
  180.         WaitPort(window->UserPort);
  181.         while (im = (struct IntuiMessage *) GetMsg(window->UserPort)) {
  182.             switch (im->Class) {
  183.             case RAWKEY:
  184.                 ie.ie_Code = im->Code;
  185.                 ie.ie_Qualifier = im->Qualifier;
  186.                 /* recover dead key codes & qualifiers */
  187.                 ie.ie_EventAddress = (APTR *) *im->IAddress;
  188.                 actual = MapRawKey(&ie, buffer, BUFFERLEN, 0);
  189.                 for (i = 0; i < actual; i++)
  190.                 ReportChar(buffer[i]);
  191.                 break;
  192.             ...
  193.             }
  194.             ...
  195.         }
  196.         }
  197.  
  198.    ERRORS
  199.     if actual is -1, a buffer overflow condition was detected.
  200.     Not all of the characters in the buffer are valid.
  201.  
  202.    SEE ALSO
  203.     devices/inputevent.h, devices/keymap.h
  204.  
  205. keymap.library/SetKeyMapDefault               keymap.library/SetKeyMapDefault
  206.  
  207.    NAME
  208.     SetKeyMapDefault -- Set the current default keymap. (V36)
  209.  
  210.    SYNOPSIS
  211.     SetKeyMapDefault(keyMap)
  212.  
  213.     void SetKeyMapDefault( struct KeyMap * );
  214.  
  215.    FUNCTION
  216.     A pointer to key map specified is cached by the keymap library
  217.     for use by MapRawKey and MapANSI when a keymap is not specified. 
  218.  
  219.    INPUTS
  220.     keyMap - a pointer to a keyMap structure.  This key map must be
  221.         permanently allocated: it must remain in memory till the
  222.         machine is reset.  It is appropriate that this keyMap be a
  223.         node on the keymap.resource list.
  224.  
  225.    BUGS
  226.     The keymap.h include file should be in the libraries/ or perhaps
  227.     resources/ directory, but is in the devices/ directory for
  228.     compatability reasons.
  229.  
  230.    SEE ALSO
  231.     devices/keymap.h, keymap.library/AskKeyMapDefault(),
  232.     console.device ...KEYMAP functions
  233.  
  234.