home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD v1.2 / amidev_cd_12.iso / reference / amiga_mail_vol2 / xi-25 / appkeymap.doc < prev    next >
Text File  |  1996-01-30  |  5KB  |  152 lines
  1. AppKeyMap.o/AlterAppKeyMap                         AppKeyMap.o/AlterAppKeyMap
  2.  
  3.    NAME
  4.     AlterAppKeyMap -- Changes keyboard mappings for a keymap
  5.  
  6.    SYNOPSIS
  7.     AlterAppKeyMap(mykeymap, keyarray, arrayentries);
  8.  
  9.     void AlterAppKeyMap(struct KeyMap *,
  10.                     struct MyKey *,
  11.                     UWORD);
  12.  
  13.    FUNCTION
  14.     Using an array of MyKey structures (which describe a series of
  15.     rawkeys), this function    changes the rawkey's corresponding
  16.     mapping values in mykeymap.  Only call this function on
  17.     a private copy of a KeyMap (including its data).
  18.  
  19.    INPUTS
  20.     mykeymap = pointer to a KeyMap structure.  AlterAppKeyMap() will
  21.       make changes to this KeyMap's data, so this KeyMap should
  22.       be a private copy of a KeyMap (including the data the KeyMap
  23.       points to).
  24.  
  25.     keyarray  = pointer to an array of struct MyKey (from
  26.       appkeymap.h):
  27.  
  28.             struct MyKey
  29.             {
  30.               UBYTE RawCode;    /* RawCode of character to change      */
  31.                 /* in the KeyMap.  Correponds to the   */
  32.                 /* Lo/HiKeyMap structures from the     */
  33.                 /* KeyMap structure.               */
  34.               UBYTE MapType;    /* The Lo/HiKeyMapTypes field.         */
  35.               UBYTE Capsable;   /* This TRUE/FALSE state of this bit   */
  36.                                 /* gets translated to the correspond-  */
  37.                                 /* bit in KeyMap.Lo/HiCapsable.        */
  38.               UBYTE Repeatable; /* This TRUE/FALSE state of this bit   */
  39.                                 /* gets translated to the correspond-  */
  40.                                 /* bit in KeyMap.Lo/HiRepeatable.      */
  41.               ULONG Map;    /* Map data for key.  This points to   */
  42.                           /* data for the rawkey.  Its format    */
  43.                           /* depends on the key type. This field */
  44.                           /* correponds to KeyMap.Lo/HiKeyMap.   */
  45.             };
  46.  
  47.         arrayentries = The number of MyKey entries in keyarray.
  48.  
  49.  
  50.    RESULT
  51.     For each MyKey entry in keyarray, AlterKeyMap() finds the correpsonding
  52.     raw key    entry in mykeymap and changes the data to match the entry
  53.     in keyarray.  AlterKeyMap() makes changes directly to the KeyMap's
  54.     data, so don't call this function on a system copy of a keymap, make
  55.     a copy of it.
  56.  
  57.     Note that the console.device's CD_ASKKEYMAP only copies a KeyMap
  58.     structure, which is only a set of pointers.  If you want to customize
  59.     a copy of a keymap, you also have to duplicate the data that
  60.     the KeyMap references.  If you do not duplicate the keymap data when
  61.     customizing a keymap, you'll write over data that many keymaps are
  62.     currently using.
  63.  
  64.     This function assumes that the keymap passed to it was duplicated
  65.     using the CreateAppKeyMap() function.  CreateAppKeyMap() puts
  66.     the keymap tables in a specific order and AlterAppKeyMap()
  67.     expects to find the tables in that order.  Only call AlterAppKeyMap()
  68.     on keymaps duplicated with CreateAppKeyMap().
  69.  
  70.    BUGS
  71.  
  72.    SEE ALSO
  73.     console.device/CD_ASKKEYMAP console.device/CD_SETKEYMAP "appkeymap.h"
  74.     AppKeyMap.o/CreateAppKeyMap() AppKeyMap.o/DeleteAppKeyMap()
  75.  
  76. AppKeyMap.o/CreateAppKeyMap                       AppKeyMap.o/CreateAppKeyMap
  77.  
  78.    NAME
  79.     CreateAppKeyMap -- Create a new KeyMap by duplicating an existing one.
  80.  
  81.    SYNOPSIS
  82.     newkeymap = CreateAppKeyMap(origkeymap);
  83.  
  84.     struct KeyMap *CreateAppKeyMap(struct KeyMap *);
  85.  
  86.    FUNCTION
  87.     This function accepts a pointer to a KeyMap structure and duplicates it.
  88.     CreateAppKeyMap() allocates the memory for a KeyMap structure and all
  89.     the tables associated with that keymap.
  90.  
  91.    INPUTS
  92.     origkeymap = points to a KeyMap to duplicate.
  93.  
  94.    RESULT
  95.     If successful, this function returns a pointer to a duplicate of
  96.     origkeymap.  CreateAppKeyMap() duplicates all of the tables that
  97.     origkeymap references, so an application can make changes to the
  98.     duplicate.  If CreateAppKeyMap() fails, it returns NULL.  The
  99.     DeleteAppKeyMap() function deallocates the resources allocated
  100.     by CreateAppKeyMap().
  101.  
  102.     CreateAppKeyMap() places the duplicate tables in an order so
  103.     that a "Lo" table (for example, KeyMap.km_LoKeyMap) is immediately
  104.     followed by the corresponding "Hi" table (KeyMap.km_HiKeyMap).
  105.     This allows application to reference the two tables as one using
  106.     the raw key value as an index.
  107.  
  108.    BUGS
  109.  
  110.    SEE ALSO
  111.     console.device/CD_ASKKEYMAP console.device/CD_SETKEYMAP "appkeymap.h"
  112.     AppKeyMap.o/AlterAppKeyMap() AppKeyMap.o/DeleteAppKeyMap()
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120. AppKeyMap.o/DeleteAppKeyMap                       AppKeyMap.o/DeleteAppKeyMap
  121.  
  122.    NAME
  123.     DeleteAppKeyMap -- Relinquish the resources allocated by
  124.                        CreateAppKeyMap.
  125.  
  126.    SYNOPSIS
  127.     DeleteAppKeyMap(mykeymap);
  128.  
  129.     void DeleteAppKeyMap(struct KeyMap *);
  130.  
  131.    FUNCTION
  132.        This function accepts a pointer to a keymap allocated by
  133.        CreateAppKeyMap() and deallocates the resources allocated
  134.        by that function.
  135.  
  136.    INPUTS
  137.     mykeymap = points to a KeyMap to deallocate.
  138.  
  139.    RESULT
  140.        Frees memory previously used by mykeymap and its associated tables.
  141.  
  142.    BUGS
  143.  
  144.    SEE ALSO
  145.     console.device/CD_ASKKEYMAP console.device/CD_SETKEYMAP "appkeymap.h"
  146.     AppKeyMap.o/AlterAppKeyMap() AppKeyMap.o/CreateAppKeyMap()
  147.  
  148.  
  149.  
  150.  
  151.  
  152.