The CDPD Public Domain Collection for CDTV 3

home *** CD-ROM | disk | FTP | other *** search

/ The CDPD Public Domain Collection for CDTV 3 / CDPDIII.bin / pd / commodities / yak / englishdocs / yak.doc < prev next >

Wrap

Text File | 1993-04-22 | 30KB | 820 lines

short: great multi-purpose commodity Yak 1.4a (c) 1992, 1993, Martin W. Scott. All Rights Reserved. [Needs KickStart 2.04 or above] Yak stands for "Yet Another Kommodity" (never was any good at speling), and is a mouse/window manipulation program along the same lines as DMouse, MightyMouse etc. Why write another one? None of the others (and I've looked at almost all of them) were quite right for me. Yak has the following features: - AutoPoint (sunmouse) that only activates when mouse stops can also specify which screens to include/exclude. (Compatible with popup-menu type programs) - AutoPop windows (bring them to front) when they're auto-activated; - KeyActivate windows (when key pressed); - Activate windows when menu button pressed; - Click windows to front or back; may also specify which screens/windows to include/exclude. - Cycle screens with mouse; - Mouse and Screen blanking (hotkey blanking too); - Close/Zip/Shrink/Enlarge windows with programmable hotkeys; - Cycle screens and windows from keyboard; - Activate Workbench by hotkey (to get at menus when WB obscured); - Center frontmost screen by pressing a hotkey; - Pop up a palette on front screen (requires reqtools.library); - Insert date in custom format (requires locale.library in WB2.1); - KeyClick with adjustable volume; - PopCommand key for starting a command (like PopCLI); - Wildstar option (like StarBurst) lets you use '*' as wildcard. - Optional on-screen AppIcon to bring up preferences window. - Nice gadtools settings window; Look familiar? It's a combination of the AutoPoint, ClickToFront, Blanker and IHelp standard commodities (on the Extras disk) with a hint of KCommodity and DMouse thrown in. And it's quite small, about 12K. It uses about 18K when running. If you use just two of the standard commodities, you'll save memory by using Yak. What Yak doesn't do ------------------- Yak only has a plain screen-blanker. Since the introduction of OS 2.0, there has been a profusion of fancy screen blankers, such as Spliner (which I use), ASwarm (various incarnations), FracBlank and more. I think most people have their own favourite fancy blanker, so I didn't include one in Yak. There is no mouse-acceleration. The system default one (settable via the Input preferences) is more than adequate as far as I am concerned. If I get enough requests, I'll add faster acceleration (so far, hardly any received). How to use Yak -------------- Yak is designed to be run from the sys:WBStartup drawer, but may be 'run' from the Shell. All Yak settings are stored in a prefs-file, "S:Yak.prefs". When you first use Yak, configure it the way you like, then save that configuration for later invocations. The .prefs file format is designed to be upward compatible, so future versions of Yak should be able to load older .prefs files. This didn't quite hold true in the transition from v1.2 to v1.3, but that should be a one-off. The only tooltypes that Yak takes are the standard Workbench ones (such as DONOTWAIT), the standard Commodities ones (such as CX_POPUP) and the AppIcon ones. Those tooltypes are: ToolType Category Description Default (1) --------------------------------------------------------------------------- CX_POPKEY HOTKEY Key to show settings window RCommand Help CX_PRIORITY INTEGER Priority of this commodity 0 CX_POPUP BOOLEAN Show settings window on startup NO NOICON BOOLEAN If TRUE, no AppIcon is made FALSE ICONNAME STRING Name of AppIcon "Yak!" ICONXPOS INTEGER x-coordinate of AppIcon floating ICONYPOS INTEGER y-coordinate of AppIcon floating You should also have the tooltype "DONOTWAIT" set if you want to start Yak from your SYS:WBStartup drawer. The AppIcon facility is optional (specify NOICON=TRUE if you don't want it). If NOICON=FALSE (or there is no NOICON tooltype) Yak puts an AppIcon onto the Workbench screen, and when it is double-clicked, the Settings Window is opened. The icon imagery is obtained from the icon Yak was started from, which allows you to customise the AppIcon to your colours/resolution simply by changing Yak's icon. The CX_PRIORITY may be useful in enabling Yak and other commodities to work better together. See, for example, notes on the RMB Activate toggle below. The Settings Window ------------------- Once Yak is started, you may bring up its settings window by the following means: Pressing RCommand Help (i.e. the Right Amiga key and the Help key). This key-sequence is configurable; Double-clicking Yak's AppIcon (if this feature is set); Start Yak again (from Workbench tool icon); Via the Commodities Exchange (on the Extras disk). A fairly large window with a small menu and many gadgets will appear, grouped under headings. From top-to-bottom, left-to-right, they are: Yak Hotkeys =========== Here is where you edit the hotkeys for specific actions. Those actions are: Show this window bring up the settings window Default: RCommand Help Close window close currently active window (c.a.w.) Default: Control esc Zip window zip c.a.w. (like clicking on zip gadget) Default: Control z Shrink window make c.a.w. as small as possible Default: LCommand [ Enlarge window make c.a.w. as large as possible Default: default: LCommand ] Activate WBench activate (a) Workbench window Default: LCommand w Palette bring up palette on front screen NB: You MUST close the palette before the screen is closed, otherwise a system crash may result. Also, while any palettes are open, Yak cannot be exited. Default: LCommand p PopCommand execute PopCommand (see below) Default: LCommand esc Insert date write date into c.a.w. Default: LCommand d Cycle windows bring rearmost window to front Default: LCommand k Cycle screens bring rearmost screen to the front Default: LCommand n Center screen center horizontally the front screen Default: LCommand c Screen to back push front screen to back. same as Intuition's LCommand m, but also activates window under mouse on new front screen. Default: LCommand m Blank display immediately blank the display (like screen blanker); screen-blanking need not be enabled for this to work. Default: LCommand del To change an action's hotkey, click over the action, then edit the string gadget below as desired. If you want to remove a hotkey (if you don't need a particular action) click in the string gadget and press RightAmiga-X to clear it, then press Return. (Make sure the string really is empty (i.e. not composed of spaces) otherwise strange keys will be mapped due to a bug in commodities.library -- see history (v1.2) for details.) The Activate WBench hotkey gives access to the Workbench menus when the Workbench is obscured by an application-window (e.g. an editor or shell). It brings the Workbench screen to front if necessary. PopCommand ========== This string gadget holds the command that will be executed when the PopCommand hotkey is pressed. Note that it is not run asynchronously; some aspects of Yak will be disabled until the command is finished (but commands like NewShell return immediately). DateFormat ========== This string specifies what string is to be inserted into the event chain on pressing the Date insertion hotkey. Any valid locale-style string is valid (see below for full details). AutoScreens =========== The AmigaDos pattern (see below) here specifies on which screens the AutoFront/PopToFront features are ACTIVE. ClickScreens ============ The AmigaDos pattern (see below) here specifies on which screens the ClickToFront/Back features are ACTIVE. PopWindows ========== The AmigaDos pattern (see below) here specifies on which windows the AutoPopToFront feature is active. ClickWindows ============ The AmigaDos pattern (see below) here specifies which windows may be clicked-to-front. Most commonly, this will be set to exclude the Workbench window. Note that this does not filter click-to-back operations. ScreenBlank =========== If no user input (mouse or keyboard) occurs over this period (of seconds), the screen will blank. Set it to 0 to disable screen blanking altogether. The blanking is performed by opening a 2-color screen with the same displaymode as the frontmost screen. MouseBlankTime ============== If mouse isn't moved in the period specified, the mouse will blank. This is only operational if the Mouse Blanking toggle (see below) is on, otherwise it is ignored. Method ====== Refers to mouse-blanking. `None' disables mouse-blanking altogether, `Sprites' means blank mouse by disabling (all) sprites (like in version 1.2), and `Copper' means blank mouse by modifying copper list. This second option only disables sprite 0 (the mouse-pointer), so terminal programs using a sprite for the cursor work okay, but the method is a bit less robust (the mouse occasionally comes back on). ClickVol ======== Controls the volume of the KeyClick. A volume of zero means 'no click' (yes, that's obvious, but when set to zero, the audio device won't be opened at all). Toggles ======= Here are various toggles for miscellaneous features. AutoPoint Activate window under mouse. This behaves almost exactly like Commodore's AutoPoint commodity, in that it only activates a window when the mouse stops. AutoPoint is compatible with popup-menu type programs. Note: can specifiy pattern that screen title must match before this function operates. AutoPopToFront Only operative when AutoPoint is set, this tells Yak to bring windows to the front as well as activating them. The exception is when the window under the mouse has a requester showing. Note that both the Auto-functions only take place when NO qualifier (mouse or keyboard) is pressed. Not only does this avoid conflict with other programs, it provides a way of preventing activation/popping when it's not desired. Note: can specifiy pattern that window title must match before this function operates. RMB Activate When selected, the window under the mouse will be activated when the right mouse button is pressed, regardless of the status of AutoPoint. This is useful in getting the menu you want without either waiting for AutoPoint to activate the window or clicking into the window to make it active. For instance, when using the screen depth gadgets, the new front screen is not activated, but with this toggle set, clicking the RMB will get the correct menus. Note 1: If there is no window under the mouse, the first window on the screen will be activated. Note 2: To work properly with popupmenu-type programs, Yak's CX_PRIORITY may need to be higher than the popupmenu program's CX_PRIORITY. Key Activate Activates window under mouse when key is pressed. You should only need one of AutoPoint or KeyActivate. Click To Front Bring a window to the front of others by double-clicking over it. Click To Back Move a window to the back of others by pressing and holding the left mousebutton, then clicking the right mousebutton. Note: can specifiy pattern that screen title must match before click functions operate. Note2: as with Auto- features, clicking to front and back is disabled whilst a keyboard qualifier is pressed. Screen To Back Using the same mouse sequence as Click To Back, move a screen to the back of others if: either the window under the mouse is a backdrop window (like the main Workbench window) or there is only one window on the screen. Screen Activate When checked, Yak will activate screens that it shuffles by hotkeys (i.e. Screen Cycle hotkey and LCommand m hotkey). This is a toggle because conflicts arise with some programs. This is similar (but not identical) to Steve Tibbet's WindX. By activating screens I mean that it activates the window under the mouse-pointer of the new front screen. Wild star When on, enables the use of * as an AmigaDos pattern-matching character (like MSDOS and UNIX *). (This is what the StarBurst program does.) Hide ==== Close the settings window, leaving Yak running. (The window's close gadget has the same effect). Quit ==== Terminate Yak. The menus are: Load (shortcut: L) ==== Load previously saved prefs-file. This basically restores your default options. Save (shortcut: S) ==== Save the current settings to the prefs-file. These settings will then be used in future invocations of Yak. Hide (shortcut: H) ==== Close settings window. Quit (shortcut: Q) ==== Terminate Yak. You may also control Yak using the Commodities Exchange program on the Workbench disk. Consult your user-guide for details on this. Date formats ------------ For the date-insertion feature, you must use a locale-style date format string (and so will need AmigaDos 2.1). The available formatting options under locale.library are as follows:- %a - abbreviated weekday name %A - weekday name %b - abbreviated month name %B - month name %c - same as "%a %b %d %H:%M:%S %Y" %C - same as "%a %b %e %T %Z %Y" %d - day number with leading 0s %D - same as "%m/%d/%y" %e - day number with leading spaces %h - abbreviated month name %H - hour using 24-hour style with leading 0s %I - hour using 12-hour style with leading 0s %j - julian date %m - month number with leading 0s %M - the number of minutes with leading 0s %n - insert a linefeed %p - AM or PM strings %q - hour using 24-hour style %Q - hour using 12-hour style %r - same as "%I:%M:%S %p" %R - same as "%H:%M" %S - number of seconds with leadings 0s %t - insert a tab character %T - same as "%H:%M:%S" %U - week number, taking Sunday as first day of week %w - weekday number %W - week number, taking Monday as first day of week %x - same as "%m/%d/%y" %X - same as "%H:%M:%S" %y - year using two digits with leading 0s %Y - year using four digits with leading 0s That list is pretty exhaustive, and should handle most needs; you can insert your own text freely in the format string. Some examples: "The time is %X" gives (e.g.) "The time is 20:44:16" "Have a nice %A!" gives (e.g.) "Have a nice Monday!" If you need more details, consult the AutoDocs on locale.library if you have them. AmigaDos Patterns ----------------- AmigaDos patterns are used to include/exclude a list of named screens/windows for a particular feature. Currently, there are three such features: AutoActivate/Pop, ClickToFront/Back (specified on screens), and AutoPopToFront (specified on windows). These pattern specifications aid in compatibillity with other programs you may use. The pattern matching is case-sensitive. "Amiga" is not the same as "AMIGA". The standard AmigaDos patterns available are:- ? Matches a single character. # Matches the following expression 0 or more times. (ab|cd) Matches any one of the items seperated by '|'. ~ Negates the following expression. It matches all strings that do not match the expression (aka ~(foo) matches all strings that are not exactly "foo" [abc] Character class: matches any of the characters in the class. a-z Character range (only within character classes). % Matches 0 characters always (useful in "(foo|bar|%)"). * Synonym for "#?", not available by default. Available if Wildstar option is set. If you're not used to patterns, you may find all of that quite daunting. Consult your system manual for further details. There are two basic things you'll want: either a finite list of names that the feature should be enabled on, or a finite list for which it should be disabled. To ENABLE a feature on all objects (be they screens or windows, as appropriate) use the "#?" pattern (matches everything). To enable a feature on N objects named "name1" to "nameN", use (name1|name2| ... |nameN) and to DISABLE the feature for these names, prepend a tilde ~, viz. ~(name1|name2| ... |nameN) An example: I don't want AutoPopToFront popping the Workbench window or any Protext (WP from Arnor) window, so exclude them with the pattern ~(Workbench|#?Arnor#?) Note that the second 'name' is actually a pattern, which matches any title with the text "Arnor" in it. Another: I don't want AutoActivation on Directory Opus's screen. It doesn't show its title in the program so I have to use ARTM or Xoper to find the screen's name, and find that it's "DOPUS.1". Figuring that the "1" would bump to "2" if I ran two copies, I decide to exclude all DOpus screens using ~(DOPUS#?) NB-1: Specifying the Workbench screen in a pattern is a bit tricky, as it's title keeps changing, depending on what window is active. For most purposes, a pattern such as #?Workbench#? will match, but some applications set the Workbench title to a descriptive string of their application. NB-2: Screens or windows with titles that are unset (i.e. are NULL) always pass the patterns. Ending Yak ---------- Yak can be terminated in the following ways: From the settings window, select Quit (gadget or menu); From the Commodities Exchange, select Kill (Remove under WB2.1); By sending the Yak process a ^C signal. Problems -------- There are a few problems that I am currently aware of. Firstly, a shell created by the PopCommand hotkey doesn't have the stack or current directory as set at boot-time (in the Startup-Sequence). It DOES retain your path, though. Your Shell-Startup file should set the CD and the stack you need. The Close window hotkey doesn't work for shell windows. This is because they handle intuition events differently from other windows. If you're not happy with Yak's mouse-blanking, you could try the Commodore MouseBlank commodity (WB3.0), which should blank the mouse on all displays correctly. NOTE FOR AMOS USERS: I hate AMOS (that's enough of my opinion), partly because it is so system unfriendly. It completely steals the input stream, so that mouse blankers (in programs like Yak) kick-in, thinking there's been no input, and the mouse isn't restored, because there's no mousemoves to unblank it. Because Yak uses a rather bad blanking method, problems can occur (mouse vanishes and won't come back). Two solutions: 1) Use 'Copper' blanking. 2) Set MouseBlankTime to zero. You'll still have key blank, but no timed blank. Then the AMOS problem of the pointer disappearing should be solved. Compiling --------- Yak has been written to compile under SAS/C, and as from v1.4a, using SAS/C version 6.2. The code passes cleanly with ANSI checking, so users of other ANSI-compliant compilers should have little problem recompiling - the only places changes may be needed are in SAS-specific keywords (like __saveds). Yak uses overlays, but this can be compiled out by removing the definition USE_OVERLAYS in SCOPTIONS. GTB 2.0b was used to generate the user-interface. The generated code (popup.c, popup.h) needs only minimal modification, specifically to use NewLookMenus under WB3.0 and above; these (two) changes are indicated by comments with the word 'ADDED' in them, if you want to play around with the interface. Distribution ------------ Yak is freely redistributable, copyrighted software. The source is included, and you are permitted to modify it for personal use, but any modifications made must NOT be distributed. If you have made changes you think others would like, send them to me and I'll include them in future versions. Although Yak is freeware, DONATIONS WOULD BE GLADLY ACCEPTED, either money or stuff you've written yourself. Credits ------- Yak is written entirely in C, and compiled with SAS/C 6.2. Thanks to Reza Elghazi for help in the transition to 6.2. The Settings window gadgetry was created using the excellent (apart from the v2.0 glitch:) GadToolsBox v2.0b, from Jaba Development. Yak makes use of reqtools.library, which is Copyright Nico François. Thanks must also go to Mike Meyer et. al. for Mg3, Steve Koren for SKsh, Matt Dillon for DMouse (which answered many of my how-to questions), and Kai Iske for KCommodity, which is where the KeyClick sound was 'borrowed'. Yak also uses WB2CLI, a very useful little link-module by Mike Sinz. The HotKey documentation is taken from the ToolManager distribution, by kind permission of Stefan Becker. Thanks to Stefan Sticht for his public domain MouseBlanker commodity - this is where I pinched the 'Copper' mouse-blanking method. And a big thank-you to all those people who wrote to me about Yak with suggestions and bug reports, and especially to Gaël Marziou who drew the nice Yak icons and translated the documentation into French -- thanks Gaël! History (* = new feature) ------------------------- v1.4a * Added RMB Activate toggle - window under mouse is activated when right mouse button pressed. * New improved mouse-blanking: Method 'Sprites' is same as before, but method 'Copper' has been completely rewritten; it still only blanks sprite 0, but is now compatible with LacePointer. - Completely removed AutoThresh code due to compatibility problems, but RMB Activate takes over the main usefulness of AutoThresh anyway (i.e. getting the correct menus up). - Now compiled with SAS/C 6.2 (see Compiling above). v1.4 [* AutoActivate now has threshold setting. This should have been in ages ago, but I only just realised how easy it was to add. REMOVED DUE TO CONFLICTS WITH POPUPMENU ] - Range-checking now performed on number-gadgets. - NewLookMenus for WB 3.0. v1.3f * Settings window now font-sensitive (uses screen font). * ScreenToBack by mouse-clicks now activates first window on front screen when no window is under mouse (this helps programs like MagicMenu). * Screen blanking now opens screen with same displaymode as front one. - Further mouse-blanking bug removed. - Conflicts between window-cycle hotkey and key activation resolved, although they don't really go well together. - Window-cycle (via hotkey) now also cycles Workbench windows; when initially written, Yak emulated IHelp's (CBM OS2.0) function of cycling application windows only, but I get so many reports from people saying that this function doesn't work, I figured folks really want to cycle ALL windows. - More enforcer-hits removed (oh I wish I had an 030 etc., then I could fix these all by myself, instead of relying on others informing me). v1.3e - Version string added. - Now a choice of mouse-blanking method (so quit the flames...). v1.3d - Fixed bug in KeyActivate routine (was losing first keystroke). v1.3c - Fixed small enforcer hit which may have caused Window cycle to fail. v1.3b * New ClickWindows pattern, allows you to specify which windows may be clicked-to-front (n.b. has no effect on click-to-back). * Mouse-blank timeout may now be specified. - [Click volume now specified via integer gadget]. v1.3a - Now all Intuition calls are outside the input-handler to avoid possible deadlocks (thanks to Eddy Carroll for reporting this). * New hotkey: Screen to back. Previously, this was hardcoded to LCommand m, but can now be changed. * New hotkey: Blank display. Instant screen-blank. * Can now click screens to back in the titlebar (previously not permitted due to system conflicts). * Palette runs asynchronously now, and you can have as many open as you like. They MUST be closed before their parent screen closes, and before Yak is terminated. - Now a disk-insertion halts screen-blanking. - Centering of screens via hotkey adjusted by 1 pixel, to be consistent with Display, AutoCentre etc. (i.e. I was wrong...) - If started from Workbench (the usual way) Yak now sets it's current directory to SYS:; this is then inherited by shells created with PopCommand. - Some more mouse-blanking problems fixed. Also, screen-blanking mouse-flicker fixed - hardly anyone uses Yak's blanker, so it went unnoticed. - Fixed small bug in channel allocation priority. - Bug fixed in hotkey cancellation (by clearing string gadget). Previously used to cancel a hotkey only for current session, and still continue to show old key definition. How do I miss these things? v1.3 * Executable is now overlayed. Now uses less memory than earlier versions, even with new features! * Can now specify which screens AutoActivate and ClickToFront/Back operate on, by means of a standard AmigaDos pattern. * Date insertion uses locale.library-style format specification. (Unfortunately, date insertion feature now requires WB 2.1). * AutoPopToFront feature added. * Improved mouse-blanking: now Yak only blanks sprite 0, so programs that use other sprites are unaffected. * PopCommand now retains paths (but not directory/stack in startup-sequence). - Auto-activation and key-activation now works more sensibly. - Somehow managed to remove volume check for clicking. Now a volume of zero means that no click will be attempted. - Date insertion now inserts key-up events to aid compatability with other programs. - Window cycling (via hotkey) now works on all screens (previously just on WB, but I didn't mention it in the docs). NB - Contention code in v1.2c was rather severe in cases, and unnecessary if I changed the way Yak AutoActivated. Now Yak only AutoActivates (and AutoPops) when no qualifier or mouse-button is pressed. Contention-checking code has therefore been removed. Should be no problems with well-behaved programs. NB - Settings file changed; now uses S:Yak.prefs instead of S:Yak.config; this is because format of that file changed. A 'Convert' program is supplied to create a 1.3 file from existing 1.2 file. - [Changed prefs window layout; looks nicer now (I think).] v1.2c - Inclusion of HotKey documentation (adapted from Stefan Becker's ToolManager documentation). - Enforcer hit removed. (But there may be more). - Improved contention-checking; now Yak's AutoActivate works with Dragit V2, for instance. v1.2b - maximum length of hotkey definitions increased from 29 to 49 characters to allow (almost) all possible definitions. v1.2a - small bug crept into v1.2; wasn't removing old hotkey when changing existing definition. v1.2 * mouse-pointer unblanks when Left-Amiga key is pressed, so keyboard mouse-move is usable. * activates screens (i.e. windows on screens) when they're shuffled, similar to WindX. * now optionally puts an AppIcon on the Workbench screen; when this is double-clicked, the preferences window pops up. - entering a blank string as a hotkey (to delete it) would create a hotkey attached to the ' key. I consider this to be a bug in commodities.library. Now a blank string WILL remove the hotkey. - bad bug in auto-activate (key or mouse) fixed. Previously, Yak would sometimes choose the wrong window (on the wrong screen) if more than one screen was visible. - now changes active window even when current one has a request(er) pending (but if active window has an active string-gadget, it won't be de-activated). This seems more useful (to me, anyway). - changed 'Screen Cycle' toggle to 'Screen To Back' to avoid confusion with 'Screen Cycle' hotkey (yes, silly of me...) v1.1 * now uses config-file (s:Yak.config) rather than 10 million tooltypes. Only the standard commodity tooltypes are now recognised. * added window and screen cycling via keyboard (same as IHelp). * added screen-center hotkey. * added wildstar toggle. - [slightly changed settings window layout, added menu] - fixed bug in click-to-back feature (conflicted with PowerSnap); it now only operates if no qualifiers are pressed. - fixed bug in mouse-blanking where mouse pointer used to reappear periodically. - hotkeys now produce keyclick if it's on. v1.0 - initial release. Contact ------- I can be reached with comments, suggestions, bug reports, praise, money etc. at the following addresses: BEFORE END OF JULY 1993: Martin W. Scott, 23 Drum Brae North, Edinburgh EH4 8AT United Kingdom AFTER END OF JULY 1993: Martin W. Scott, c/o 557 Great Western Road, Ground flat right, Aberdeen AB1 7PA United Kingdom OR BY EMAIL UNTIL END OF JULY 1993: mws@castle.ed.ac.uk Cheers, Martin.