********************************************************************** WizKey Copyright 1992 by Jörg von Frantzius *************************************************************************** WizKey is SHAREWARE, see end of this document for details. *************************************************************************** AGREEMENT: By using WizKey you agree that the author will not be responsible for any damages resulting from malfunction or wrong documentation of WizKey. What is WizKey? --------------- WizKey is just another commodity, intended to speed up working with windows and screens. This is accomplished by letting the user manipulate that stuff via the keyboard instead of having to: 1. grab your mouse (i.e. get your fingers off the keyboard...) 2. look for gadgets 3. aim at these gadgets and click 4. search for windows in huge window-piles etc. Anything you can do with system gadgets becomes accessible via keyboard using WizKey, plus some additional comfort (it's a commodity!). A windowlist pops up on hotkey invocation, showing a list of all windows available on the active screen and letting you pick a window with the mouse or the keyboard (available on public screens only). The hotkey definitions are free configurable (using any text editor), allowing you to extend WizKey's functionality to your special needs in combination with its complete AREXX port. Any Arexx-script may be mapped to any key combination using normal commodities conventions (those provided by commodities.library). You may for example map a script to the hotkey "lcommand e", which will pop up your editor's window and screen and activate it, no matter on which screen you have been working on. Installation ------------ As it is a commodity, WizKey needs at least OS 2.0. Workbench: place WizKey into your Wbstartup drawer to start WizKey with every boot-up, or double-click on it everytime you want to use it. If you have installed WizKey in your WBstartup-drawer, I suggest you install its Preference file in your environment, so that WizKey will find it on boot-up: Double-click on "InstallPrefs" to copy WizKey's preference file to "env:WizKey/WizKey.prefs" and "envarc:WizKey/WizKey.prefs" The preference file contains some hotkey definitions that can't be used if WizKey can't find its preference file. Shell: put something like "run >NIL: WizKey" into your user-startup script, if you really don't like the wbstartup drawer. See "The preference file" for some locations where WizKey can find its preference file. I'm not sure how much stack exactly WizKey needs, but 4096 is definitely not enough. I suggest about 10000 bytes, if you encounter problems (Wizkey should report that) raise the stack. The preference file + Arexx Port -------------------------------- WizKey's Arexx host port is named "WizKey" (case sensitive). WizKey tries to locate a preference file following the rules given in the user interface style guide, or at least my interpretation of these. Using tooltypes or commandline parameters you may specify a certain preference file to be used by WizKey, or a directory containing the file "WizKey.prefs". Tooltype example: "SETTINGS=Work:stuff/WizKey.prefs" commandline example: "run WizKey settings=Work:stuff/WizKey.prefs" If no preference file is specified, WizKey will look for it in its program directory, if it can't be found there it will look for "ENV:WizKey/WizKey.prefs" in the last place. If no preference file at all could be found, WizKey uses its built-in defaults. The preference file is a plain ascii file editable with any ascii-editor. It consists of hotkey-definitions using the template: commandName = hokey definition e.g.: WindowList = lcommand help The example given will open the windowlist by pressing the keys left amiga + help key (which is the built-in default for this command, btw). Hotkey definitions using plain command names without arguments like the example above will override WizKey's built-in hotkey defaults. Anything else WizKey does not "know" will be considered being some kind of arexx script, i.e. string file or physical file. The hotkey defaults exist for simple commands only that do not require arguments. If a line does not contain a "=" or no valid Input Description String, it will be completely ignored. Small Arexx-Scripts may be put into the preference file using so-called string files, e.g.: "ActivateWindow 'Shell'; WinToFront; ScrToFront" = lcommand s Pressing left amiga+"s", this example will activate the first window containing the string "Shell", pop it to front and pop its screen to front. Note that in string files you do not need to say "Address 'WizKey'" to have access to WizKey's arexx-commands, since these string files will be executed from within Wizkey. String files are always surrounded by quotemarks. As well a filename may be specified, which WizKey will try to execute as an Arexx-script., e.g: rexx:doSomeThing.wiz = lalt s WizKey will try to execute the file "rexx:doSomeThing.wiz" as an Arexx-Script. Filenames do not need to be surrounded by quotemarks. WizKey's built-in hotkey defaults use some combinations of keys that are not accessible through input description strings, e.g. WinToFront's hotkey would be something like "lcommand lshift", which is not a valid input description string. I'm sorry about that, but commodities.library does not support that (yet?); if somebody needs to define hotkeys like that himself, I might add something non-standard to accomplish that. WizKey's commands in detail --------------------------- Following is a list of WizKey's functions, including their arexx command names and default hotkeys. As a lot of Intuition procedures run asynchronously (sp?) from WizKey, every arexx-command of WizKey is followed automatically by a certain delay that makes sure the Intuition procedure really has completed. This is important since some combinations of Intuition procedures (which are invoked by WizKey's Arexx-commands) depend on the completion of the previous command, e.g. "CenterWindow X; ExpandBottom": the window would be expanded to the bottom before it is centered in the middle of the screen, because WizKey examines the Window's data before Intuition changes them. However, this delay often slows down arexx-scripts unnecessarily, so you can switch it off by providing the "ND=NoDelay/S" argument with your invocation, e.g.: "WinToFront nd; ScrToFront" - here the delay would not be necessary so it is switched off. NAME: Quit, lcommand x Arguments: Force/S WizKey removes itself from memory. You'll never use this one, anyway ;-) If called with "Force/S" WizKey won't ask silly questions before removing itself. Windowlist stuff: NAME: WindowList, lcommand help Arguments: ND=NoDelay/S If the active screen is a public screen, a window is opened containing the titles of every window on the screen. Click on a title to pop a window to the front and activate it; the active window is marked with a "*". To activate the windowlist, which is not activated when opened, press the hotkey again, then cursor up and down to scroll through the windowlist. The default preference file conains some little arexx-scripts enabling you to pick windows with the keys lcommand + F1-F10 and "1"-"0", according to the numbers displayed in the windowlist. NAME: ToggleTitles, lcommand t Arguments: none By default the windowlist displays the windows' titles, with this command the display can be switched to the windows's screentitles and back. Very useful for my texteditor :-) NAME: CloseList, lcommand delete Arguments: ND=NoDelay/S Closes the windowlist. Activation stuff + shuffling:: NAME: NextWin, lcommand tab Arguments: ND=NoDelay/S Activates the next window in the windowlist, allowing you to activate any window on screen. NAME: PrecedingWin, lcommand ` (the key above tab) Arguments: ND=NoDelay/S Activates the window preceding the active window in the windowlist. NAME: TopWinToBottom, lcommand up (i.e. cursor up) Arguments: ND=NoDelay/S The window on top of the active screen's window pile is dropped to the bottom, the window now on top is activated. Handy to shuffle through the window pile. NAME: BottomWinToFront, lcommand down (i.e. cursor down) Arguments: ND=NoDelay/S The bottom window of the window pile is brought to the top and is activated. NAME: WinToFront, lcommand lshift Arguments: ND=NoDelay/S The active window is brought to the front. NAME: WinToBack, lcommand rshift Arguments: ND=NoDelay/S The active window is dropped to the bottom. NAME: CloseWindow, lcommand q Arguments: ND=NoDelay/S If the active window contains a close gadget, WizKey tries to close the window. Window sizin'n'movin': Any change of size and position performed through WizKey may be taken back one time for each window, see "RestoreWindow". NAME: ToggleClip, lcommand c Arguments: "On/S,Off/S" Determines whether certain WizKey-commands take care of the active screen's display clip, i.e. size and position of the visible portion of the screen. "On/S,Off/S" set or unset an internal boolean flag, without any arguments this flag is toggled. In Arexx-scripts this global flag may be overridden individually by each command that accepts the arguments "DClip/S,NoDClip/S". NAME: ReduceWindow, lcommand r Arguments: ND=NoDelay/S The active window is sized to its minimum. NAME: FullSize, lcommand f Arguments: ND=NoDelay/S The active window is sized to its maximum. If the display clip flag is set, FullSize will try to move the active window into the display clip and size it appropriately. NAME: Zip, lcommand z Arguments: ND=NoDelay/S Just like clicking on the active window's zip gadget. NAME: RestoreWindow, lcommand backspace Arguments: ND=NoDelay/S The window's last change of position and/or size done with WizKey is taken back. Even "RestoreWindow" itself can be taken back. Screen shuffling: NAME: ScreenToBack, rcommand up Arguments: ND=NoDelay/S The active screen is dropped behind any other screen, the screen's active window is remembered. If WizKey can remember an active window on the next screen, the window is activated, else the window covering the screen's centre is activated or the screen's first window is activated. NAME: BackScreenToFront,rcommand down Arguments: ND=NoDelay/S The bottom screen is popped to the front, activation of its window is the same as in "ScreenToBack". Arexx only commands: These commands are accessible via AREXX only, there exist no internal default hotkeys for them. Further examples for these commands can be found in the preference file. NAME: ActivateWindow Arguments: WinTitle/A,ND=NoDelay/S WizKey searches through every window on any screen for a window title that contains (!) the title given as an argument, and activates it if it finds one. "ActivateWindow 'rkben'" for example will activate the window 'Workbench', if there is one. The search is case sensitive. NAME: GetWinTitle Arguments: none Requiring "options result" before invocation, this function returns the title of the active window. Example (to type in the shell): rx "address 'WizKey'; options results; GetWinTitle; say result" this will print the name of the shell window in the shell. NAME: PickWindow Arguments: Number/A/N,ND=NoDelay/S The window at the position in the windowlist will be activated and popped to the front. See preference file for examples. NAME: ScrToFront Arguments: ScrTitle,ND=NoDelay/S If provided with a screentitle argument, this command will pop the first screen containing the argument string in its title to the front. Without any argument, this will bring the active window's screen to front. NAME: RelSizeWindow Arguments: Numerator/A/N,Denominator/A/N,X/S,Y/S,ND=NoDelay/S The active window's size is changed to a fraction relative to its screen size. X and Y determine whether this affects only the window's width, only the window's height, or both. Example: "RelSizeWindow 5 7 X Y" will size the active window both in width and height to 5/7 of its screen's size. "RelSizeWindow 1 2 Y" will size the active window only in height to 1/2 (one half) of its screen's height. NAME: RelMoveWindow Arguments: WhichWin/A/N,NumberWins/A/N,X/S,Y/S,ND=NoDelay/S Hmpf. Not too easy to explain. If the active screen's specified axis (specified by "X/S" and "Y/S") was divided into "NumberWins/N" Windows, the parameter "WhichWin" specifies the position this Command moves the active Window to. Nobody will understand that, including myself in half an hour. The purpose of this command is to offer the opportunity of writing arexx-scripts that tile windows in a sophisticated manner (in combination with "RelSizeWindow"), the thing is just that I have yet to write these arexx-scripts. Right now I'm starting to doubt that this is the right way, though ... For now you can move windows with this command to some places other than the screen's border or center. Example: "RelSizeWindow 1 4 X; RelMoveWindow 3 4 X" - the active window's with is sized to 1/4 of its screen's width, and it's moved to the position of the third window of four windows (with width=1/4 of the screens' width) that you have to imagine standing next to each other in a row on the x-axis of the screen. Can't find an explanation now that sounds less ridiculous ... NAME: ExpandWindow Arguments: "Left/S,Right/S,Top/S,Bottom/S,DClip/S,NoDClip/S,ND=NoDelay" According to the arguments passed to it, ExpandWindow expands the active window's borders to its screen's borders or the momentary display clip's borders. The latter can be switched on and off by the arexx-command "ToggleClip" or by providing the appropriate argument to "ExpandWindow", see argument template. Every combination of directions makes sense, e.g. "ExpandWindow Top Bottom Right". NAME: SnapWindow Arguments: "Left/S,Right/S,Top/S,Bottom/S,DClip/S,NoDClip/S,ND=NoDelay" The active window is moved to its screens or display clip's borders. Combinations of opposite movement directions (like "Top Bottom") do not make sense, I'm not quite sure now where exactly the window would be moved... See "ExpandWindow" and "ToggleClip" for details on the display clip. NAME: CenterWindow Arguments: "X/S,Y/S,ND=NoDelay" The active window is moved to its screen's or the momentary display clip's center horizontally or vertically or both, depending on the arguments provided. See "ExpandWindow" and "ToggleClip" for details on the display clip. Future Enhancements ------------------- I have some ideas already for some new commands and Arexx-scripts that help tiling windows and stuff like that, this sure will come. I have just learned that the delay I am using to assure the completion of Intuition procedures ist not sufficient in every situation; I don't like this one anyway, so I'm going to find a different solution. If you have any idea of improvements or corrections then please tell me about it, maybe I will implement it. There might especially be some useful Arexx-commands I did not think of. Of course I'd appreciate any bug report very much, too, the more detailed the better. SHAREWARE --------- If you use WizKey frequently then feel free to send me a donation of 20$ or 20 DM. If you can't afford that much money or if you think that WizKey is worth less, feel free to send less money, that's ok. If you think that WizKey is worth much more than 20$, don't hesitate to send much more than 20$. If you do not like WizKey or do not have any computer at all, and you don't know how to get rid off your money, this might be a reason to send some money to me, too, you are welcome. My address is: Jörg von Frantzius Neue Königstr 61 W-5040 Brühl Germany Email: NOVALIS@DARKNESS.ZER Internet: novalis@darkness.gun.de My bank account is: BLZ 37010050, number 04199 53-507 Postgiroamt Köln UPDATES ------- Registered users can obtain updates for free, e.g. the cost of postage, envelope and diskette. I suggest about $3 or 3,- DM in Germany, I hope that's enough... Since I am working on WizKey almost everytime I switch on my computer, chances are good that there's a new version available every now and then. HISTORY ------- WizKey 1.14 first public release WizKey 1.15 10-Jul-1992 Changes, or better bugfixes: - WizKey now runs on those few Amigas with an 68000 in it ;-) - a potentially nasty bug that showed up only when at least two users are playing with WizKey and the mouse simultaneously is fixed now - Bug in AREXX-Command ScrToFront fixed that would bring up the Workbench no matter what Screenname was passed to it - now CX_PRIORITY may be passed either as a ToolType or CLI- Parameter to determine the priority of WizKey in relation to other running Commodities. BTW, hey Commodore, why doesn't Exchange show nor change these priorities? - WizKey now removes properly when started twice WizKey 1.16 2-Aug-1992 - WizKey should now REALLY run on 68000... - Arexx-argument parsing is now done by Dos' ReadArgs(); argument templates now look standard-like - "ND=NoDelay/S" argument introduced for every Arexx-command that makes sense with this argument, speeding up arexx-scripts a lot - Expand + FullSize take care of the display clip; ToggleClip switches the flag telling if they should or not - some bugs fixed, I really can't remember them all now ;-) WizKey 1.17 7-Aug-1992 - WizKey now DOES run on 68000... ahem (at least on my A1000) - MoveXXXXX, MoveXYCenter and ExpandXXXXX become single Arexx commands each, requiring some arguments to be passed to them; all of them take care of the display clip now - DClip/S and NoDClip/S arguments introduced to arexx-commands that take care of the display clip - ToggleClip defaults now to Yes, and accepts arguments "On/S,Off/S" - WindowList now always opens within the display clip WizKey 1.18 2-Sep-1992 - WizKey now seems to run always on my A1000, really... yeah - "Quit" accepts argument "Force/S" (I once needed it myself) - PropGadget looks nicer now (very important thing) - opening the WindowList could in some situations freeze the machine, fixed now - Added command "RelMoveWindow" - Some renaming again: "MoveWindow" is called "SnapWindow" now, "ShrinkWindow" is called "RelSizeWindow" The new prefsfile reflects the new names, of course. I suggest those 4 of 5 people who are using WizKey already replace their old prefsfiles with the new one.