Date: January 10, 1992

KEYUTIL - Directory
Copyright 1992  Brian Maguire
All Rights Reserved

DISCLAIMERS

KEYUTIL and this manual are presented without warranties,
expressed or implied.  The author makes no guarantee as to the
fitness of this software.

KEYUTIL can be copied freely provided the software, including
this manual, is copied in its entirety.  The user cannot be
charged, in whole or in part, except for the cost of
reproduction.  No part of this package may be used for commercial
purposes without written permission from the author.

SUMMARY

KEYUTIL contains a number of useful functions that gives the
programmer easier control over the keyboard.  Several of these
programs are intended for system RPL programs and do not include
the proper error checking, but can be used in a user RPL with
extreme caution.

COMMANDS

KRPTP

Input:  Any object

KRPTP accepts any object as input, but expects an executable
object (program, code, etc.) that neither removes or pushes any
object on the stack.  KRPTP evaluates the object input on level
one and scans the keyboard.  If the last key that was processed
is still pressed down, the program pauses, and the repeatedly
evaluated the input object until the key is released.  This
program has an advantage over the system RPL command REPEATER in
that the repeat key does not need to included as an argument.
Instead, it is recalled from the key buffer.

KRPT

Input:  Any object

KRPT functions exactly like KRPTP except it does not pause
between the first evaluation and the repeated evaluation of the
input object.

KEYSTATE

Input:     None
Output:    If a key is pressed       -   Keycode,  Real(0 or 1), 1
           If a key is not pressed   -  0

If a key is pressed, KEYSTATE will return the key's
keycode(rowcol.shift), a flag indicating whether the key was just
pressed or is being held down, and the real number 1.  If a key
is not being pressed the real number 0 is returned.  If a key is
pressed the real number on level two will equal 1 if it is a new
key stroke or 0 if it is a key that is being held down.

->KA

Input:   A list in the form { obj, keycode ....... obj , keycode }
Output:  Hex string, list

->KA formats a list containing key assignments to be used by the
program GETKASN listed later  It converts a list of object and
keycode into a hex string and a list of objects.  The input list
must resemble the list returned by RCLKEYS.  It should contain
pairs of objects and keycodes.  The hex string contains the key
code information and the offset to each key's associated object.
The list is the set of all key assignments.

KA->

Input :  hex string, list
Output:  A list in the form { obj keycode ..... obj keycode }

KA-> converts a hex string containing key assignment offsets and
a list of key objects back into a single list of key assignments.

GETKASN

Input:  system binary, system binary, hex string, list
Output  If key is found      -   key object, TRUE
        If key is not found  -  FALSE

This program is intended to be used in a system RPL program.  It
accepts a key number and shift plane on levels four and three, a
hex string containing key data and the offset to the key object
on level two, and a list of key assignments on level one.  The
arguments on level one and two must be create using the program -
KA.

RASN

Input     the variables KLNK and KASN
Output:   temporarily reassigns selected keys

RASN is an example program that demonstrates the usefulness of
GETKASN.  The key that you want to reassign must first be created
using ->KA.  the list of key object must them be stored in KASN
while the hex string representing the offsets must be stored in
KLNK.  Running RASN after the key definitions have been stored in
KASN and KLNK will set temporarily reassign the selected keys.
Running RASN will the keys are reassigned will restored the
normal keyboard.

->KEYMAP

Input:   List containing 294 key objects
Output:  Hex string

This program creates a hex string that contains the offsets for a
list of 294 key object,.  This hex string, along with a list of
key objects are used by GETKMAP to redefine the entire keyboard.

GETKMAP

Input:    system binary, system binary, hex string, list
Output:   key object

This program is intended to be used in a system RPL program.
When redefining the entire keyboard GETKMAP has less overhead
than  GETKASN.  It expects a key number and shift plane on levels
four and three, a hex string on level two, and a list of 294 key
objects on level one.  The proper key object is returned to level
one.  NOTE: the hex string input on level two must be created
using ->KEYMAP.

RMAP

Input:  the hex string stored in KYOFST and the list stored in KYOBS
Output: the entire keyboard is redefined

RMAP is an example of how GETMAP can be used.  First, you must
create a list of 294 objects representing the keyboard.  The
first 49 object are assigned to the keys with a shift state of 1,
the next 49 object for keys with a shift state of 2, and so on.
This list must then be stored in KEYOBS.  Next, recall the list
and calculate the offsets to each key object using the program -
>KEYMAP.  The resultant hex string must be stored in KYOFST.
Finally, running RMAP will redefine the keyboard.  Running RMAP
while the keyboard is redefined will restore the standard key
definitions.

NOTE! If a key object list is used by any of these programs
contain global names which are later converted into XLIB names
with the USRLIB the key object offsets that were calculated with
->KA or ->KEYMAP will be incorrect and will cause you program to
crash.  To correct this problem you must recall the key object
list from the library version using the HACKIT or the SRPL
library, calculate new key object offsets, and then store them
into the original directory version.  Now you can send the
directory to a PC and convert it into a library using USRLIB
again.  This new version should work fine.

Enjoy,

Brian Maguire
139 Kingsbury
Dearborn, MI 48128