home *** CD-ROM | disk | FTP | other *** search
/ Otherware / Otherware_1_SB_Development.iso / amiga / utility / misc / yak.lha / Yak / Yak.doc < prev    next >
Encoding:
Text File  |  1992-09-18  |  10.9 KB  |  314 lines
  1.  
  2. Yak 1.0  (c) 1992, Martin W. Scott. All Rights Reserved.
  3. --------------------------------------------------------
  4. [Needs KickStart 2.04 or above]
  5.  
  6. Yak stands for "Yet Another Kommodity" (never was any good at speling),
  7. and is a mouse/window manipulation program along the same lines as DMouse,
  8. MightyMouse etc.
  9.  
  10. Why write another one? None of the others (and I've looked at almost all of
  11. them) were quite right for me. Yak has the following features:
  12.  
  13.     - AutoPoint (sunmouse) that only activates when mouse stops;
  14.       (Compatible with SiliconMenus' Iris menus)
  15.  
  16.     - KeyActivate windows (when key pressed);
  17.  
  18.     - Click windows to front or back;
  19.  
  20.     - Cycle screens with mouse;
  21.  
  22.     - Mouse and Screen blanking;
  23.  
  24.     - Close/Zip/Shrink/Enlarge windows with programmable hotkeys;
  25.  
  26.     - Activate Workbench by hotkey (to get at menus when WB obscured);
  27.  
  28.     - Pop up a palette on front screen (requires reqtools.library);
  29.  
  30.     - Insert date (in various formats);
  31.  
  32.     - KeyClick with adjustable volume;
  33.  
  34.     - PopCommand key for starting a command (like PopCLI);
  35.  
  36.     - Nice gadtools settings window;
  37.  
  38.     - All settings accessible from Workbench tooltypes;
  39.  
  40. Look familiar? It's a combination of the AutoPoint, ClickToFront, Blanker
  41. and IHelp standard commodities (on the Extras disk) with a hint of
  42. KCommodity and DMouse thrown in. And it's quite small, about 11K. It uses
  43. about 18K when running. If you use just two of the standard commodities,
  44. you'll save memory by using Yak.
  45.  
  46.  
  47. What Yak doesn't do
  48. -------------------
  49. Yak only has a plain screen-blanker. Since the introduction of OS 2.0,
  50. there has been a profusion of fancy screen blankers, such as Spliner (which
  51. I use), ASwarm (various incarnations), FracBlank and more. I think most
  52. people have their own favourite fancy blanker, so I didn't include one in
  53. Yak.
  54.  
  55. There is no mouse-acceleration. The system default one (settable via the
  56. Input preferences) is more than adequate as far as I am concerned. If I get
  57. enough requests, I'll add faster acceleration.
  58.  
  59.  
  60. How to use Yak
  61. --------------
  62. Yak is designed to be run from the sys:WBStartup drawer, and accepts many
  63. tooltypes to let you configure it. It can be started from the Shell, but
  64. that is less convenient.
  65.  
  66. The tooltypes accepted come in four general categories:
  67.  
  68.     BOOLEAN        true/yes/on responses are "YES", "ON", "TRUE".
  69.             Anything else means false/no/off.
  70.  
  71.     HOTKEY        a valid hotkey definition string. Full details of
  72.             valid definitions are given in the OS 2.0
  73.             user-manual (section 5 of mine) so I'll not
  74.             replicate them here.
  75.  
  76.     INTEGER        a (possibly) signed integer.
  77.  
  78.     STRING        an arbitrary string.
  79.  
  80. The many tooltypes are:
  81.  
  82. ToolType    Category    Description            Default (1)
  83. ---------------------------------------------------------------------------
  84. (Standard commodity tooltypes)
  85. CX_POPKEY    HOTKEY        Key to show settings window    RCommand Help
  86. CX_PRIORITY    INTEGER        Priority of this commodity    0
  87. CX_POPUP    BOOLEAN        Show settings window on startup    NO
  88.  
  89. (KeyClick tooltypes)
  90. VOLUME        INTEGER        Keyclick volume (0-64)        48
  91.  
  92. (Screen-blanking tooltypes)
  93. SCRTIMEOUT    INTEGER        Screen-blanking timeout (0-9999) 300 seconds
  94.  
  95. (Date insertion tooltypes)
  96. DATEFORMAT (3)    INTEGER        Format for date (0-3)        0
  97. DAY        BOOLEAN        Insert day            YES
  98. DATE        BOOLEAN        Insert date            YES
  99. TIME        BOOLEAN        Insert time            NO
  100.  
  101. (Mouse-control tooltypes)
  102. AUTOPOINT    BOOLEAN        see below             ON
  103. KEYACTIVATE    BOOLEAN        see below            OFF
  104. CLICKTOFRONT    BOOLEAN        see below            ON
  105. CLICKTOBACK    BOOLEAN        see below            ON
  106. SCREENCYCLE    BOOLEAN        see below            ON
  107. MOUSEBLANK    BOOLEAN        see below            ON
  108.  
  109. (Hotkeys for window manipulation etc)
  110. CLOSEWINDOW    HOTKEY        Key to close active window    Control esc
  111. ZIPWINDOW    HOTKEY        Key to 'zip' active window    Control z
  112. MAKESMALL    HOTKEY        Key to shrink active window    LCommand [
  113. MAKEBIG        HOTKEY        Key to enlarge active window    LCommand ]
  114. WORKBENCH    HOTKEY        Key to activate Workbench    LCommand w
  115. PALETTE        HOTKEY        Key to pop-up palette        LCommand p
  116. POPCOMMKEY    HOTKEY        Key to run PopCommand        LCommand esc
  117. INSERTDATE    HOTKEY        Key to insert date        LCommand d
  118.  
  119. POPCOMMAND    STRING        Command for POPCOMMKEY hotkey    NewShell ...
  120.  
  121. You should also have the tooltype "DONOTWAIT" set if you want to start Yak
  122. from your sys:WBStartup drawer. There are so many different tooltypes that
  123. I may use a config file instead in a future version.
  124.  
  125. Hopefully, you'll be happy enough with the defaults and only have to set a
  126. few tooltypes.
  127.  
  128. The meanings of all the tooltypes will become apparent in the discussion on
  129. the Settings window.
  130.  
  131.  
  132. The Settings Window
  133. -------------------
  134. Once Yak is started, you may bring up its settings window by pressing
  135. RCommand Help (i.e. the Right Amiga key and the Help key). This
  136. key-sequence is configurable.
  137.  
  138. A fairly large window with many gadgets will appear, grouped under
  139. headings. From top-to-bottom, left-to-right, they are:
  140.  
  141.     Yak Hotkeys
  142.     -----------
  143.     Here is where you edit the hotkeys for specific actions. Those
  144.     actions are:
  145.     
  146.     Show this window    bring up the settings window
  147.     Close window        close currently active window (c.a.w.)
  148.     Zip window        zip c.a.w. (like clicking on zip gadget)
  149.     Shrink window        make c.a.w. as small as possible
  150.     Enlarge window        make c.a.w. as large as possible
  151.     Activate WBench        activate (a) Workbench window
  152.     Palette            bring up palette on front screen
  153.     PopCommand        execute PopCommand (see below)
  154.     Insert date        write date into c.a.w.
  155.     
  156.     To change an action's hotkey, click over the action, then edit the
  157.         string gadget below as desired. The Activate WBench hotkey gives
  158.     access to the Workbench menus when the Workbench is obscured by an
  159.         application-window (e.g. an editor or shell).
  160.     
  161.     Click Volume
  162.     ------------
  163.     Controls the volume of the KeyClick. A volume of zero means 'no
  164.         click' (yes, that's obvious, but when set to zero, the audio device
  165.         won't be opened at all).
  166.     
  167.     Date Format
  168.     -----------
  169.     These gadgets control the format of the date used by the Insert
  170.         date hotkey. Their usage should be fairly obvious.
  171.  
  172.     PopCommand
  173.     ----------
  174.     This string gadget holds the command that will be executed when the
  175.         PopCommand hotkey is pressed. Note that it is not run
  176.         asynchronously; some aspects of Yak will be disabled until the
  177.         command is finished (but commands like NewShell return
  178.         immediately). 
  179.  
  180.     Mouse Options
  181.     -------------
  182.     Here are various toggles for the mouse manipulation features.
  183.     
  184.     AutoPoint    Activate window under mouse. This behaves almost
  185.                 exactly like Commodore's AutoPoint commodity, in
  186.                 that it only activates a window when the mouse has
  187.                         stopped moving (so there is a small delay). The
  188.                         difference is that Yak's AutoPoint works with
  189.                         SiliconMenus with Iris menus on - it won't go
  190.                         activating windows while you're making your menu
  191.                         choice. (By the way, GET SiliconMenus!)
  192.  
  193.     Key Activate    Activates window under mouse when key is pressed.
  194.                         You should only need one of AutoPoint or
  195.             KeyActivate.
  196.  
  197.     Click To Front    Bring a window to the front of others by
  198.                         double-clicking over it.
  199.  
  200.     Click To Back    Move a window to the back of others by
  201.                         pressing and holding the left mousebutton, then
  202.                         clicking the right mousebutton.
  203.             
  204.     Screen Cycle    Using the same mouse sequence as Click To Back,
  205.                         move a screen to the back of others if:
  206.             
  207.             either    the window under the mouse is a backdrop
  208.                             window (like the main Workbench window)
  209.             or    there is only one window on the screen.
  210.             
  211.             Screen Cycle only works when the mouse is BELOW the
  212.                         screen's titlebar (due to confilcts with other
  213.             programs).
  214.  
  215.     Mouse Blanking    Blank the mouse pointer when a key is pressed. The
  216.                         mouse pointer is restored when the mouse is moved.
  217.                         The mouse pointer will also blank after a 5 second
  218.                         period of inactivity. (See problems below.)
  219.  
  220.     Screen Timeout
  221.     --------------
  222.     If no user input (mouse or keyboard) occurs over this period (of
  223.         seconds), the screen will blank. Set it to 0 to disable screen
  224.         blanking altogether.
  225.  
  226.     Hide
  227.     ----
  228.     Close the settings window, leaving Yak running.
  229.     (The window's close gadget has the same effect).
  230.  
  231.     Quit
  232.     ----
  233.     Terminate Yak.
  234.  
  235. You may also control Yak using the Commodities Exchange program on the
  236. Workbench disk. Consult your user-guide for details on this.
  237.  
  238.  
  239. Ending Yak
  240. ----------
  241. Yak can be terminated in the following ways:
  242.  
  243.     From the settings window, select Quit;
  244.     
  245.     From the Commodities Exchange, select Kill;
  246.     
  247.     By sending the Yak process a ^C signal.
  248.  
  249.  
  250. Problems
  251. --------
  252. There are a few problems that I am currently aware of. Firstly, a shell
  253. created by the PopCommand hotkey doesn't have the paths or stack set at
  254. boot-time (in the Startup-Sequence). Your Shell-Startup file should set any
  255. paths and the stack you need. (I use a PATH environment variable, which is
  256. referenced in both my Startup-Sequence and Shell-Startup, so that changes
  257. made happen in both places.)
  258.  
  259. When the Palette is opened, no other hotkeys work, and the keyclicking is
  260. disabled. There is a way to open a Palette requester asynchronously using
  261. reqtools, but I've yet to look into it.
  262.  
  263. Mouse blanking is performed by turning the sprites off. I know that this is
  264. a bit dirty, but just clearing the pointer holds problems too. See the
  265. source (file "handler.c") for further details. If you know of a workaround,
  266. I'd appreciate you letting me know.
  267.  
  268. The Close window hotkey doesn't work for shell windows. This is because
  269. they handle intuition events differently from other windows.
  270.  
  271.  
  272. Distribution
  273. ------------
  274. Yak is freely redistributable, copyrighted software. The source is included,
  275. and you are permitted to modify it for personal use, but any modifications
  276. made must NOT be distributed. If you have made changes you think others
  277. would like, send them to me and I'll include them in future versions.
  278.  
  279. Although Yak is freeware, donations would be gladly accepted, either money
  280. or stuff you've written yourself. I would be grateful if you would let me
  281. know if you use Yak, so I can judge whether it's worth releasing upgrades.
  282. A postcard or email message would be fine.
  283.  
  284.  
  285. Credits
  286. -------
  287. Yak is written entirely in C, and compiled with SAS/C 5.10a.  The Settings
  288. window gadgetry was created using GadToolsBox, from Jaba Development. If
  289. you are an Amiga developer, you really should get a hold of GadToolsBox. 
  290.  
  291. Yak makes use of reqtools.library, which is Copyright Nico Franτois.
  292. Thanks must also go to Mike Meyer et. al. for Mg3, Steve Koren for SKsh,
  293. Matt Dillon for DMouse (which answered many of my how-to questions), and
  294. Kai Iske for KCommodity, which is where the KeyClick sound was 'borrowed'.
  295.  
  296.  
  297. Contact
  298. -------
  299. Send bug-reports, comments, suggestions, donations, postcards etc. to:
  300.  
  301.     Martin W. Scott,
  302.     23, Drum Brae North,
  303.     Edinburgh, EH4 8AT
  304.     United Kingdom.
  305.  
  306. or by e-mail: mws@castle.ed.ac.uk
  307. but I will be switching accounts in Oct '92, so if mail bounces around
  308. then, please try again a couple of weeks later, or use postal mail.
  309.  
  310. Cheers,
  311.  
  312.     Martin.
  313.  
  314.