fish/input/readme

   1 KEYBOARD INPUT MADE EASY
   2 © Copyright 1990 Timm Martin
   3
   4
   5 INTRODUCTION
   6
   7 This archive contains a few functions which should make reading input from
   8 the keyboard a snap.  Included are 6 files:
   9
  10    README ...... what you are reading now
  11    console.c ... functions to open and close the console device
  12    input.c ..... a function to read keyboard input
  13    input.h ..... header file for programs using these functions
  14    test.c ...... test program showing you how to use these functions
  15    test ........ executable form of the test program
  16
  17 At the heart of this keyboard processor is an input function which "cooks"
  18 Intuition RAWKEY messages, returning a 16-bit number packed with all necessary
  19 key information.  This number contains not only the value of the key pressed,
  20 but also any qualifiers (such as the SHIFT key, ALT key, Amiga key, or CONTROL
  21 key).  The function will return all key presses including command keys
  22 (function keys, arrow keys, HELP, DELETE, BACKSPACE, RETURN, ESCAPE, and
  23 RETURN) and international dead keys (such as e-accent-grave received when you
  24 press ALT-g then e).
  25
  26
  27 LEGAL JUNK
  28
  29 Some of the source is copyrighted, but all of it may be used freely as long
  30 as the copyright notice remains intact.  You may use any of this source
  31 inside executable programs without acknowledgement of or compensation to the
  32 author (me!).
  33
  34 All of the source was written to conform to ANSI C standards and compiles
  35 cleanly using Manx C v5.0b (and compiler options -pas -wadpru).
  36
  37
  38 GETTING STARTED...QUICKLY!
  39
  40 --  Place the input.h header file in the current directory and add the
  41     following line to the beginning of your source file:
  42
  43         #include "input.h"
  44
  45 --  In your program startup function, call the console_open() function,
  46     checking its return value.  If FALSE, you should end the program.
  47
  48 --  In your program cleanup function, call the console_close() function.
  49
  50 --  Be sure to set the RAWKEY flag in the IDCMPFlags member of your NewWindow
  51     structure.
  52
  53 --  Inside your window input loop, check for a RAWKEY message class.  If
  54     received, call the input_key() function, passing it a pointer to the
  55     IntuiMessage.  If this function returns a non-zero value, then a key
  56     has been pressed and you can process it.  For example:
  57
  58         struct Window *window;
  59         struct IntuiMessage *imessage;
  60         USHORT key;
  61
  62         while (imessage = (struct IntuiMessage *)GetMsg( window->UserPort ))
  63         {
  64           switch (imessage->Class == RAWKEY)
  65           {
  66             case RAWKEY:
  67               if (key = input_key( imessage ))
  68                 /* key was pressed -- do something with it */
  69             case CLOSEWINDOW:
  70               etc...
  71           }
  72         }
  73
  74 --  When processing a key, you first need find out whether the key was a
  75     command key (such as F1, HELP, RETURN, UP-ARROW, etc.) or an ASCII
  76     character (such as 'A', '3', 'k', etc.).  You can do this with the
  77     KEY_COMMAND() macro (defined in input.h).  For example:
  78
  79         if (KEY_COMMAND( key ))
  80           /* is a command key */
  81         else
  82           /* is an ASCII character */
  83
  84     Then you need to find out which key was pressed.  You can do this with
  85     the KEY_VALUE() macro:
  86
  87         char c;
  88         c = KEY_VALUE( key );
  89
  90     If this is a command key, then the key value will be a number between 1
  91     and 20 as defined in input.h, such as COMMAND_F1, COMMAND_HELP,
  92     COMMAND_UP_ARROW, etc.
  93
  94     If this is an ASCII character, however, then the key value will just be
  95     the value of the character itself, such as decimal 65 if the 'A' key was
  96     pressed.
  97
  98 --  If you need to know if a qualifier was pressed with the key, you can use
  99     the qualifier definitions in input.h.  For example:
 100
 101         if (key & QUAL_CONTROL)  /* was the control key pressed? */
 102         if (key & QUAL_LSHIFT)   /* was the left shift key pressed? */
 103         if (key & QUAL_SHIFT)    /* was either shift key pressed? */
 104         etc...
 105
 106 --  Compile the console.c and input.c source files.  Be sure to link these
 107     files with your main program, for example (with the test.c program and
 108     Manx C):
 109
 110         ln test console input -lc
 111
 112
 113 TECHNICAL DETAILS
 114
 115 To convert Intuition RAWKEY messages into ASCII characters, the input_key()
 116 function uses the Amiga RawKeyConvert() function.  This function is not
 117 located in any ROM library, but rather, is a vector attached to the console
 118 device.  This means that you need to open console.device to use it.
 119
 120 The source file console.c was provided for your convenience.  It includes the
 121 console_open() function (which opens the console device, returning TRUE or
 122 FALSE whether successful) and the console_close() function (which closes the
 123 console device).
 124
 125 Each time you receive an Intuition RAWKEY message, you should call the
 126 input_key() function, sending it a pointer to the IntuiMessage.  Note that
 127 you may receive more than one RAWKEY message per key returned by input_key().
 128 Intuition sends a RAWKEY message each time a key is pressed OR released, and
 129 whenever a qualifier key is pressed or released.  The input_key() function
 130 filters out all extraneous messages and returns a non-zero value only when
 131 there's a key to be dealt with.
 132
 133 The input_key() function returns a unsigned short (16-bit) integer.  The
 134 information is laid out as follows:
 135
 136     <-- MOST SIGNIFICANT BYTE --->  <-- LEAST SIGNIFICANT BYTE -->
 137     15  14  13  12  11  10  09  08  07  06  05  04  03  02  01  00  <--BITS
 138     RG  LG  RA  LA  CT  RS  LS  CO  <-------- key value --------->
 139
 140 where if the bits are set (==1) indicate:
 141
 142     BIT  MEANING
 143     ---  -----------------------------------
 144     15   right AMIGA key was pressed
 145     14   left AMIGA key was pressed
 146     13   right ALT key was pressed
 147     12   left ALT key was pressed
 148     11   CONTROL key was pressed
 149     10   right SHIFT key was pressed
 150     09   left SHIFT key was pressed
 151     08   one of the command keys was pressed
 152
 153 The least significant byte (represented by bits 0 through 7) holds the value
 154 of the key pressed.  If a command key was pressed, bit 08 will be set and the
 155 key value in bits 0 through 7 will contain a number between 1 and 20 as
 156 defined in input.h:
 157
 158     VALUE  #define              CORRESPONDING COMMAND KEY
 159     -----  -------------------  -------------------------
 160      1     COMMAND_F1           F1 key
 161      2     COMMAND_F2           F2 key
 162      3     COMMAND_F3           F3 key
 163      4     COMMAND_F4           F4 key
 164      5     COMMAND_F5           F5 key
 165      6     COMMAND_F6           F6 key
 166      7     COMMAND_F7           F7 key
 167      8     COMMAND_F8           F8 key
 168      9     COMMAND_F9           F9 key
 169     10     COMMAND_F10          F10 key
 170     11     COMMAND_TAB          TAB key
 171     12     COMMAND_DELETE       DELETE key
 172     13     COMMAND_ESCAPE       ESCAPE key
 173     14     COMMAND_BACKSPACE    BACKSPACE key
 174     15     COMMAND_HELP         HELP key
 175     16     COMMAND_RETURN       RETURN key
 176     17     COMMAND_UP_ARROW     UP_ARROW key
 177     18     COMMAND_DOWN_ARROW   DOWN_ARROW key
 178     19     COMMAND_LEFT_ARROW   LEFT_ARROW key
 179     20     COMMAND_RIGHT_ARROW  RIGHT_ARROW key
 180
 181 If a character key was pressed, then bit 08 will be cleared and bits 0
 182 through 7 will represent the ASCII value of the character.
 183
 184 For more information on how this 16-bit integer is created, see the input.c
 185 source file.
 186
 187
 188 /*--- END OF TEXT ---*/