Frozen Fish 1: Amiga/FrozenFish-Apr94.iso/bbs/alib/d1xx/d128/wkeys.lha/wKeys/wKeys.doc

Text File | 1988-01-02 | 13KB | 287 lines

OVERVIEW:

WKEYS is a program that allows you to manipulate windows through the use of
keyboard function keys rather than by using the mouse.  This way, you can
activate windows, move them from front to back and vice-versa, and move
screens from front to back, all without having to move your hands from the
keyboard, and without having to move windows around so that you can see their
depth gadgets.  It also lets you move windows or screens that do not have
depth gadgets.  WKEYS knows how to perform eight different window and screen
functions.  The key bindings are user definable, so you can make any key (or
keys) perform any of the functions that you want.


HOW TO USE WKEYS:

To use WKEYS, you must have WKEYS in your C: directory (or the current PATH,
and WKEYS-HANDLER in your L: directory (or the current directory).  Once this
is done, simply type:

    1> wKeys

WKEYS should display a message telling you its version number and the date it
was last modified.  Once this message is displayed, the window "hot-keys" will
be active.  If you wish to de-activate the hot-keys, simply issue the WKEYS
command again.  WKEYS should respond by telling you that the hot-keys have
been removed.

WKEYS knows how to perform the following window and screen manipulation
functions:

    Next-Window           Activates the window behind the currently-active one.

    Previous-Window       Activates the window above the currently-active one.

    Window-To-Front       Moves the current window to the front of the screen.

    Window-To-Back        Moves the current window to the back of the screen.

    Screen-To-Front       Moves the back-most screen to the front and activates
                          its top-most window.

    Screen-To-Back        Moves the front screen to the back and activates
                          the top-most window on the screen that is revealed.

    Back-Window-To-Front  Brings the back-most window to the front and
                          activates it.

    Front-Window-To-Back  Sends the top-most window to the back and activates
                          the next window down (the new top window).


By default, these are bound to the arrow keys when you are holding down the
right amiga key, or the right amiga key and the right shift key in the
following manner:

    RAmiga-LeftArrow:           Previous-Window
    RAmiga-RightArrow:          Next-Window
    RAmiga-DownArrow:           Window-To-Back
    RAmiga-UpArrow:             Window-To-Front

    RShift-RAmiga-LeftArrow:    Back-Window-To-Front
    RShift-RAmiga-RightArrow:   Front-Window-To-Back
    RShift-RAmiga-DownArrow:    Screen-To-Back
    RShift-RAmiga-UpArrow:      Screen-To-Front

Note:  normally these keys cause the mouse pointer to move without your having
to move the mouse itself.  When the default WKEYS are in effect, however, you
will have to use the LEFT amiga key (together with the arrow keys) to move the
mouse pointer in this fashion.  If you prefer to use the right amiga key for
moving the pointer, you can use the WKEYS re-binding feature (see below) to
change the default key bindings to something that better suits your tastes.


CHANGING THE DEFAULT KEY BINDINGS:

Not everyone finds the default WKEYS to be optimally placed on the keyboard.
For this reason, WKEYS allows you to specify which keys should perform what
functions.  To do this, you must use a key-binding file.  You tell WKEYS what
key binding file you want to use by specifying its name when you call WKEYS.
For instance:

    1> wKeys Alternate.Keys

would cause WKEYS to load the key bindings that are specified in the file
named "Alternate.Keys" in the current directory.

A key-binding file is a standard ASCII text file that you create using any
text editor.  Each line binds a key to a function and should have the
following form:

    qualifiers-keyname:  function

where "qualifiers" is a (possibly empty) list of key-qualifier names,
"keyname" is the name of any key on the Amiga keyboard, and "function" is
one of the eight functions listed above.  For example,

    F1: Screen-To-Front
    LAmiga-F1: Screen-To-Back
    SHIFT-CONTROL-N: Next-Window

all are legal key bindings.

The valid qualifier names are:

    LShift          left shift key
    RShift          right shift key
    CapsLock        caps-lock key
    Control         CTRL key
    LAlt            left ALT key
    RAlt            right ALT key
    LAmiga          left Amiga key
    RAmiga          right Amiga key
    NumericPad      the key is on the numeric keypad
    Repeat          the key is being auto-repeated
    Interrupt       (I don't know what it means, but it's in InputEvent.h)
    MultiBroadCast  (ditto)
    MButton         the middle mouse button is down (future expansion)
    RButton         the right mouse button is down
    LButton         the left mouse button is down
    RelativeMouse   (a mouse movement was relative, not absolute)

    LCommand        same as LAmiga
    RCommand        same as RAmiga
    Shift           either shift key
    Amiga           either Amiga key
    Alt             either ALT key

    KeyUp           the key is being released

Qualifiers may be separated by spaces, commas, or dashes.

The key name can be either a single, printable ASCII character (representing
the key with that legend on it), or one of the following names:

    BACKSPACE, DELETE, ENTER, ESCAPE, HELP, RETURN, SPACE, TAB,
    F1, F2, F3, F4, F5, F6, F7, F8, F9, F10,
    KP0, KP1, KP2, KP3, KP5, KP5, KP6, KP7, KP8, KP9,
    LEFTARROW, RIGHTARROW, DOWNARROW, UPARROW,
    BS, DEL, ESC,  COLON, COMMA, DASH, DOT, MINUS,
    CAPSLOCKKEY, CONTROLKEY, LALTKEY, LAMIGAKEY, LCOMMANDKEY, LSHIFTKEY,
    RALTKEY, RCOMMANDKEY, RALTKEY, RSHIFTKEY

where "Fn" is a function key, "KPn" is a number key on the keypad, "DASH" is
the dash on the main keyboard (the same key as the underscore), "DOT" is the
keypad dot, and "MINUS" is the keypad minus key.  "CAPSLOCKKEY", etc. are
the qualifier keys (for instance, you can make "RSHIFT-RALTKEY" map to some
function).

"COLON", "COMMA", and "DASH" are named because they are special characters
within the key-binding file, and as such, can not be specified in the usual
manner.

If you specify a single character name for a special symbol that requires a
shift key to be pressed, the SHIFT qualifier is added automatically.  For
example,  "CONTROL-*" and "CONTROL-SHIFT-*" are equivalent, as are "#" and
"SHIFT-#".  Upper-case letters do not automatically include SHIFT, however.
If you want an alphabetic key to require a shift key to be pressed, you must
explicitly include the SHIFT qualifier.

Note:  "NUMERICPAD-0" is NOT the same as "KP0".  The former specifies the zero
key on the main keyboard with the NUMERICPAD qualifier set (a non-existant
combination), whereas the latter specifies the numeric keypad zero key (with
no particular qualifier keys required).

You can define as many key bindings as you want (more than one key can be
bound to the same function).  Each key definition must be on its own line,
however.

See the files DEFAULT.KEYS, ALTERNATE.KEYS, and STRANGE.KEYS for examples
of some key binding files.


HOW WKEYS WORKS:

WKEYS installs an input handler into the chain of handlers called by the Input
Device.  This handler is added at priority 51, so it receives input events
before Intuition does.  The input handler looks at each raw-key event and
compares it to the keys defined by WKEYS.  When it finds one that is defined,
it performs the function bound to that key and removes the raw-key event from
the event list.  When all the events have been checked, it passes the
(modified) list back to the input device, which passes it to Intuition for
further processing.

When you call WKEYS, it creates an array of key bindings (either from the
default bindings, or from the key-binding file that you specify).  Each key in
the array takes up 8 bytes of memory.  WKEYS then calls LoadSeg() to load
WKEYS-HANDLER, which is the actual input handler, and passes it the key array.
It installs WKEYS-HANDLER as an Input Device input handler, and then exits.

WKEYS uses a named, public message-port to store the address of the input
handler and the key array.  When you call WKEYS a second time, it finds that
public message-port and retrieves the pointers to the handler and key array,
removes the handler, calles UnLoadSeg() on it, and deallocates the key array.

Since lots of keystrokes may go through the handler, and since most of those
will not be one of the hot-keys, the handler must be able to determine as
quickly as possible whether a key event matches one of defined keys.  For this
reason, the key array is sorted by key code and qualifiers, and is searched
via a binary search method.  Thus, for example, when the eight default keys
are used, no more than three comparisons will need to be made to determine
which hot-key, if any, has been pressed.  For sixteen keys, only four
comparisons need be made.

HOW TO ADD YOUR OWN FUNCTIONS:

You can define your own hot-key functions by adding them into WKEYS-HANDLER.C
(just after the routine called FrontWindowToBack()).  Your routine should
expect no parameters, and should return no value (i.e., it should be a
function of type "void").  Your routine will be called from within the Input
Handler, therefore, it should NOT call any function that might call Wait().
This includes DOS calls, WaitIO(), LockLayers(), and all graphics primitives
that could block while Layers are locked.

Once your routine is added to the handler, include it at the end of the
Action[] array in WKEYS-HANDLER.C and add a #define statement to WKEYS.H (at
the bottom, just after FRONTTOBACK).  Then add an additional entry in the
Action[] array in BINDWKEYS.C.  The character string is what you use within
your key-binding file to specify your new function.  The code number is the
number that you have #defined in WKEYS.h.  Be sure that your new entry is
placed in the list so that the list remains in alphabetical order.

Once you have made these changes, you can use a key-binding file to bind keys
to your new function just as though it was one of WKEYS' original functions.
You can change the default key-bindings to include your new function by
following the instructions in the next section.


HOW TO CHANGE THE DEFAULT KEY BINDINGS:

The default key-bindings are stored in an array called DefaultKey[] in the
file BINDWKEYS.C.  You can change the default key setup by changing this
array (you can add new keys, remove old ones, or change the keys or qualifiers
used for the current default keys).  The HOTKEY() macro is used to make
defining keys easy.  You specify the qualifiers first (OR them together), then
the keyboard scan-code for the key, then the function number (as #defined in
WKEYS.H).  The DefaultKey[] array must be sorted by KeyCode.  This means that
it is sorted by scan-code first, then qualifier value.  If you are specifying
qualifiers other than RAMIGA and RSHIFT, you should add them to the HOTKEY()
macro #define statement.


KNOWN PROBLEMS:

When you use the SHIFT qualifier, WKEYS really defines two key-bindings, one
using LSHIFT and one using RSHIFT.  The AMIGA and ALT qualifiers produce
similar results with the LAMIGA, RAMIGA, LALT, and RALT qualifiers.  Currently,
you can not specify a key using more than one of these special, multi-key
qualifiers (SHIFT, AMIGA, ALT).  Instead, you must explicitly define the keys
in terms of LSHIFT, RSHIFT, LAMIGA, etc.  For example, SHIFT-AMIGA-N would
have to be specified as LSHIFT-LAMIGA-N, LSHIFT-RAMIGA-N, RSHIFT-LAMIGA-N, and
RSHIFT-RAMIGA-N.  Note that some keyboard symbols implicity include the SHIFT
qualifier, as described above ("#" is the same as "SHIFT-#").


COMPILING AND LINKING WKEYS:

WKEYS was developed using Lattice C version 3.10.  I have tried to use longs
when required by the Manx Aztec C compiler, but I do not own a copy of it,
so I can not verify that WKEYS will compile properly with it.

To compile and link WKEYS, type:

    1> lc -v -r wKeys wKeys-Handler BindWKeys mSort
    1> asm HandlerStub
    1> blink with wKeys.lnk
    1> blink with wKeys-Handler.lnk

The -v is required to suppress stack checking (since the handler will run
on the Input Device's stack), but the -r is optional.

Place wKeys in your C: directory, and wKeys-Handler in your L: directory.

If you compile BindWKeys with -dNO_FILE, the file-reading code will not be
included in the executable.  In this case, you will not be able to load key
bindings from a file, but the program will be smaller, and will execute
faster.  You can change the default key bindings as described above to make
the stripped-down version load with your favorite key-bindings.


AUTHOR:

Davide P. Cervone
University of Rochester Computing Center           [e-mail]
Taylor Hall                                        [e-mail]
Rochester, New York  14627                         [e-mail]
[phone]