home *** CD-ROM | disk | FTP | other *** search
/ Frozen Fish 1: Amiga / FrozenFish-Apr94.iso / bbs / alib / d5xx / d500 / wiconify.lha / wIconify / wKeys.lzh / wKeys.doc < prev   
Text File  |  1991-04-21  |  15KB  |  321 lines

  1. OVERVIEW:
  2.  
  3. WKEYS is a program that allows you to manipulate windows through the use of 
  4. keyboard function keys rather than by using the mouse.  This way, you can
  5. activate windows, move them from front to back and vice-versa, and move
  6. screens from front to back, all without having to move your hands from the
  7. keyboard, and without having to move windows around so that you can see their
  8. depth gadgets.  It also lets you move windows or screens that do not have
  9. depth gadgets.  WKEYS knows how to perform twelve different window and screen
  10. functions.  The key bindings are user definable, so you can make any key (or
  11. keys) perform any of the functions that you want.
  12.  
  13.  
  14. HOW TO USE WKEYS:
  15.  
  16. To use WKEYS, you must have WKEYS in your C: directory (or the current PATH, 
  17. and WKEYS-HANDLER in your L: directory (or the current directory).  Once this 
  18. is done, simply type:
  19.  
  20.     1> wKeys
  21.  
  22. WKEYS should display a message telling you its version number and the date it
  23. was last modified.  Once this message is displayed, the window "hot-keys" will
  24. be active.  If you wish to de-activate the hot-keys, simply issue the WKEYS
  25. command again.  WKEYS should respond by telling you that the hot-keys have
  26. been removed.
  27.  
  28. WKEYS knows how to perform the following window and screen manipulation
  29. functions:
  30.  
  31.     Next-Window           Activates the window behind the currently-active one.
  32.  
  33.     Previous-Window       Activates the window above the currently-active one.
  34.  
  35.     Window-To-Front       Moves the current window to the front of the screen.
  36.  
  37.     Window-To-Back        Moves the current window to the back of the screen.
  38.  
  39.     Screen-To-Front       Moves the back-most screen to the front and activates
  40.                           its top-most window.
  41.  
  42.     Screen-To-Back        Moves the front screen to the back and activates
  43.                           the top-most window on the screen that is revealed.
  44.  
  45.     Back-Window-To-Front  Brings the back-most window to the front and 
  46.                           activates it.
  47.  
  48.     Front-Window-To-Back  Sends the top-most window to the back and activates
  49.                           the next window down (the new top window).
  50.  
  51.     Close-Window          Sends a CLOSEWINDOW message to the active window
  52.                           (provided the window accepts them, and is not
  53.                           a BACKDROP window).
  54.  
  55.     Window-To-Icon        Iconifies the current window (if wIconify is running).
  56.     
  57.     Icon-To-Window        Restores the window associated with the selected
  58.                           window icon (if wIconify is running).
  59.  
  60.     Select-Next-Icon      Selects the next window icon on the screen (if
  61.                           wIconify is running).
  62.  
  63.  
  64. By default, these are bound to the arrow keys when you are holding down the
  65. right amiga key, or the right amiga key and the right shift key in the
  66. following manner:
  67.  
  68.     RAmiga-LeftArrow:           Previous-Window
  69.     RAmiga-RightArrow:          Next-Window
  70.     RAmiga-DownArrow:           Window-To-Back
  71.     RAmiga-UpArrow:             Window-To-Front
  72.  
  73.     RShift-RAmiga-LeftArrow:    Back-Window-To-Front
  74.     RShift-RAmiga-RightArrow:   Front-Window-To-Back
  75.     RShift-RAmiga-DownArrow:    Screen-To-Back
  76.     RShift-RAmiga-UpArrow:      Screen-To-Front
  77.     
  78.     RAmiga-DELETE:              Close-Window
  79.     
  80.     RAmiga-RETURN:              Window-To-Icon
  81.     RAmiga-BACKSPACE:           Icon-To-Window
  82.     RAmiga-TAB:                 Select-Next-Icon
  83.  
  84. Note:  normally these keys cause the mouse pointer to move without your having 
  85. to move the mouse itself.  When the default WKEYS are in effect, however, you
  86. will have to use the LEFT amiga key (together with the arrow keys) to move the
  87. mouse pointer in this fashion.  If you prefer to use the right amiga key for 
  88. moving the pointer, you can use the WKEYS re-binding feature (see below) to
  89. change the default key bindings to something that better suits your tastes.
  90.  
  91.  
  92. CHANGING THE DEFAULT KEY BINDINGS:
  93.  
  94. Not everyone finds the default WKEYS to be optimally placed on the keyboard. 
  95. For this reason, WKEYS allows you to specify which keys should perform what
  96. functions.  To do this, you must use a key-binding file.  You tell WKEYS what 
  97. key binding file you want to use by specifying its name when you call WKEYS.
  98. For instance:
  99.  
  100.     1> wKeys Alternate.Keys
  101.  
  102. would cause WKEYS to load the key bindings that are specified in the file
  103. named "Alternate.Keys" in the current directory.
  104.  
  105. A key-binding file is a standard ASCII text file that you create using any 
  106. text editor.  Each line binds a key to a function and should have the 
  107. following form:
  108.  
  109.     qualifiers-keyname:  function
  110.  
  111. where "qualifiers" is a (possibly empty) list of key-qualifier names, 
  112. "keyname" is the name of any key on the Amiga keyboard, and "function" is
  113. one of the eight functions listed above.  For example,
  114.  
  115.     F1: Screen-To-Front
  116.     LAmiga-F1: Screen-To-Back
  117.     SHIFT-CONTROL-N: Next-Window
  118.  
  119. all are legal key bindings.
  120.  
  121. The valid qualifier names are:
  122.  
  123.     LShift          left shift key
  124.     RShift          right shift key
  125.     CapsLock        caps-lock key
  126.     Control         CTRL key
  127.     LAlt            left ALT key
  128.     RAlt            right ALT key
  129.     LAmiga          left Amiga key
  130.     RAmiga          right Amiga key
  131.     NumericPad      the key is on the numeric keypad
  132.     Repeat          the key is being auto-repeated
  133.     Interrupt       (I don't know what it means, but it's in InputEvent.h)
  134.     MultiBroadCast  (ditto)
  135.     MButton         the middle mouse button is down (future expansion)
  136.     RButton         the right mouse button is down
  137.     LButton         the left mouse button is down
  138.     RelativeMouse   (a mouse movement was relative, not absolute)
  139.  
  140.     LCommand        same as LAmiga
  141.     RCommand        same as RAmiga
  142.     Shift           either shift key
  143.     Amiga           either Amiga key
  144.     Alt             either ALT key
  145.     
  146.     KeyUp           the key is being released
  147.  
  148. Qualifiers may be separated by spaces, commas, or dashes.
  149.  
  150. The key name can be either a single, printable, ASCII character (representing
  151. the key with that legend on it), or one of the following names:
  152.  
  153.     BACKSPACE, DELETE, ENTER, ESCAPE, HELP, RETURN, SPACE, TAB,
  154.     F1, F2, F3, F4, F5, F6, F7, F8, F9, F10,
  155.     KP0, KP1, KP2, KP3, KP5, KP5, KP6, KP7, KP8, KP9,
  156.     LEFTARROW, RIGHTARROW, DOWNARROW, UPARROW,
  157.     BS, DEL, ESC,  COLON, COMMA, DASH, DOT, MINUS,
  158.     CAPSLOCKKEY, CONTROLKEY, LALTKEY, LAMIGAKEY, LCOMMANDKEY, LSHIFTKEY,
  159.     RALTKEY, RCOMMANDKEY, RALTKEY, RSHIFTKEY
  160.  
  161. where "Fn" is a function key, "KPn" is a number key on the keypad, "DASH" is
  162. the dash on the main keyboard (the same key as the underscore), "DOT" is the
  163. keypad dot, and "MINUS" is the keypad minus key.  "CAPSLOCKKEY", etc. are
  164. the qualifier keys (for instance, you can make "RSHIFT-RALTKEY" map to some 
  165. function).
  166.  
  167. "COLON", "COMMA", and "DASH" are named because they are special characters
  168. within the key-binding file, and as such, can not be specified in the usual
  169. manner.
  170.  
  171. If you specify a single character name for a special symbol that requires a
  172. shift key to be pressed, the SHIFT qualifier is added automatically.  For
  173. example,  "CONTROL-*" and "CONTROL-SHIFT-*" are equivalent, as are "#" and
  174. "SHIFT-#".  Upper-case letters do not automatically include SHIFT, however.
  175. If you want an alphabetic key to require a shift key to be pressed, you must 
  176. explicitly include the SHIFT qualifier.
  177.  
  178. Note:  "NUMERICPAD-0" is NOT the same as "KP0".  The former specifies the zero
  179. key on the main keyboard with the NUMERICPAD qualifier set (a non-existant
  180. combination), whereas the latter specifies the numeric keypad zero key (with
  181. no particular qualifier keys required).
  182.  
  183. You can define as many key bindings as you want (more than one key can be
  184. bound to the same function).  Each key definition must be on its own line,
  185. however.
  186.  
  187. See the files DEFAULT.KEYS, ALTERNATE.KEYS, and STRANGE.KEYS for examples
  188. of some key binding files.
  189.  
  190.  
  191. HOW WKEYS WORKS:
  192.  
  193. WKEYS installs an input handler into the chain of handlers called by the Input
  194. Device.  This handler is added at priority 51, so it receives input events 
  195. before Intuition does.  The input handler looks at each raw-key event and 
  196. compares it to the keys defined by WKEYS.  When it finds one that is defined, 
  197. it performs the function bound to that key and removes the raw-key event from 
  198. the event list.  When all the events have been checked, it passes the 
  199. (modified) list back to the input device, which passes it to Intuition for 
  200. further processing.
  201.  
  202. To close a window, WKEYS sends an IntuiMessage of class CLOSEWINDOW to the
  203. active window's UserPort.  The reply port for the message is setup so that
  204. the input handler can check for when it has been replied.
  205.  
  206. To iconify a window, WKEYS calls wIconify, which does the real work of 
  207. iconifying the window.  Special calls also allow WKEYS to request wIconify
  208. to restore a window and select the next icon.
  209.  
  210. When you call WKEYS, it creates an array of key bindings (either from the
  211. default bindings, or from the key-binding file that you specify).  Each key in
  212. the array takes up 8 bytes of memory.  WKEYS then calls LoadSeg() to load 
  213. WKEYS-HANDLER, which is the actual input handler, and passes it the key array.
  214. It installs WKEYS-HANDLER as an Input Device input handler, and then exits.
  215.  
  216. WKEYS uses a named, public message-port to store the address of the input
  217. handler and the key array.  When you call WKEYS a second time, it finds that
  218. public message-port and retrieves the pointers to the handler and key array,
  219. removes the handler, calles UnLoadSeg() on it, and deallocates the key array.
  220.  
  221. Since lots of keystrokes may go through the handler, and since most of those
  222. will not be one of the hot-keys, the handler must be able to determine as 
  223. quickly as possible whether a key event matches one of defined keys.  For this
  224. reason, the key array is sorted by key code and qualifiers, and is searched
  225. via a binary search method.  Thus, for example, when the eight default keys 
  226. are used, no more than three comparisons will need to be made to determine
  227. which hot-key, if any, has been pressed.  For sixteen keys, only four
  228. comparisons need be made.
  229.  
  230.  
  231. HOW TO ADD YOUR OWN FUNCTIONS:
  232.  
  233. You can define your own hot-key functions by adding them into WKEYS-HANDLER.C 
  234. (just after the routine called FrontWindowToBack()).  Your routine should
  235. expect no parameters, and should return no value (i.e., it should be a
  236. function of type "void").  Your routine will be called from within the Input
  237. Handler, therefore, it should NOT call any function that might call Wait(). 
  238. This includes DOS calls, WaitIO(), LockLayers(), and all graphics primitives
  239. that could block while Layers are locked. 
  240.  
  241. Once your routine is added to the handler, include it at the end of the
  242. Action[] array in WKEYS-HANDLER.C and add a #define statement to WKEYS.H (at
  243. the bottom, just after FRONTTOBACK).  Then add an additional entry in the
  244. Action[] array in BINDWKEYS.C.  The character string is what you use within
  245. your key-binding file to specify your new function.  The code number is the
  246. number that you have #defined in WKEYS.H.  Be sure that your new entry is
  247. placed in the list so that the list remains in alphabetical order.
  248.  
  249. Once you have made these changes, you can use a key-binding file to bind keys
  250. to your new function just as though it was one of WKEYS' original functions. 
  251. You can change the default key-bindings to include your new function by
  252. following the instructions in the next section.
  253.  
  254.  
  255. HOW TO CHANGE THE DEFAULT KEY BINDINGS:
  256.  
  257. The default key-bindings are stored in an array called DefaultKey[] in the
  258. file BINDWKEYS.C.  You can change the default key setup by changing this
  259. array (you can add new keys, remove old ones, or change the keys or qualifiers
  260. used for the current default keys).  The HOTKEY() macro is used to make
  261. defining keys easy.  You specify the qualifiers first (OR them together), then
  262. the keyboard scan-code for the key, then the function number (as #defined in
  263. WKEYS.H).  The DefaultKey[] array must be sorted by KeyCode.  This means that
  264. it is sorted by scan-code first, then qualifier value.  If you are specifying
  265. qualifiers other than RAMIGA and RSHIFT, you should add them to the HOTKEY()
  266. macro #define statement.
  267.  
  268.  
  269. KNOWN PROBLEMS:
  270.  
  271. When you use the SHIFT qualifier, WKEYS really defines two key-bindings, one
  272. using LSHIFT and one using RSHIFT.  The AMIGA and ALT qualifiers produce
  273. similar results with the LAMIGA, RAMIGA, LALT, and RALT qualifiers.  Currently,
  274. you can not specify a key using more than one of these special, multi-key
  275. qualifiers (SHIFT, AMIGA, ALT).  Instead, you must explicitly define the keys
  276. in terms of LSHIFT, RSHIFT, LAMIGA, etc.  For example, SHIFT-AMIGA-N would
  277. have to be specified as LSHIFT-LAMIGA-N, LSHIFT-RAMIGA-N, RSHIFT-LAMIGA-N, and 
  278. RSHIFT-RAMIGA-N.  Note that some keyboard symbols implicity include the SHIFT
  279. qualifier, as described above ("#" is the same as "SHIFT-#").
  280.  
  281.  
  282. COMPILING AND LINKING WKEYS:
  283.  
  284. WKEYS was developed using Lattice C version 3.10.  I have tried to use longs
  285. when required by the Manx Aztec C compiler, but I do not own a copy of it,
  286. so I can not verify that WKEYS will compile properly with it.
  287.  
  288. To compile and link WKEYS, type (these commands can be found in wKeys.make):
  289.  
  290.     1> lc -v -b0 -r wKeys wKeys-Handler BindWKeys mSort
  291.     1> lc -v -b0 -dWKEYS_CALLS wIconCalls
  292.     1> asm wStub
  293.     1> blink with wKeys.lnk
  294.     1> blink with wKeys-Handler.lnk
  295.  
  296. The -v and -b0 are required to suppress stack checking (since the handler will
  297. run on the Input Device's stack) and base-relative addressing, but the -r is
  298. optional.
  299.  
  300. wIconCalls.c is distributed with the rest of the wIconify source.  It is the 
  301. programmer's interface to wIconify.
  302.  
  303. Place wKeys in your C: directory, and wKeys-Handler in your L: directory.
  304.  
  305. If you compile BindWKeys with -dNO_FILE, the file-reading code will not be
  306. included in the executable.  In this case, you will not be able to load key
  307. bindings from a file, but the program will be smaller, and will execute
  308. faster.  You can change the default key bindings as described above to make
  309. the stripped-down version load with your favorite key-bindings.
  310.  
  311.  
  312. AUTHOR:
  313.  
  314. wKeys and wKeys-Handler
  315. Copyright (c) 1987,1988 by Davide P. Cervone, all rights reserved.
  316.  
  317. Davide P. Cervone
  318. Department of Mathematics, Box 1917                 ST402523@BROWNVM.BITNET
  319. Brown University                                    st402523@brownvm.brown.edu
  320. Providence, Rhode Island  02912                     dpvc@fermat.math.brown.edu
  321.