home *** CD-ROM | disk | FTP | other *** search
/ The Fred Fish Collection 1.5 / ffcollection-1-5-1992-11.iso / ff_disks / 200-299 / ff291.lzh / Keyboard / Keyboard.doc < prev    next >
Text File  |  1989-12-12  |  6KB  |  133 lines
  1. KEYBOARD.C--Translating Inutition RAWKEY Class Messages into Useful Codes
  2.  
  3. by Fabbian G. Dufoe, III
  4.  
  5.  
  6.  
  7. INTRODUCTION
  8.  
  9. Getting ordinary keystrokes into your program is a tricky business on
  10. the Amiga if you want to use Intuition's windows and other features.
  11. Intuition provides two IDCMP flags: VANILLAKEY and RAWKEY.  VANILLAKEY
  12. returns ASCII codes for the standard ASCII characters but doesn't tell you
  13. anything about functions keys, cursor keys, or the help key.  RAWKEY
  14. identifies the physical key which was pressed buy you have to do some extra
  15. processing to relate it to the key value assigned to it in the user's
  16. keymap.  Keyboard.c does that extra processing for you.  This document
  17. explains how to call the three functions to open the console device, close
  18. the console device, and get ASCII keycodes or unique key identifiers from
  19. the console device.
  20.  
  21. This document and the other files in this archive are in the public
  22. domain.  You may use them any way you wish.
  23.  
  24.  
  25.  
  26. FILES IN THIS ARCHIVE
  27.  
  28. This archive contains the following files:
  29.  
  30.      Keyboard.c     Source code for functions to translate RAWKEY Intuition
  31.                     messages to usable keycodes
  32.  
  33.      Keyboard.doc   Documentation for Keyboard.c
  34.  
  35.      Keyboard.h     Function prototypes and declarations for programs using
  36.                     Keyboard.c
  37.  
  38.      Keyboard.o     Object file compiled from Keyboard.c with the Lattice
  39.                     AmigaDOS C compiler, version 5.02.  You can use this as
  40.                     a link-time library if you have a compiler that uses the
  41.                     standard Amiga object format.
  42.  
  43.      RawDemo        Executable demonstration program that uses the
  44.                     Keyboard.c functions
  45.  
  46.      RawDemo.c      Source code for Keyboard.c demonstration program
  47.  
  48.      RawDemo.lmk    Input for the Lattice lmk utility for compiling
  49.                     RawDemo.c and Keyboard.c
  50.  
  51.  
  52.  
  53. QUICK INSTRUCTIONS
  54.  
  55. To use the functions in Keyboard.c you must include Keyboard.h in your
  56. source file (#include "Keyboard.h").  If your C compiler does not support
  57. function prototypes define the symbolic constant "__NOPROTO" in your source
  58. file (#define __NOPROTO).
  59.  
  60. Open the console device by calling OpenReadConsole().  OpenReadConsole()
  61. takes no arguments.  It returns 0 if it succeeds or -1 if it fails.
  62.  
  63. When you get an Intuition RAWKEY class message call ReadKey() to decode it.
  64. You have to set the IDCMP RAWKEY flag when you open your window to get
  65. RAWKEY class messages.  ReadKey() requires three arguments.
  66.  
  67.      1.  A pointer to the Intuition message (struct IntuiMessage *)
  68.      2.  A pointer to the key ID number (unsigned short int *)
  69.      3.  A pointer to the keymap (struct KeyMap *)
  70.  
  71. To use the default keymap set the pointer to NULL.
  72.  
  73. ReadKey() returns a char.  If the key can be represented by a standard ASCII
  74. character ReadKey() will return that character.  Note that control
  75. characters are included in this category.  ReadKey() returns 0 for keys
  76. which can't be represented by an ASCII character.  In that case the key can
  77. be identified by the value in the KeyID field.  The value will match one of
  78. the symbolic constants defined in Keyboard.h.  If ReadKey() fails it returns
  79. -1.  If the message was not a RAWKEY class message or if it was a "key up"
  80. message ReadKey() returns -2.  You can safely ignore return values of -2.
  81.  
  82. Close the console device by calling CloseReadConsole().  CloseReadConsole()
  83. takes no arguments and returns nothing.
  84.  
  85.  
  86.  
  87. THEORY
  88.  
  89. The console device (like all Amiga devices) is also a library.  It provides
  90. a function called RawKeyConvert() which translates Intuition RAWKEY messages
  91. into the sequences you would get if you were reading the console device
  92. directly.  RawKeyConvert would generate 0x9b 0x30 0x7e if you pressed the F1
  93. key.
  94.  
  95. To use RawKeyConvert() you need a pointer to the console device just as you
  96. need a pointer to the Intuition library to use any Intuition functions.
  97. OpenReadConsole() calls the exec function OpenDevice with a unit number of
  98. -1.  That gets a pointer to the device library vector without opening an
  99. actual console.  You need to get the pointer before you call ReadKey()
  100. because ReadKey() uses RawKeyConvert().
  101.  
  102. If you want to write to the console device you'll have to call OpenDevice()
  103. directly.  That's beyond the scope of this document.  You'll need to look in
  104. the ROM Kernel Manual: Libraries and Devices for discussion of the console
  105. device (chapter 8), the ROM Kernel Manual: Exec for discussion of messages
  106. and ports (chapter 3) and input and output (chapter 4), and the Autodocs for
  107. information about OpenDevice (Autodocs1.3/DevicesA-K/console.doc).
  108.  
  109. ReadKey() passes the Intuition message along to DeadKeyConvert() which calls
  110. RawKeyConvert().  DeadKeyConvert is taken substantially from the 1.2
  111. Enhancer manual (page 65).  Dead keys allow you to add diacritical marks to
  112. some characters.  On the usa keymap there are five dead keys: F, G, H, J,
  113. and K.  If you hold down the ALT key and press F nothing happens.  That's
  114. why it's called a dead key.  Now press e.  There will be an accent mark
  115. above the e (i).
  116.  
  117. RawKeyConvert() doesn't know about dead keys, so you need to use
  118. DeadKeyConvert() as a front end.  Both RawKeyConvert() and DeadKeyConver()
  119. place a sequence of codes in a buffer.  The sequence can vary in length.
  120. ASCII characters require a single code.  Function keys may require four.
  121. ReadKey() parses the sequences returned by DeadKeyConvert() and reduces
  122. everything to a single code.  Printable characters (and control characters)
  123. are returned to the caller.  It identifies special keys by placing a code in
  124. the KeyID field pointed to by the caller.  The caller does not have to
  125. examine the KeyID field unless ReadKey() returns 0.
  126.  
  127.  
  128.  
  129. DOCUMENTATION OF FUNCTIONS
  130.  
  131. The interface parameters for each function in Keyboard.c are included as
  132. comments in the source code.
  133.