home *** CD-ROM | disk | FTP | other *** search
/ World of A1200 / World_Of_A1200.iso / programs / system / ambush1.03a / docs / ambush.doc next >
Text File  |  1995-02-27  |  15KB  |  365 lines
  1.  
  2.  
  3.  
  4.                                Ambush User Guide
  5.  
  6.                        Copyright ©1993 Silicon Based Life
  7.  
  8.  
  9.  
  10.  
  11.                        Contents
  12.  
  13.  
  14.                        1. What does Ambush do?
  15.  
  16.                        2. How do I make it work?
  17.  
  18.                           2.1 From the shell.
  19.                           2.2 From an icon.
  20.                           2.3 With a particular package.
  21.                           2.4 The Ambush Control Window.
  22.  
  23.                        3. Who are Silicon Based Life?
  24.  
  25.                        4. And what do they want?
  26.  
  27.  
  28.  
  29. 1. WHAT DOES AMBUSH DO?
  30.  
  31. A short story,
  32.  
  33. Once upon a time, the Amiga's operating system existed in versions 1.2/1.3.
  34. Although hard to believe to those that never started there, these versions
  35. had no 3 dimensional buttons, a colour scheme popular with 70's interior
  36. decorators, and all the text was displayed in topaz 8, especially the
  37. default text for the title bars of windows etc.  Many great Amiga programs
  38. were written and still function flawlessly even on the very latest version
  39. of Workbench, thanks to careful observation of Amiga programming rules and
  40. practices.  Cute furry animals skip and jump in the forest, picking flowers
  41. and singing love songs.
  42.  
  43. An evil demon lurks in the trees however.  What many programmers failed to
  44. do, was to explicitly specify the topaz 8 font in their programs, relying
  45. on the fact that the system font would always be set to topaz.  With the
  46. arrival of Workbench 2 and above, a new preferences program allows the user
  47. to change the default screen font into a much larger, often
  48. proportional typeface, to make workbench look more attractive and title bar
  49. text and menus easier to read (this is especially important with the advent
  50. of AGA and the 1942 monitor, and also display cards such as the Retina,
  51. which both allow flicker free high resolution Workbench screens).  As a
  52. matter of trivia, this practice of not specifying, but assuming topaz, was
  53. not correct even under 1.3, as the then global preferences program allowed
  54. the selection of 60 column topaz over 80 column topaz causing text to spew
  55. from the right side of gadgets and other objects.
  56.  
  57. Many of the old programs described and even some new ones (I have even
  58. found a shareware program which REQUIRES Workbench 3 that does this - no
  59. names) have not had the simple changes made, but are still on sale and
  60. become unusable, or simply unpleasant to look at and embarrassing to run in
  61. anything other than topaz 8.  Having found this problem with a number of
  62. programs, such as the Professional Page and Professional Draw utilities
  63. (Gold Disk), Trace, Clipmap, Makefont... and Real 3D 1.4.x/ Classic
  64. (RealSoft) utilities DeltaConvert, DeltaToIFF... I mused that a program to
  65. intercept just these programs and provide them with the environment they
  66. require (a topaz workbench screen) would be a worthwhile investment of my
  67. time, if only for my own use.  Shortly afterwards, Ambush was born.
  68. The fluffy bunnies once again danced through the flower meadows to the
  69. song of Nightingales.
  70.  
  71. If you have never run Workbench with a 22 point title bar font such as I
  72. do, you may have never experienced what I describe, Ambush therefore is not
  73. for you.  If you do use a large screen font, but have not experienced this
  74. problem, then you are far richer than I, to be able to afford the latest
  75. versions of the software.  If you boot all your software from floppy then
  76. you can set the prefs for the individual disks, and it is probably set
  77. right to start with anyway.
  78.  
  79. Naturally, from the description, you will require at least workbench 2 to
  80. use Ambush.
  81.  
  82.  
  83. DEVELOPERS.
  84.  
  85. Ambush may also be of use to developers, who may wish to test programs for
  86. their appearance on a standard 640x256 four colour workbench (Ambush always
  87. uses 640 across regardless of overscan settings). This neatly avoids the
  88. hassle of changing the preferences settings (Close all windows...). Indeed
  89. I used Ambush to ensure that the accompanying AmigaGuide document looked
  90. correct by ambushing MultiView.
  91.  
  92.  
  93.  
  94. 2. HOW DO I MAKE AMBUSH WORK?
  96. 2.1 RUNNING AMBUSH FROM A SHELL.
  97.  
  98. Ambush is designed to be run from the shell or from a script.
  99. The general format of the Ambush command line is as follows,
  100.  
  101.      AMBUSH D=DELAY/N/K,L=LACE/S,N=NO3D/S,A=ACTIVATE/S,C=COMMAND/F/A
  102.  
  103. What this all means is,
  104.  
  105.      DELAY: This allows you to adjust the time in seconds (up to 10
  106.             minutes) for the ambushing of your command to be completed. You
  107.             would want to do this if for example, the command that you run
  108.             takes a number of seconds to open it's window(s). (It loads in
  109.             from a floppy disk?)
  110.  
  111.             The default time is 2 seconds, after which control is returned
  112.             to the Workbench screen.  If you find that your application is
  113.             opening onto the Workbench, try increasing this value.
  114.             (Alternatively see ACTIVATE below.)
  115.  
  116.             Example: 1.SYS:> ambush delay=10 calculator
  117.                  or: 1.SYS:> ambush d=10 calculator
  118.  
  119.  
  120.       LACE: This puts the Ambush screen into interlace mode.
  121.  
  122.  
  123.       NO3D: This suppresses the Workbench 2 and higher 3D intuition look
  124.             (buttons etc.) and sets the colour scheme to the 1.3 style
  125.             (Yuck!)
  126.  
  127.             Example: 1.SYS:> ambush lace no3d calculator
  128.                  or: 1.SYS:> ambush l n calculator
  129.  
  130.  
  131.   ACTIVATE: This makes the ambush screen stay active, regardless of the
  132.             DELAY setting.  You may return control to the Workbench screen
  133.             manually by using the `Ambush Control' window.
  134.             You would do this if a program opens further windows onto the
  135.             Workbench in response to your actions (and hence the delay
  136.             option is inappropriate).
  137.  
  138.             Example: 1.SYS:> ambush a calculator
  139.  
  140.  
  141.    COMMAND: The rest of the command line (no double quotes required) is the
  142.             command which you want to ambush, along with any arguments, as
  143.             if you had typed it directly at the command line prompt.  If
  144.             you simply wish to open the Ambush screen, use a command of "",
  145.             that is, an empty string, (You WILL need the quotes to do this,
  146.             of course).
  147.  
  148.             Examples: 1.SYS:> ambush d=5 l n calculator tape con:
  149.                       1.SYS:> ambush calculator
  150.                       1.SYS:> ambush ""
  151.  
  152.  
  153.  
  154. 2.2 RUNNING AMBUSH FROM AN ICON.
  155.  
  156. Ambush is not designed to be run directly from the workbench, but to be set
  157. up in such a way that it appears to run automatically - You double click an
  158. icon to run the application of your choice, the Ambush screen appears, and
  159. then the application opens onto it.  However, to make this magic work, does
  160. require a little work.
  161.  
  162. Following are the steps that you must follow (in the shell) to set up an
  163. application to run on an Ambush screen from it's icon. I will use a program
  164. sys:tools/calculator in my example. It is not a program that needs
  165. ambushing, but, is handy to illustrate the process.
  166.  
  167.  
  168. 1) Install Ambush once, somewhere on the search path - I like to keep mine
  169.    in SYS:Utilities. (Alternatively place it into the same directory as
  170.    each program you intend to ambush, if there is only a couple.)
  171.  
  172.    1.SYS:> copy df0:Ambush to SYS:Utilities
  173.  
  174.  
  175. 2) Change directory to where the program you want to ambush is kept.
  176.  
  177.    1.SYS:> cd SYS:tools
  178.  
  179.  
  180. 3) Rename the program to a different name, (but not the .info file)
  181.  
  182.    1.SYS:tools> rename Calculator Calculator2
  183.  
  184.  
  185. 4) Create a simple script file that would ambush your program, using the
  186.    old name of your application for the script (remember to use Ambush on
  187.    the new name of the  application or you will create an `endless loop'.
  188.  
  189.    1.SYS:tools> ed Calculator
  190.  
  191.    ------------------------------------ While inside ed.
  192.    ambush calculator2                   Remember to use new name!
  193.    ------------------------------------ <esc><x>.
  194.  
  195.    A number of options are available as command line switches. See the
  196.    section `Running Ambush from the shell' for a detailed description of
  197.    these.
  198.  
  199.  
  200. 5) Load the Icon Editor (IconEdit) and load the .info file for your
  201.    application (calculator.info).  Go to the `Type' menu and change the
  202.    icon type from `Tool' to `Project' and then save the icon again.
  203.  
  204.  
  205. 6) Now find the icon on the workbench screen and select it (click once).
  206.    Select `Information' from the `Icon' menu.  Change the `Default Tool' to
  207.    read `iconx' and save (not yet if you have Workbench 2).
  208.  
  209.    If you have Workbench 3, everything is now complete, you can double
  210.    click on the icon and (hopefully) run your application.
  211.  
  212.    If you have Workbench 2, create a `Tool Type' which reads,
  213.  
  214.                 WINDOW=CON:0/0//256/IconX/AUTO/CLOSE
  215.  
  216.    the AUTO bit is the important bit, as it stops the irritating window
  217.    that iconx produces from opening, unless some output occurs (which can
  218.    always be redirected to nil: in the script).
  219.  
  220.  
  221.    PROGRAMS THAT REQUIRE LARGE STACKS.
  222.  
  223.    In order to ambush programs requiring stack space of greater than
  224.    4096 bytes, you will need to create two scripts,
  225.  
  226.    ------------------------------------ file: calculator.script
  227.    stack 50000
  228.    calculator2                          (remember, this is the program)
  229.    ------------------------------------
  230.  
  231.    ------------------------------------ file: calculator
  232.    ambush d=5 execute calculator.script
  233.    ------------------------------------
  234.  
  235.    What you are simply doing is ambushing the script file
  236.    (calculator.script) rather than ambushing the calculator directly,
  237.    this gives you the opportunity to issue a stack command before executing
  238.    the program.
  239.  
  240.  
  241.  
  242. 2.3 USING AMBUSH WITH A PARTICULAR PACKAGE
  243.  
  244. If you examine the directory `AmbushScripts', you will find script files
  245. for a number of packages for which Ambush has been used.  If you cannot
  246. find the exact one you need, the selection works as a useful library of
  247. examples of the simple process.  You will need to follow the procedure
  248. described in `Running Ambush from an icon'.
  249.  
  250.  
  251. IMPORTANT!
  252.  
  253. You must remember to rename the original package before copying the files.
  254. Remember you must ALWAYS keep/use backups of your software (and esp. your
  255. hard disk).
  256.  
  257.  
  258.  
  259. 2.4 AMBUSH CONTROL WINDOW
  260.  
  261. On the Ambush screen, in the bottom right corner, you will find a small
  262. title bar window called `Ambush Control'.  When highlighted a menu is
  263. available which has just a few simple options.
  264.  
  265.  
  266.   Project/Active/Normal (Workbench)
  267.                 /Ambush
  268.  
  269.     These allow you to make either the Ambush or Workbench screen the
  270.     currently active screen.  So, if you have a program which opens a new
  271.     window when you click on a button, which because of the way the program
  272.     is written, would open the new window onto Workbench, you may
  273.     temporarily change the active screen to make it appear in the right
  274.     place.  You may also use these options to make Ambush active and then
  275.     double click on a program icon on the Workbench screen.
  276.  
  277.   Project/About
  278.  
  279.     Tells you what version of Ambush you are running, along with our
  280.     excellent autoscaling logo...
  281.  
  282.   Project/Quit
  283.  
  284.     Normally, Ambush will shut down when the last application window is
  285.     closed.  However, if you ambush a program which then fails to open it's
  286.     window or you simply typed `ambush ""' then you are left with an Ambush
  287.     screen with nothing on it.  Use the quit option to shut down Ambush.
  288.     (If any applications still have a lock on the screen, then Ambush will
  289.     refuse, informing you that you still have applications running - not
  290.     unlike Workbench's behaviour to a quit.)
  291.  
  292.  
  293.  
  294. 3. WHO ARE SILICON BASED LIFE?
  295.  
  296. Silicon Based Life are a small group of dedicated Amiga enthusiasts, who
  297. enjoy to use and to develop for the machine.  We attempt to understand and
  298. to appreciate all that is the technological masterpiece that the Amiga
  299. range represents and try to present it in it's best light in what ever way
  300. we can find.
  301.  
  302. We are a varied group of individuals, each with differing levels of
  303. experience, but all with a passion for getting the best out of our
  304. equally diverse Amiga computers.
  305.  
  306. Please enjoy your Amiga, in the knowledge that you have the finest in
  307. computer hardware that your money could buy.  Thankyou.
  308.  
  309.  
  310.  
  311. 4. WHAT DO SBL. WANT?
  312.  
  313. Ambush is freeware, however if you want to help us, please send a letter or
  314.  a pretty postcard to the address below, stating which product (Ambush) you
  315. are using.  This allows us to gauge the response to each completed package
  316. and to therefor direct our activities as best as possible.  Money is of
  317. course welcome, but, must be in UK pounds (lots of them!).
  318.  
  319. If you have any suggestions or have discovered a bug, please write with a
  320. detailed description to
  321.  
  322.  
  323.                            James Ling
  324.  
  325.                            93 Weatherbury Way
  326.                            Dorchester
  327.                            Dorset     DT1 2EE
  328.                            England
  329.  
  330.  
  331. Please remember that it is helpful to include a description of your
  332. Amiga setup - model, RAM size, Hard disk, monitor type, esp. when reporting
  333. possible faults.
  334.  
  335. Writing does not guarantee a reply, (an SAE increases your chances), but I
  336. will try to reply to most sensible correspondence.
  337.  
  338.  
  339. DISCLAIMER
  340.  
  341. Silicon Based Life does not take any responsibility for any damage, loss of
  342. data, caused directly or indirectly by the use of Ambush or any of the
  343. associated material.  A standard text accompanies each package, Legal.doc,
  344. which must accompany the package when it is duplicated.
  345.  
  346.  
  347. DISTRIBUTION
  348.  
  349. Ambush may be distributed freely, however, we request that only a minimal
  350. fee should be charged to cover the duplication service (if you have paid
  351. more than a couple of quid, you've been ripped off.)
  352.  
  353. The package must be distributed in full, that is, the following files must
  354. be present,
  355.           Ambush
  356.           Start-Ambush
  357.           Start-Ambush.info
  358.           docs/Ambush.Guide
  359.           docs/Ambush.doc
  360.           docs/Legal.doc
  361.           AmbushScripts/#?
  362.  
  363. Please write to confirm if you wish to include Ambush as part of a large
  364. distribution such as a coverdisk.
  365.