home *** CD-ROM | disk | FTP | other *** search
/ The Fred Fish Collection 1.5 / ffcollection-1-5-1992-11.iso / ff_disks / 200-299 / ff293.lzh / ClockDJ / ClockDJ.doc < prev    next >
Text File  |  1989-12-14  |  31KB  |  1,218 lines

  1.  
  2. ClockDJ   - Assembly language clock, mouse, screen and window program.
  3. Version   - 4.07
  4. Copyright - Copyright (c) by David Jenkins, 17 Oct 89, 
  5.             I can be reached at Bloom Beacon 416-283-5924.
  6.  
  7.  
  8.      This program is copyright but may be distributed freely. Please keep the
  9. documentation with the load module.
  10.  
  11. Version 4.07 
  12. ~~~~~~~~~~~~
  13.  
  14. 1. When flipping screens, the window under the pointer becomes
  15.    active irrespective of the Sun Mouse or Key Activate settings.
  16.  
  17. 2. A  bug in the mouse button routine has been fixed.
  18.  
  19.  
  20. Version 4.06 
  21. ~~~~~~~~~~~~
  22.  
  23.     The clock window can now be popped to the next screen
  24. immediately by holding down the left shift key while clicking the
  25. left mouse button in the clock window.
  26.  
  27.     The key re-mapping routines have been re-written; the delay
  28. parameter used when submitting a string should not now be needed (although
  29. it is still valid to specify it).
  30.  
  31.  
  32.  
  33. Version 4.05 
  34. ~~~~~~~~~~~~
  35.  
  36.     Fixed a bug in defining keypad keys as a macro.
  37.  
  38. Eg. a macro like this:
  39.  
  40.     \lal\kp7\run ed\r\c
  41.  
  42. should now work.
  43.  
  44.  
  45. Version 4.04 
  46. ~~~~~~~~~~~~
  47.  
  48.     Click to front now gives you the option of keeping or discarding 
  49. the last of the left mouse button clicks which brings the window to front. 
  50.  
  51.     There is a 'Discard' sub-menu item under 'Click to Front'. 
  52. If 'Discard' is checked the last mouse click is discarded.
  53.  
  54.     The difference this option makes is mainly seen when the last
  55. mouse click is on an icon or other field you wish to select. To find
  56. out which to use, experiment.
  57.  
  58.  
  59. Version 4.03 
  60. ~~~~~~~~~~~~
  61.  
  62.     This version fixes a bug which made Key Activate
  63. unreliable.
  64.  
  65.  
  66. Version 4.02 
  67. ~~~~~~~~~~~~
  68.     Version 4.02 includes a couple of improvements in the
  69. click to front and click to back routines:
  70.  
  71. 1. The click to front code removes the last mouse button click
  72.    to prevent something unintentional happening when you simply
  73.    want to click a window to the front.
  74.  
  75. 2. In this version you can hold down the left mouse button and
  76.    click many windows to the back (with the right mouse button)
  77.    without having to release the left button.
  78.  
  79.  
  80.     The zoo file also has WTFPatch3 which has a corresponding
  81. change and should replace WTFPatch2 in your startup sequence.
  82.  
  83.  
  84.  
  85. Version 4.01 
  86. ~~~~~~~~~~~~
  87.  
  88.     This version fixes a bug which caused a machine freeze
  89. when the left mouse button was pressed under some circumstances.
  90.  
  91.  
  92.  
  93. Version 4.00 
  94. ~~~~~~~~~~~~
  95.  
  96.     This  version  has  an  AREXX  port.   See  the ARexx section for
  97. details.
  98.  
  99.  
  100. Version 3.09 changes
  101. ~~~~~~~~~~~~~~~~~~~~
  102.  
  103. 1. This version supports the Arp 1.3 file requester. Also, a new parameter
  104.    is supported in the macro to give you the option of changing the 
  105.    colours of the requester. For example:
  106.  
  107.    \lal\`\&arf1\r\s\2
  108.               ^
  109.             gives colour 1
  110.  
  111.    \lal\`\&arf2\r\s\2
  112.               ^
  113.             gives colour 2
  114.  
  115.  
  116.  
  117. 2. The 'Load Keys' will now bring up the Arp file requester.
  118.  
  119.  
  120.  
  121.  
  122. Version 3.08 changes
  123. ~~~~~~~~~~~~~~~~~~~~
  124.  
  125. 1. The main change in this version is the ability to invoke  
  126.    the Arp file requester from a macro. For this to
  127.    work you must have V 34 of Arp.Library in your libs: directory.
  128.    To call the requester include a macro that looks like this:
  129.  
  130.    \lal\`\&arf\r\s\2
  131.  
  132.    This will open the requester on the top screen when you press the
  133.    Left-alt and ` (top left of the keyboard) together. Obviously you
  134.    can make the key combination anything you want. 
  135.    When you have selected a file from the requester, the next left mouse
  136.    button click will cause the selected file (including disk and dir)
  137.    to be entered into the window where you click. The character delay
  138.    (2 in the above example) will be observed.
  139.    
  140.    There are a couple of ways to modify the string that is generated:
  141.    
  142.     
  143.    Holding down Left Shift when you click will insert a right Amiga x
  144.    at the start of the characters; this is useful for clearing existing
  145.    data out of a string gadget.
  146.  
  147.    Holding down CTRL will submit the directory for the first mouse click
  148.    and the file for the second. This is useful for filling in strings
  149.    where the directory and file are in separate gadgets (in Dpaint, for 
  150.    example).
  151.  
  152.    Holding down CTRL+Left Shift when you click will submit the directory
  153.    and file names separately and precede each with a Right Amiga x.
  154.  
  155.  
  156. 2. I check for some more snooze shapes in this version. Snooze blank
  157.    suppression should now work on Dpaint, Professional Page and Draw Plus.
  158.  
  159.  
  160.  
  161. Version 3.07 changes
  162. ~~~~~~~~~~~~~~~~~~~~
  163.  
  164. 1. The Mouse Speed menu item contains entries 7 and 8; these entries 
  165.    give additional speed.
  166.  
  167. 2. The Blank Pointer menu item now contains a Snooze Off entry.
  168.    When it is checkmarked the pointer will not blank if it is 
  169.    a snooze pointer. This can avoid having to move the mouse to
  170.    see if an operation is complete when the pointer has been blanked.
  171.  
  172. 3. A couple of bugs are fixed.
  173.  
  174.  
  175. Version 3.06 changes
  176. ~~~~~~~~~~~~~~~~~~~~
  177.  
  178.  
  179.     A bug in the screen blanker caused an occasional guru; V3.06
  180. fixes this.
  181.  
  182.  
  183.  
  184. Version 3.05 changes
  185. ~~~~~~~~~~~~~~~~~~~~
  186.  
  187.      The arc file contains 'WTFPATCH3', an improved version of the 
  188. WindowToFront patch. Include 'WTFPatch3' in your start-up sequence, 
  189. but make sure you remove the old version of the patch (WTFPatch) first.
  190.    
  191.  
  192.     'WTFPatch3' corrects an Intuition bug in WindoToFront and
  193. WindowToBack. To use it, simply put the 'WTFPatch3' program in your
  194. c: directory and include 'WTFPatch3' in your startup sequence.
  195.  
  196.     Previous versions of the clock had timing code designed to get
  197. around the Intuition bug. The patch is more effective and should
  198. eliminate machine lockups caused by WindowToFront. Since the timing
  199. code has been removed from V3.05 and above, you must run 'WTFPatch3' with this 
  200. version of the clock.
  201.  
  202.  
  203.  
  204. Program Description
  205. ~~~~~~~~~~~~~~~~~~~
  206.  
  207.  
  208.  
  209.      This utility combines a clock, mouse accelerator, screen blanker,
  210. window manipulator, function keys and macros. 
  211.  
  212.     The display is a  small  borderless  window  which  shows the
  213. total memory left in the system  (chip  and fast) and the time in
  214. 12 hour format. The  window  pops  to  the front of the workbench
  215. screen once every  minute. 
  216.  
  217.     You can start the program with a 'Run ClockDJ' or 'Runback ClockDJ'.
  218. (Do NOT use  Workbench 1.3 'run >nil:' or the ARP Arun NOIO commands. 
  219. Only RunBack will work correctly in this situation). 
  220.  
  221. Using 'Runback' is useful if you want to close ALL CLI windows. If you start
  222. the clock with 'Runback', the output which is directed to the default CLI
  223. will not be seen. This is not usually a problem since this output is typically
  224. of the '[CLI 3]' variety. 
  225.  
  226.     If you use 'Runback' to start the program, command macros 
  227. (those ending with a '\c') MUST specify output and input redirection to
  228. nil:. Eg.:                 ~~~~
  229.  
  230. \lal\b\run <nil: >nil: blitz\r\c
  231.  
  232. If you do not do this the MACHINE WILL GURU.
  233.    
  234. If you want to start the clock with a 'run' so that the output from macros
  235. to the default CLI is preserved, but the startup CLI is to be closed,
  236. do something like this:
  237.  
  238. newcli "con:0/0/580/200/AmigaDOS " from df0:command.file
  239. endcli > nil:
  240.  
  241. "commands.file" is a file located on df0: containing the following:
  242.  
  243. run clockdj
  244.  
  245.  Starting the clock in this way preserves the file handle of the CLI
  246. which launched the clock and passes it to programs started by the macros.
  247.  
  248.  
  249.  
  250. Start-up parameters
  251. ~~~~~~~~~~~~~~~~~~~
  252. "r" specified as the first parameter will reverse the action of the
  253. mouse buttons for the features that require both to be depressed.
  254. The default is "n", for normal operation.
  255.  
  256. The "Newcli" entry in the menu may now be changed by specifying a second
  257. parameter when starting the clock. Eg.:
  258.  
  259.         run clockdj n NewWsh con:0/0/640/150/Myname
  260.  
  261. Note that if the second parameter is specified, the first parameter must
  262. also be specified.
  263.  
  264.  
  265. Arp File requester
  266. ~~~~~~~~~~~~~~~~~~
  267.  
  268.    The Arp file requester can be called from a macro. For this to
  269. work you must have V 34 of Arp.Library in your libs: directory. To call
  270. the requester include a macro that looks like this:
  271.  
  272.    \lal\`\&arfx\r\s\2
  273.  
  274. where x is either 1 or 2. The numbers change the colour scheme
  275. of the requester,
  276.  
  277.    This will open the requester on the top screen when you press the
  278. Left-alt and ` (top left of the keyboard) together. Obviously you
  279. can make the key combination anything you want. 
  280.  
  281. When you have selected a file from the requester, the next left mouse
  282. button click  will cause the selected file (including disk and dir)
  283. to be entered into the window where you click. The character delay
  284. (2 in the above example) will be observed.
  285.   
  286. There are a couple of ways to modify the string that is generated:
  287.  
  288.     
  289. Holding down Left Shift when you click will insert a right Amiga x
  290. at the start of the characters; this is useful for clearing existing
  291. data out of a string gadget.
  292.  
  293. Holding down CTRL will submit the directory for the first mouse click
  294. and the file for the second. This is useful for filling in strings
  295. where the directory and file are in separate gadgets (in Dpaint, for 
  296. example).
  297.  
  298. Holding down CTRL+Left Shift when you click will submit the directory
  299. and file names separately and precede each with a Right Amiga x.
  300.  
  301.  
  302. If '&arf' is specified as the string, no other characters are
  303. valid in the string field other than 1 or 2 (to change the colours).
  304.  
  305.  
  306.  
  307.  
  308. Window manipulation
  309. ~~~~~~~~~~~~~~~~~~~
  310.  
  311. The following can be selected from the menu or by clicking the correct
  312. combination of mouse buttons:
  313.  
  314.  
  315. 1. Screen blanking after a pre-defined period of inactivity.
  316.  
  317. 2. Pointer blanking after a pre-defined period of inactivity.
  318.  
  319. 3. Mouse accelerator.
  320.  
  321. 4. Sun mouse.
  322.  
  323. 5. Click the window to front with the left mouse button.
  324.  
  325. 6. Click the window to back by pressing the left mouse button followed by the
  326.    right mouse button, with the left button still down.
  327.  
  328. 7. Cycling through screens by pressing the right mouse button followed by the
  329.    left mouse button with the right button still down.
  330.  
  331. 8. Left-Amiga-m will shuffle screens if "Screen Cycle" is selected.
  332.  
  333.  
  334. The button sequences for 6. and 7. can be reversed by specifying the
  335. parameter "r" when starting the clock: eg:
  336.  
  337. run clockdj r
  338.  
  339.  
  340. All the above can be selected my menus and saved in the configuration
  341. file.
  342.  
  343.  
  344. Delete Window
  345. ~~~~~~~~~~~~~
  346. The program will allow the user to select a window and remove it
  347. from the screen while leaving the task that started it unaffected. 
  348.  
  349. To do this, point at the window you want to remove, hold the 
  350. Left-shift+Left-Amiga+Control keys down and press the left mouse button;
  351. the window should disappear. To bring the window back hold
  352. Left-shift+Left-Amiga+Control keys and press the right mouse button.
  353.  
  354. Up to 60 windows can be hidden in this way. When retrieving windows
  355. the last one removed is brought back first. A separate list of hidden windows
  356. is maintained for each screen, so only the windows for the active screen are
  357. retrieved.
  358.  
  359. I put this feature in because my workbench screen is often cluttered
  360. with small windows opened by tasks like VirusX. These windows serve no useful
  361. purpose and I decided I would like a means of removing them.
  362.  
  363. Restrictions: 
  364.  
  365. 1. CLI windows cannot be removed. Doing so confuses things and ends in a guru,
  366.    so the CLI windows are ignored when selecting a window to hide.
  367.  
  368.  
  369. 2. Some programs look at their window size; FileInjector does this. If the
  370.    small FileInjector window is hidden and the hot key sequence is used, the
  371.    resulting window is smaller than it should be. The solution is one of: don't
  372.    hide this type of window; retrieve the window before the hot key; retrieve
  373.    the window after the hot key. The last option would require a window refresh
  374.    too (move the window).
  375.  
  376. 3. You should use this feature with caution. Some programs don't expect
  377.    to have other tasks interfere with their windows and gurus can occur.
  378.    Generally, if the window holds only text then there will not be a problem.
  379.  
  380.  
  381.  
  382. Changing the window size of the clock display
  383. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  384.  
  385. The size of the clock window can be changed by hitting 
  386. Left-shift+Left+alt+Right-shift+up arrow or down arrow. This will allow the
  387. characters of larger fonts to be displayed correctly.
  388.  
  389. The size will be saved in the config file when "Save" is selected
  390. from the menu. 
  391.  
  392.  
  393. Moving the clock window to another screen
  394. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  395.  
  396.     The clock window can be popped to the next screen
  397. immediately by holding down the left shift key while clicking the
  398. left mouse button in the clock window.
  399.  
  400.     This feature works whatever is selected in the Pop to Front
  401. menu item.
  402.     
  403.  
  404. Menu options
  405. ~~~~~~~~~~~~
  406.  
  407. NewCLI
  408. ------
  409.  
  410. Gives you a new CLI window at the bottom of the screen.
  411.  
  412.  
  413.  
  414. Chip/Fast
  415. ---------
  416.  
  417. This option gives chip and fast memory displays separately. When selected
  418. the menu toggles to "Total Memory" to enable you to get back to a total
  419. memory display.
  420.  
  421.  
  422.  
  423. Colour
  424. -----
  425.  
  426. Allows you to select the colour of the clock display.
  427.  
  428.  
  429.  
  430. Priority
  431. --------
  432.                      
  433. The default priority of the clock is 2 which seems to work OK in most
  434. circumstances. Setting it to 0 makes it the same priority as other 
  435. tasks  started  from CLI. Making it negative gives it a lower priority
  436. than other CLI tasks. This option gives you a choice of running the clock
  437. from -3 to +4. I found the negative values useful while running a Basic
  438. drawing program: anything above -1 made the drawing process
  439. jerky.
  440.  
  441.  
  442.  
  443. Refresh
  444. -------
  445.  
  446. This is the maximum rate at which the program will update the display.
  447. The default is 5 times per second and the options allow from 10 times
  448. to once per second. I  only  do an PrintIText if something has changed,
  449. so even 10 times per second does  not  use much CPU - you can
  450. use pm to see how much.  
  451.  
  452.  
  453. Blank Screen
  454. ------------
  455.  
  456. The screen will blank after the specified time (in minutes) if there is no
  457. keyboard or mouse activity.
  458.  
  459.  
  460. Blank Pointer
  461. -------------
  462.  
  463. The mouse pointer will blank after the specified time (in seconds) if there is
  464. no mouse activity.
  465.  
  466. When the Snooze Off entry is checkmarked the pointer will not blank if it is 
  467. a snooze pointer. This can avoid having to move the mouse to
  468. see if an operation is complete when the pointer has been blanked.
  469.  
  470.  
  471. Mouse Speed
  472. -----------
  473.  
  474. Accelerates the mouse pointer. 1 is no acceleration.
  475.  
  476.  
  477.  
  478. Click to front
  479. --------------
  480.  
  481. Clicking the left mouse button in a window the specified number of
  482. times will bring it to the front.
  483.  
  484.  
  485. Click to front now gives you the option of keeping or discarding 
  486. the last of the left mouse button clicks which brings the window to front. 
  487.  
  488. There is a 'Discard' sub-menu item under 'Click to Front'. 
  489. If 'Discard' is checked the last mouse click is discarded.
  490.  
  491. The difference this option makes is mainly seen when the last
  492. mouse click is on an icon or other field you wish to select. To find
  493. out which to use, experiment.
  494.  
  495.  
  496. Click to back
  497. -------------
  498.  
  499. Click the window to back by pressing the left mouse button followed by the
  500. right mouse button the specified number of times.
  501.  
  502.  
  503. Note that this sequence can be reversed by specifying "r" as a start-up
  504. parameter
  505.  
  506.  
  507. Sun Mouse
  508. ---------
  509.  
  510. Activates the window the pointer is above without having to click the left
  511. mouse button.
  512.  
  513.  
  514.  
  515. Screen Cycle
  516. ------------
  517.  
  518.  
  519. Cycling through screens by pressing the right mouse button followed by
  520. the left mouse button with the right button still down.
  521.  
  522. Note that this sequence can be reversed by specifying "r" as a
  523. start-up parameter
  524.  
  525. The screen cycle can also be triggered by hitting Left-Amiga-m.
  526.  
  527.  
  528. Key Activate
  529. ------------          
  530.  
  531. If this feature is used, the window under the pointer will be activated
  532. when a key is depressed.
  533.  
  534. Pop to Front
  535. ------------
  536.  
  537. Selecting this item causes the clock to pop to the front of the 
  538. current screen if 'Windows' is selected, or to the top screen if
  539. 'Screens' is selected.
  540.  
  541.  
  542. Map Keys
  543. --------
  544.  
  545. When checked, the key mapping and macro functions are active.
  546.  
  547.  
  548. Load Keys
  549. ---------
  550.  
  551. Loads in a new set of key and macro definitions.
  552.  
  553.  
  554. Save
  555. ----
  556.  
  557. If you select "Save", all the current settings, including the window
  558. position, will be written to a file called "clockdj.config" in the 
  559. root directory of sys:. You should be careful to ensure that sys: is
  560. assigned to the correct disk so that the file can be read when the clock
  561. is next started.
  562.  
  563.  
  564. The next time clockdj starts it will attempt to read this file and set
  565. up the clock and associated parameters exactly as they were when you 
  566. selected "Save".
  567.  
  568. You should select this option when you are happy with the way the clock
  569. looks, and then make sure you have the disk with the clockdj program 
  570. on it assigned to sys:. 
  571.  
  572.  
  573.  
  574. Quit
  575. ----
  576.  
  577. Ends the program.
  578.  
  579.  
  580. Macros and redefining the keys
  581. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  582.  
  583. ClockDJ will allow you re-map the keyboard, substitute a string
  584. of characters for a single key depression, or execute a command when
  585. a particular key sequence is pressed. The key definitions and macros
  586. must be created by you and saved in a file; the default file read when
  587. the program starts is sys:clockdj.keys. The key definitions can be changed
  588. by selecting Load Keys from the menu.
  589.  
  590.  
  591.  
  592.    Pressing CTRL-` (the "ctrl" key and the "`" key) is an escape for
  593. the next key/mouse sequence entered. This will prevent translation or
  594. macro generation on  the next key/mouse sequence. 
  595.  
  596.  
  597.  
  598. NB. 'Map Keys' must be selected from the menu to activate the macro
  599.     function.
  600.  
  601.  
  602. The statement format is:
  603.  
  604. \xxx,yyy\z\wwwwww\r\s\5
  605. |    |   |   |    k c |
  606. |    |   |   |    | | |_The delay between each character in 10ms increments.
  607. |    |   |   |    | | 
  608. |    |   |   |    | |_ s = string; c = command
  609. |    |   |   |    |
  610. |    |   |   |    |_ r = replace character with the string or command
  611. |    |   |   |       k = generate string or command, but keep the original
  612. |    |   |   |           character.
  613. |    |   |   |
  614. |    |   |   |_ String to be generated, or command to be executed.
  615. |    |   |   
  616. |    |   |_ Character to be re-mapped. 
  617. |    |
  618. |    |_ List of qualifiers (see below), separated by commas.
  619. |
  620. |
  621. |_ Delimiter.
  622.  
  623.  
  624. Delimiter
  625. ---------
  626.  
  627. A "\" is the character used to delimit fields. If you wish to include 
  628. one in the string, precede it with a "^".
  629.  
  630. Qualifiers
  631. ----------
  632.  
  633. This defines which keys must be pressed with the re-map character
  634. to generate the string or command. eg., you may want the qualifiers to be
  635. left shift and right alt. If no qualifiers are needed to trigger the re-map, 
  636. the statement would start with a "\\".
  637.  
  638. Multiple qualifiers are specified by separating them by commas: eg.,
  639. "lsh,lat,ctl".
  640.  
  641.  
  642.  
  643. The valid qualifiers are: (all in lower case)
  644.  
  645. lsh    Left shift.
  646. rsh    Right shift.
  647. clo    Caps lock.
  648. ctl    Control (CTRL).
  649. lal    Left alt.
  650. ral    Right alt.
  651. lam    Left Amiga.
  652. ram    Right Amiga.
  653.  
  654.  
  655. The above qualifiers must be specified in lower case.
  656.                      ~~~~
  657.  
  658. Character to be re-mapped.
  659. ------------------------
  660.  
  661. This field is either a single character - "w", for example - or
  662. a string of characters which represents a single character.
  663. If a single character is specified it must be in lower case; if you want
  664. the upper case character re-mapped you must use two statements with
  665. "lsh" and "rsh" qualifiers. This also applies to keys like "{", "!"
  666. etc. whose lower and upper case representations are different.  
  667.  
  668. Valid strings are: (in lower case)
  669.  
  670. f01    The function keys. 
  671. f02            |
  672. f03            |
  673. f04            |
  674. f05            |
  675. f06            |
  676. f07            |
  677. f08            |
  678. f09            |
  679. f10            V
  680.  
  681. hel     Help key.
  682. esc     Escape key.
  683. tab     Tab key.
  684. bsp     Backspace key.
  685. ret     Return key.
  686. del     Delete key.
  687. upa     Up arrow.
  688. lea     Left arrow.
  689. doa     Down arrow.
  690. ria     Right arrow.
  691. kp0     Key pad 0.
  692. kp1     Key pad 1.
  693. kp2     Key pad 2.
  694. kp3     Key pad 3.
  695. kp4     Key pad 4.
  696. kp5     Key pad 5.
  697. kp6     Key pad 6.
  698. kp7     Key pad 7.
  699. kp8     Key pad 8.
  700. kp9     Key pad 9.
  701. kp.     Key pad ..
  702. kp-     Key pad -.
  703. kpe     Key pad enter.
  704. kp)     Key pad ).
  705. kp(     Key pad (.
  706. kp/     Key pad /.
  707. kp+     Key pad +.
  708. arf    Arp file requester  (valid in the string field only).
  709.  
  710. The above keys must be specified in lower case.
  711.                ~~~~
  712.  
  713.  
  714.  
  715. String
  716. ------
  717.  
  718. The string of characters which will replace the character to
  719. be re-mapped. 
  720.  
  721. Version 3.00 will accept special keys (del, bsp, for example) in the string.
  722. They are specified by preceding the key name with a "&". For example,
  723. "&del" would be delete, "&ret" would be return, etc. Any key listed above
  724. in the "Character to be re-mapped" section can be specified in this way (still
  725. in lower case).
  726.  
  727. Previous version of the program allowed a limited set of control characters
  728. in the string by using the "^". This will still work. The characters
  729. which can be defined in this way are:
  730.  
  731.  
  732. ^[   Escape.
  733. ^h   Backspace.
  734. ^i   Tab.
  735. ^m   Return.
  736.  
  737. The "^" and "\" can be included in the string by preceding them
  738. with a "^".
  739.  
  740.  
  741. A character in a macro string may now include a qualifier. 
  742. Any of the qualifiers listed above under "Qualifiers" are valid.
  743. The qualifier is preceded by a "%" and multiple qualifiers are
  744. separated by commas. Eg., 
  745.  
  746. "%lal,%ctla" 
  747.  
  748. (in lower case)  would specify left-alt-control-a.
  749.  
  750. Multiple qualifiers should be separated by commas. This can be useful
  751. for entering data in a string gadget (a file requester, for example).
  752. The file name you want in the requester may be "myfile"; specifying
  753. "%ramxmyfile" in the string would clear the gadget before filling it
  754. with "myfile".
  755.  
  756.  
  757.  
  758. The string should appear in the active window.
  759.  
  760. Each statement can be up to 1000 characters long.
  761.  
  762.  
  763. Replace/Keep
  764. ------------
  765.  
  766.  
  767. An "r" causes the re-mapped character to be replaced with the
  768. string or command. A "k" will keep the re-mapped character.
  769.  
  770. This must be specified in lower case.
  771.  
  772.  
  773. String/Command
  774. --------------
  775.  
  776. An "s" will submit the string into the input stream: it should
  777. appear in the active window.
  778.  
  779. A "c" will execute the string as a command. A "^m" (CR) or "&ret" at the end
  780. of the command is not needed. The command will be launched from the clock
  781. task AT THE SAME PRIORITY AS THE CLOCK; the default clock priority is 2.
  782. Some programs do not run well at priority 2 -  eg Txed, Excellence, Blitz -
  783. since they use input handlers running at priority 0. To avoid this kind of
  784. problem either run the clock at priority 0 or use the ARP Arun command and
  785. set the priority of the new task to 0.
  786.  
  787.  
  788. This must be specified in lower case.
  789.  
  790.  
  791. Delay
  792. -----
  793.  
  794. Some programs will not accept a continuous stream of characters in
  795. the input stream. CygnusED and Online! will not, for example. The delay 
  796. value will delay each character by the value*15 milliseconds. Eg.,
  797. a value of 5 specifies 75 ms. CLI windows do not need a delay; you should
  798. experiment to find out whether a program you are using needs the delay.
  799.  
  800. The delay field can be between 0 and 9.
  801.  
  802. If the delay is omitted, a delay of 0 is assumed.
  803.  
  804. Examples
  805. ~~~~~~~~
  806.  
  807.  
  808. \\f01\run  >nil: <nil: ed\r\c
  809.  
  810. Will run ed . Notice that no qualifier was specified
  811. for the function key F1. The redirection to nil: is to prevent unwanted
  812. messages in the console window.
  813.  
  814.  
  815.  
  816.  
  817. \ctl,lsh\f01\dir df0:\r\c
  818.  
  819. When CTRL, left shift and F1 are depressed a dir df0: will execute and the
  820. result will appear in the window belonging to the cli which started ClockDJ.
  821. This would work only if ClockDJ has NOT been started with 'RunBack'.
  822.  
  823.  
  824.  
  825. \lal\t\run >nil: <nil: Terminals:gt/gt\r\c
  826.  
  827. Run GT when left-alt t is depressed.
  828.  
  829.  
  830.  
  831.  
  832. \lal\esc\newcli <nil: >nil:\r\c
  833.  
  834. Start a new cli when Left-alt esc is depressed.
  835.  
  836.  
  837.  
  838.  
  839. \lal\n\David Jenkins\r\s\5
  840.  
  841. Submit the string when left-alt n is depressed and insert a 50 ms delay
  842. between each character.
  843.  
  844.  
  845.  
  846. \lal\m\Inter-Office Correspondence&ret&retFrom:  David Jenkins&ret&retTo:&ret&retSubject:&ret&ret______________________________________________________________________________&ret&ret\r\s\5
  847.  
  848. Submit the string when left-alt m is depressed and insert a 50 ms delay
  849. between each character..
  850.  
  851.  
  852. \clo\`\~\r\s
  853. \clo\1\!\r\s
  854.  
  855.  
  856. Convert Caps lock "`" and "1" to "~" and "!".
  857.  
  858.  
  859. \lal\f\%ramxdf0:file1\r\s
  860.  
  861.  
  862. Is useful for putting a string into a requester. The "%ramx" will submit a
  863. Right Amiga-x which will clear the string gadget before submitting the
  864. "file1" string.
  865.  
  866.  
  867.  
  868.  
  869.  
  870.  
  871.  
  872.  
  873.                               ARexx Macros
  874.                               ~~~~~~~~~~~~
  875.  
  876.     ClockDJ versions 4.00 and above contain an ARexx port.  The clock
  877. is  an  ARexx  host  and will accept commands from an ARexx program; the
  878. commands  are  listed below.  If a result is expected it will be returned
  879. in  the  special  ARexx  variable  'result';  any commands which return a
  880. result should have a 'options results' statement in the program.
  881.  
  882.  
  883. Title of ClockDJ
  884. ----------------
  885.  
  886.     The clock window has a title of 'ClockDJ' (case sensitive);
  887. you can use this title in some of the ARexx macros. For an example of this
  888. take a look at Move.Rexx and Move2.Rexx.
  889.  
  890.  
  891. Host Name
  892. ---------
  893.  
  894.     The host name of ClockDJ is CLOCKDJ (in capitals).
  895.  
  896.  
  897. Errors
  898. ------
  899.  
  900.     Errors are reported by setting a return code (the RC variable).
  901.  
  902. A return code of 20 is set for an unrecognized command.
  903.  
  904. A  return  code  of 10 is set for an invalid parameter (an invalid window
  905. address, for example).
  906.  
  907.  
  908. Commands
  909. --------
  910.  
  911. NOTE:  when executing commands which manipulate windows (like MOVE), be
  912. careful  not  to submit too many requests for the same window without a
  913. pause  between  the  requests.   Intuition  gets upset if it receives a
  914. request  for  a window before it has acted on the previous request; the
  915. ARexx   function  'delay'  (in  rexxsupport.library)  can  be  used  to
  916. accomplish this:  eg., 'call delay 5'.
  917.  
  918.  
  919.  
  920.  
  921.     ACTIVATEWINDOW    address        
  922.  
  923.  
  924. Activate the window with this address. The window may be on any screen.
  925.  
  926.  
  927.                            *******************
  928.  
  929.      COLOUR    nn    
  930.  
  931.  
  932. Change the colour of the clock display to nn (0-11).  Note: nn
  933. corresponds to a colour item menu selection
  934.  
  935.  
  936.                            *******************
  937.  
  938.  
  939.      CHIP         
  940.  
  941. Change the clock to display chip/fast memory.
  942.  
  943.  
  944.                            *******************
  945.  
  946.  
  947.      DELAY    value        
  948.  
  949.  
  950. Specify an inter-character  delay value in microseconds for injected data.
  951. The delay value remains in effect for all injected data; if you want to
  952. reset it to zero, submit a 'delay 0' command.
  953.  
  954.                            *******************
  955.  
  956.  
  957.      FILEREQUESTER
  958.  
  959.  
  960. Call the Arp file requester.  The full pathname of the selected file will
  961. be  returned  in  'result'.   If  'cancel'  is  selected  on the Arp file
  962. requester, a null string will be returned in 'result'.
  963.  
  964.  
  965.                            *******************
  966.  
  967.  
  968.      GETACTIVEWINDOW      
  969.  
  970.  
  971. Gets the active window address and returns it in 'result'.
  972.  
  973.  
  974.                            *******************
  975.  
  976.  
  977.     GETNEXTWINDOW    address        
  978.  
  979.  
  980. Get  the  address  of  the  next window on a screen.  The parameter is an
  981. address of a window.
  982.  
  983.                            *******************
  984.  
  985.  
  986.  
  987.      GETPOINTERWINDOW          
  988.  
  989.  
  990. Get the address of the window under the pointer. The address is returned
  991. in 'result'.
  992.  
  993.  
  994.                            *******************
  995.  
  996.  
  997.     GETSCREEN    title
  998.  
  999.  
  1000.  
  1001. Get  the  screen  address  from  the  title.  Note that the title is case
  1002. sensitive.  The address is returned in 'result'.
  1003.  
  1004.  
  1005.                            *******************
  1006.  
  1007.     
  1008.     GETTITLEOFSCREEN address    
  1009.  
  1010.  
  1011. Get a screen title from a screen address. The title is returned in
  1012. 'result'.  
  1013.  
  1014.  
  1015.                            *******************
  1016.  
  1017.  
  1018.      GETTOPSCREEN
  1019.  
  1020.  
  1021. Get the address of the top screen. The address is returned in 'result'.
  1022.  
  1023.  
  1024.                            *******************
  1025.  
  1026.  
  1027.      GETWINDOW    title
  1028.  
  1029.  
  1030. Get  the  address of the window with this title.  The address is returned
  1031. in  'result'.  Note that 'title' is case sensitive; make sure you specify
  1032. the exact title.  The window can be on any screen.
  1033.  
  1034.  
  1035.                            *******************
  1036.  
  1037.  
  1038.  
  1039.      HIDEWINDOW    address        
  1040.  
  1041.  
  1042. Hide the window with the specified address.
  1043.  
  1044.  
  1045.                            *******************
  1046.  
  1047.  
  1048.      INJECT    CLICK    data    
  1049.  
  1050.  
  1051. Injects  data  into  the window where you click the left mouse button.  A
  1052. small  window will appear on the top screen asking you to click where you
  1053. want  the  data  injected.   The  data to be injected is specified by the
  1054. second  operand.  If you precede the data by a hex '01' ('01'x in ARexx),
  1055. a Right Amiga+x will be inserted to clear a string requester).
  1056.  
  1057.  
  1058.                            *******************
  1059.  
  1060.  
  1061.      INJECT    ACTIVE    data
  1062.  
  1063.  
  1064. Injects data into the active window. The data to be injected is specified
  1065. by the second operand.
  1066.  
  1067.  
  1068.                            *******************
  1069.  
  1070.  
  1071.      INJECT    address    data
  1072.  
  1073.  
  1074. Injects  data into the window with the the address specified in the first
  1075. operand.  The data is specified by the second operand.
  1076.  
  1077.  
  1078.                            *******************
  1079.  
  1080.  
  1081.      LOADKEYS filename
  1082.  
  1083.  
  1084. Load new key definitions from the specified file name.
  1085.  
  1086.  
  1087.                            *******************
  1088.  
  1089.  
  1090.     MOVEWINDOW    address x-position y-position    
  1091.  
  1092.  
  1093. Move  a  window  to  a  new  position.   The  first parameter is a window
  1094. address,  the  second  is the X position and the third is the Y position.
  1095. If you attempt to move a window outside a screen's limits a return code of
  1096. 10 will be set.
  1097.  
  1098.  
  1099.                            *******************
  1100.  
  1101.  
  1102.     POPUP        OFF        
  1103.             WINDOWS
  1104.             SCREENS
  1105.  
  1106.  
  1107. Set the popup status of the clock.
  1108.  
  1109.  
  1110.                            *******************
  1111.  
  1112.  
  1113.     QUALIFIER  'nnnn'x  
  1114.  
  1115.  
  1116. Set  a key qualifier for injected data.  The qualifier is 2 hex bytes and
  1117. the values are explained below. This feature is useful if you want to
  1118. inject,  for  example,  a  Right Amiga+Right Shift+Return.  The qualifier
  1119. remains  set  for  all injected data, so you must reset it.  A normal key
  1120. depression has a qualifier of '8000'x (relative mouse).
  1121.  
  1122. NOTE:   this  is  only  effective for data injected with INJECT ACTIVE or
  1123. INJECT address.  It will not work with INJECT CLICK.
  1124.  
  1125.  
  1126.  
  1127. Qualifiers
  1128. ----------
  1129.  
  1130. IEQUALIFIER_LSHIFT    EQU   $0001        Left shift
  1131. IEQUALIFIER_RSHIFT    EQU   $0002        Right Shift
  1132. IEQUALIFIER_CAPSLOCK    EQU   $0004        Caps Lock
  1133. IEQUALIFIER_CONTROL    EQU   $0008        CTRL
  1134. IEQUALIFIER_LALT    EQU   $0010        Left Alt
  1135. IEQUALIFIER_RALT    EQU   $0020        Right Alt
  1136. IEQUALIFIER_LCOMMAND    EQU   $0040        Left Amiga
  1137. IEQUALIFIER_RCOMMAND    EQU   $0080        Right Amiga
  1138. IEQUALIFIER_RELATIVEMOUSE     EQU   $8000   Reset to this value.
  1139.  
  1140.  
  1141. NB. OR the bits together to set a qualifier: eg: '8022'x is Right shift+
  1142.     Right alt+Relative mouse.  You should always include the relative mouse 
  1143.     bit.
  1144.  
  1145.  
  1146.                            *******************
  1147.  
  1148.  
  1149.      RETRIEVEWINDOW     address    
  1150.  
  1151.  
  1152. Retrieve the hidden window with this address.
  1153.  
  1154.  
  1155.                            *******************
  1156.  
  1157.  
  1158.      SCREENFLIP
  1159.  
  1160.  
  1161. Push the top screen to the bottom.
  1162.  
  1163.  
  1164.                            *******************
  1165.  
  1166.  
  1167.     SCREENFORWINDOW    address    
  1168.  
  1169.  
  1170.  
  1171. Get  the address of the screen which contains this window.  The parameter
  1172. is a window address. The address is returned in 'result'.
  1173.  
  1174.  
  1175.                            *******************
  1176.  
  1177.  
  1178.     SCREENTOFRONT    address        
  1179.  
  1180.  
  1181.  
  1182. Bring the screen with this address to the front.
  1183.  
  1184.  
  1185.                            *******************
  1186.  
  1187.  
  1188.      TOTAL             
  1189.  
  1190. Change the clock to display total memory.
  1191.  
  1192.  
  1193.                            *******************
  1194.  
  1195.  
  1196.  
  1197.     WINDOWTOBACK    address        
  1198.  
  1199.  
  1200.  
  1201. Push the window with this address to the back.
  1202.  
  1203.  
  1204.                            *******************
  1205.  
  1206.  
  1207.     WINDOWTOFRONT    address
  1208.  
  1209.  
  1210.  
  1211.  
  1212. Bring the window with this address to the front.
  1213.  
  1214.  
  1215.  
  1216.  
  1217.                         David Jenkins.
  1218.