>>>KEYBOARD.DOC

A. Copyright Information

Keyboard.Hpp and Keyboard.Cpp along with this document file are copyright
1991 by the Gamers Programming Workshop, GAMERS forum, Compuserve (GO GAMERS,
section 11). The code and related document are free for use, distribution,
and modification, provided the following conditions are met:

	1. no commercial use of this source code or documents is permitted.
	2. no fee may be charged beyond disk duplication cost for any of this
	   material.
	3. If the code is upgraded or modified a copy of the modification must
	   be uploaded to section 11 of the GAMERS forum on Compuserve. All
	   modifications must be documented and the author's name included in
	   the source code header block, and the subsequent file package must
	   include all the original doc files as well as any additions. If you
	   modify or add functions please update the function list below.


B. Description

Keyboard.cpp and Keyboard.hpp provide a flexible low level interface to the
keyboard, which is used in this toolkit primarily by the font class read
functions. It is not an event trapping system, but rather a low level key-
board interface. For the purposes of the mode 13 toolkit if you prefer to
use your own keyboard routines you will only have to modify the font::
readstr() method, which calls getfilteredkey() (described below).

C. Function interface

*****************************************************************************

void getkey(char *key, extnd *scan);

getkey() returns the ascii and extended scan codes for the next key in the
keyboard buffer. It calls interrupt 0x16, function 0x10, which will wait for
a key if none has been pressed. Test with kbhit() if you don't the program
to idle here. The ascii code is returned as an unsigned char, and the exten-
ded code, if any, is returned as an enumerated type extnd (see definition
below).

*****************************************************************************

boolean getfilteredkey(char mask, char *key, extnd *scan);

getfilteredkey() operates exactly as getkey() with one important difference.
It accepts a mask (see definition below) which determines which sort of char-
acters are returned. The mask types can be combined with a logical or to
return multiple character types. If no key has been pressed, the function
waits. Otherwise, the next key is retrieved and compared against the mask. If
it matches the function returns true (see enum in KEYBOARD.HPP), and the
ascii and extended codes are returned in key and scan. If the key doesn't
match the function returns false and the values of key and scan are unchang-
ed.

*****************************************************************************

void stuffbuffer(char key, extnd scan);

stuffbuffer() places the ascii and extended scancodes passed in key and scan
into the keyboard buffer.

*****************************************************************************

void flushBuffer(char *buf);

flushBuffer() clears the keyboard buffer. if *buf != NULL then the flushed
codes are stored there, else they are discarded.

*****************************************************************************

D. Constants and enumerated types

*****************************************************************************

enum boolean {false,true};

Used for return value in getfiltered key. May be used anywhere else where
it's appropriate.

*****************************************************************************

enum extnd {F1=59,F2,F3,F4,F5,F6,F7,F8,F9,F10,
			F11=133,F12,
			S_F1=84,S_F2,S_F3,S_F4,S_F5,S_F6,S_F7,S_F8,S_F9,S_F10,
			S_F11=135,S_F12,
			C_F1=94,C_F2,C_F3,C_F4,C_F5,C_F6,C_F7,C_F8,C_F9,C_F10,
			C_F11=137,C_F12,
			A_F1=104,A_F2,A_F3,A_F4,A_F5,A_F6,A_F7,A_F8,A_F9,A_F10,
			A_F11=139,A_F12,
			S_TAB=15,
			HOME=71,UP_ARR,PG_UP,LT_ARR=75,RT_ARR=77,END=79,DN_ARR,
			PG_DN,INS,DEL,
			C_PRTSC=114,C_LT_ARR,C_RT_ARR,C_END,C_PG_DN,C_HOME,
			C_PG_UP=132, NO_EXT=0};

The extnd enumerated type provides constants used to refer to the extended
scan codes returned by getkey() and getfilteredkey(). Both functions return
extended codes as type extnd. Prefixes are: C_ control and key, A_ alt and
key, and S_ shift and key.

*****************************************************************************

 mask types passed to getfilteredkey() to select keymask. Masks operate
 as follows:
			  U_CASE   - returns only upper case characters
			  L_CASE   - returns only lower case characters
			  B_CASE   - returns characters of both cases
			  NUMBER   - returns only numbers
			  FUNCT    - returns only function keys
			  CURSOR   - returns only cursor positioning keys
			  PUNCT    - returns only punctuation marks
			  ESC      - returns only the escape key

 the masks can be combined with a logical OR in the call, for example:

 if(getfilteredkey(&s,&c,U_CASE|NUMBER|FUNCT))

 will return true if the key pressed was an upper case character, a
 number, or a function key. If true, the key's ascii code and scan
 value are in scan and key.

 const char UCASE = 0x1;
 const char LCASE = 0x2;
 const char BCASE = 0x4;
 const char NUMBER = 0x8;
 const char FUNCT  = 0x10;
 const char CURSOR = 0x20;
 const char PUNCT  = 0x40;
 const char ESC   = 0x80;

*****************************************************************************

E. Support

Support for this tool will be provided as and where possible through mess-
ages posted to 76605,2346 in the Game Design section (sec. 11) of the Gamers
Forum on Compuserve. Sorry, no telephone support is possible.