======================================================================
ReadMe  file  for  key conversion package, 07-Jun-89, compiled by Olaf
          'Olsen' Barthel of ED Electronic Design Hannover.
======================================================================

                         KEY CONVERSION, WHY?

Most  programmers  are  lazy, they want to get the maximum effect with
the  minimum  effort.   There's  nothing  wrong with this attitude but
especially  on  the  Amiga it has led to some strange result.  Results
such  as  a  good  lot  of  programs  that do not even think about the
possibility  of  a  user  typing  on  a  keyboard  with  non  american
keymapping.  For this reason especially european users get confused by
the  characters  produced  by  the  keys  they  hit.   BUT  there is a
possibility  to  find  out  about the keyboard definition the user has
selected  via  the  SetMap  program.  It is not as difficult as it may
seem.   You  use  the  console.device to translate the key events your
program receives instead of a home-brewn key conversion table.

                          HOW DOES IT WORK?

There  are  three or four possibilities to approach the key conversion
problem:

	1. Ask Intuition to send you VANILLAKEY codes, but you won't
	   get any information if the cursor keys, the help key
	   or the function keys are pressed.

	2. Open the console.device and attach a console handler to
	   your window. Good idea, but it crashes almost as often
	   as it works in civilized code.

	3. Add an input handler to the stream of input events going
	   through Intuition(), then use the console.device function
	   RawKeyConvert() to convert the InputEvent to readable
	   text.

We  use  none  of  these  methods,  we  do  the following:  When I was
experimenting  with  an  input.device  handler I discovered a striking
similarity between the RAWKEY codes Intuition sends through IDCMPs and
the ie_Code entry in the InputEvent structure.  Even the Qualifier and
the  ie_Qualifier  entries  were  the  same.   So  we  can  guess that
Intuition  distributes  copies  of the InputEvents it receives (right,
RJ?).   There  isn't  very  much  to  do  anymore,  fill an InputEvent
structure  with these values and pass it to RawKeyConvert() --- ta da!
We get converted key events!

                           HOW DO I USE IT?

I have written some routines to do the key conversion for you, these
are to be found in KeyConvert.c. For a quick comment on the functions
and the usage see the comment at the top of the file.

                            WHO NEEDS IT?

I  would  say:   NewZAP  3.18, Diga!, Handshake, Access!, Hack!, Larn,
Rogue,  The  Bard'  Tale,  Populous,  World  Class Leaderboard, F/A 18
Interceptor,  Starglider,  AFS  II,  DevPac 1.0, DPaint II (DPaint III
has),  PrintMaster,  GRABBiT, AmigaBASIC, Sonix, UEdit, CygnusEd (only
in  requesters),  Manx  SDB,  Lattice  LSE  (real  stoneage tool!) and
probably YOU in your next program which needs keyboard interaction.

                              COMMENTS?

I  REALLY  recommend  you  to use these routines, not because of their
author (no, I am not conceited), just because of the sake of the user.
The  Amiga  has  the  ability  to support user defined keymapping, you
should support it as well - if not, it would be of no use at all.

Many  programs  filter  the  characters  the  user  has  typed  on the
keyboard.   These  programs  expect  only 7-bit ASCII characters to be
valid.   A  cruel  fallacy  as  I  see it.  Diga!, for example, uses a
console handler to determine the input coming in from the keyboard but
filters  international characters.  This keeps me from telling the BBS
systems  I  use which umlauts I want to see on screen.  The emulations
are  treated  in  an  even crueler way:  they don't use the console to
determine  the  input  coming in from the keyboard.  So, if you need a
filter, use the IsASCII() function in KeyConvert.c to determine if the
character  is  in  the range of valid Amiga characters.  There are two
additional   functions:   IsPrintable()  and  ToUpper().   IsPrintable
returns TRUE if the character will have an visual or audible result if
printed  in  a  CLI  window.   ToUpper works very much the same as the
toupper()  macro  expression  but  takes  care  of  the  international
character  set  of the Amiga.  Don't be too correct if you are writing
software  emulations  for, say a VT102 terminal.  Always ask yourself:
is it more convenient for the user if I preserve the original shape of
the  project  or  would  it  be  the better idea if I try to make some
useful additions, such as international keymapping support?

        --- Hope you like the code,
	                            Olsen