dpvc@s.cc.purdue.edu.UUCP (10/02/87)
It is a "hot-key" program that binds keyboard function keys to window manipulation functions (like "send window to back", "activate next window", "bring back screen to front", etc.). Seee the document file for more information. Davide P. Cervone dpvc@tut.cc.rochester.EDU dpvc@ur-tut.UUCP DPVC@UORDBV.BITNET # This is a shell archive. # Remove everything above and including the cut line. # Then run the rest of the file through sh. #----cut here-----cut here-----cut here-----cut here----# #!/bin/sh # shar: Shell Archiver # Run the following text with /bin/sh to create: # wKeys.doc # Alternate.Keys # Default.Keys # Strange.Keys # This archive created: Thu Oct 1 17:57:33 1987 # By: Craig Norborg (Purdue University Computing Center) cat << \SHAR_EOF > wKeys.doc 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 dpvc@tut.cc.rochester.EDU Taylor Hall dpvc@ur-tut.UUCP Rochester, New York 14627 DPVC@UORDBV.BITNET (716) 275-2811 SHAR_EOF cat << \SHAR_EOF > Alternate.Keys F1: Next-Window F2: Previous-Window F3: Window-To-Front F4: Window-To-Back SHIFT-F1: Front-Window-To-Back SHIFT-F2: Back-Window-To-Front F6: Screen-To-Back F7: Screen-To-Front SHAR_EOF cat << \SHAR_EOF > Default.Keys RAmiga-LeftArrow: Previous-Window RAmiga-RightArrow: Next-Window RAmiga-UpArrow: Window-To-Front RAmiga-DownArrow: Window-To-Back RShift-RAmiga-LeftArrow: Back-Window-To-Front RShift-RAmiga-RightArrow: Front-Window-To-Back RShift-RAmiga-UpArrow: Screen-To-Front RShift-RAmiga-DownArrow: Screen-To-Back SHAR_EOF cat << \SHAR_EOF > Strange.Keys SHIFT ESC: Screen-To-Back Control,LAmiga - N: Next-Window HELP: Screen-To-Front LShift - KP0 : Window-To-Front CONTROL-!: Window-To-Back RSHIFT-RALTKEY: Back-Window-To-Front RALT-RSHIFTKEY: Back-Window-To-Front LSHIFT-LALTKEY: Front-Window-To-Back LALT-LSHIFTKEY: Front-Window-To-Back KEYUP-F10: Previous-Window KEYUP-SHIFT-F10: Next-Window LBUTTON-LSHIFTKEY: WINDOW-TO-FRONT SHAR_EOF # End of shell archive exit 0