Stars of Shareware: Animation & Sound/SOS-ANIM_SOUND.ISO/best_50/ody200.zip/ODYDOC.LZH/MAKEKEY.DOC

Text File | 1991-10-07 | 6KB | 130 lines

MAKEKEY is a utility for creating Odyssey compatible keyboard definition
files. These files allow you to configure Odyssey such that any key
combination can be substituted with a user defined string of characters.

MAKEKEY accepts as input a text file describing the keyboard mapping, and
it outputs a file with the extension .KEY, which you can use within
Odyssey, at the General menu, or in a script by invoking the LoadKeyDef()
function.

Keyboard definitions are also loaded automatically if its name matches the
name of a terminal emulation being loaded, that is, if you load a terminal
emulation called XYZ.TRM, and a keyboard definition file exists called
XYZ.KEY then the keyboard file will also be loaded. This allows you to
produce your own variants of the standard terminal emulations for use with
special hardware, eg protocol converters. You would normally copy the
standard emulation to a new name, eg VT100.TRM to VT_TSO.TRM, and prepare
a keyboard definition called VT_TSO.KEY. Doing it this way ensures that
the keyboard definition is not loaded when you want it to behave like a
standard terminal.

The format of the keyboard definition source file is very simple, it is
just a text file with one definition per line. The source file may also
contain blank lines, and lines starting with a semicolon ';' are ignored
so such lines may be used for comments.

Below are some sample definitions:-

<CtrlF1> = <Esc>[0~
<CtrlF2> = <Esc>[1~
<CtrlF3> = <Esc>[2~
<CtrlF4> = <Esc>[3~
<ShiftF1> = <AltS>E
<AltShiftE> = XYZ123

Each line contains the key combination to be defined, an equals sign, and
then the definition itself, which is made up of one or more key symbols (a
letter or a key combination). Note that the definition on the right hand side
does NOT need to be an ASCII sequence - you can have one keystroke simulate
a number of other keystrokes whether those are ASCII characters or not - just
enclose non-ASCII keys in angle brackets using the convention described below.

A key combination starts with '<' and ends with '>'. In between should be
a key name optionally prefixed by 'Ctrl', 'Alt' or 'Shift', or any
combination of those. There are some valid key definitions:-

       <ShiftTab>
       <AltShiftTab>
       <ShiftAltTab>
       <ShiftCtrlTab>
       <<>

Key combinations can contain the words 'Alt', 'Shift' and 'Ctrl' in any
order, but the combination must end with a key name (the shift keys are
not sufficient on their own). Table 1 lists the function key names
recognised by MAKEKEY.

------------- TABLE 1 - Recognised Function Key Names -----------------------

   (* These are the standard functions keys *)

   F1        F2         F3        F4        F5        F6        F7
   F8        F9         F10       Esc       Tab       BS        UpArr
   DownArr   LeftArr    RightArr  Ins       Home      PgUp      Del
   End       PgDn       Enter


   (* These keys are all generated on the keypad when NUMLOCK is in effect.
      Since MAKEKEY recognises these keys it is possible to have '7' on the
      keypad generate a different sequence from '7' on the main keyboard. *)

   K0        K1         K2        K3        K4        K5        K6
   K7        K8         K9        KDot      KMinus    KPlus


   (* The following keys are only useful if you have an Enhanced Keyboard,
      they include three further keypad keys (KSlash, KStar and KEnter). *)

   F11       F12        ELeftArr  EHome      EEnd      EUpArr    EDownArr
   EPgUp     EPgDn      ERightArr KSlash     KStar     KEnter

-----------------------------------------------------------------------------


Once you have prepared your source definition file you then run the
MAKEKEY utility, eg:-

    C:\ODYSSEY> makekey mydef.txt

Provided that there are no errors in the definition then Odyssey will
create a file called MYDEF.KEY.

In operation, Odyssey's key substitution is not nested, ie a definition
such as:-

    <Esc> = <Esc>

Is essentially a NOP, it does not produce a infinite recursive loop. In
other words only keys actually read from the keyboard may be substituted,
keys which are themselves substitutes are never replaced.

Odyssey can distinguish key combinations not normally distinguished by the
keyboard BIOS. It does this by reading the keyboard flags at the same time it
reads the key, and combines the character code, scan code and flags into one
big keyboard code. Even when the BIOS generates the same scancode for ALT-F1
as it does for ALT-SHIFT-F1, Odyssey can still tell the difference, because
the shift states are different. Ody could have done the same trick by taking
over the keyboard interrupt, but that introduces problems with foreign
keyboard layouts - the method described still works when the Dos KEYB driver
is used.

You should also be aware that the MAKEKEY utility makes no attempt to verify
that a key combination you define can actually be generated by your keyboard
or BIOS. For example, my keyboard does not generate a keystroke if I press
CTRL,ALT and F1 together, but MAKEKEY will not prevent me from using this
combination in a definition, eg:-

      <CtrlAltF1> = XYZ

This leaves open the possibility that you can use a replacement keyboard
interrupt 9h handler which generates keystrokes for combinations which are
normally ignored, thereby increasing the number of combinations able to be
redefined. The extra keystrokes would have to generate standard scancodes (ie
they should generate the same scancode as a legal sequence on that key - say
the code for Alt-F1), and Odyssey distinguish the non-standard combination
by checking the keyboard flags as described above.

Don Milne.
24-Mar-1990.