home *** CD-ROM | disk | FTP | other *** search
/ Frozen Fish 1: Amiga / FrozenFish-Apr94.iso / bbs / alib / d5xx / d553 / addmenu.lha / AddMenu / AddMenu.Doc < prev    next >
Text File  |  1991-10-28  |  15KB  |  323 lines
  1.         AddMenu V1.53 (19th Aug 1991) by Nic Wilson
  2.         -------------------------------------------
  3.  
  4.                 Written totally in Assembler
  5.                 ----------------------------
  6.                  using Hisoft Devpac Amiga 
  7.                  -------------------------
  8.                   on an Amiga A3000 25mhz
  9.                   -----------------------
  10.  
  11.          Nic Wilson Software
  12.          138d South Street
  13.          Toowoomba Qld 4350
  14.          Australia  
  15.          Ph (076) 358384 Work or FAX
  16.             (076) 358539 After hours
  17.             
  18.          EMAIL {cbmvax|cbmehq}!cbmaus!wilson!nic@uunet.uu.net   
  19.  
  20.          This program has been placed on Shareware for your enjoyment
  21.          You may distribute it freely as long as this document and the 
  22.          program remains unmodified, and accompanies the program.  
  23.          You may modify the script files as examples as long as you 
  24.          FULLY test them before distribution.
  25.  
  26.          If you like the program, a donation would be appreciated,
  27.          and the latest version of this and other programs will be sent
  28.          to you if requested.
  29.  
  30.          FUNCTION
  31.          --------
  32.          Add an infinite number of Menu Items to the Workbench Tools 
  33.          Menu in Kickstart V2.0 using script files.  Updating is 
  34.          possible from the menus, from CLI or from Workbench using
  35.          different script files.  Temporary menu items can also be 
  36.          added that stay in the menu strip after upating to new script.
  37.  
  38.          REQUIREMENTS
  39.          ------------
  40.          Any Amiga running V2.0 of Kickstart and Workbench including
  41.          the A3000. Tested to versions 37.157 Kickstart and Workbench 37.66
  42.  
  43.          HISTORY
  44.          -------
  45.          V1.0   Original release.
  46.          V1.1   Added ability to use different script name/path
  47.          V1.2   Added quit and update options
  48.          V1.3   Added ability to change scripts on update
  49.          V1.31  Optimised and fixed error msg for illegal use
  50.                 under kickstart V1.3. 
  51.                 Fully checked with 'Enforcer' for bugs.
  52.          V1.40  New temporary menus via workbench icon added
  53.                 and ability to update or remove from this icon.
  54.          V1.41  Stopped illegal devices, drawers or non-executables
  55.                 being added to the menu strip.  These will cause
  56.                 workbench screen to flash.
  57.                 Added switch for temporary menus, so you do not have
  58.                 to have the icon around if you do not use them.
  59.                 Added the ability to remove the temporary menus alone.  
  60.                 V1.42   Fixed bug.  If Temporary menus were removed, they would
  61.                 magically reappear when a script was changed.
  62.         V1.50   Fixed bug.  When updating to new script, old script memory 
  63.                 buffers were not being freed.   
  64.                 Added ability for each menu item to have more than one 
  65.                 executable(SEE 'COMMAND STRINGS' or 'EXAMPLE SCRIPT' BELOW).
  66.         V1.51   Added an 'About' menu automatically, this allows for easy
  67.                 identification of version number, author and info on its
  68.                 free distribution permission.  The About menu will always
  69.                 be at the top of any function you have added in your script.
  70.         V1.52   Very sorry but the new about function didn't work in hi-res
  71.                 I only use Interlace and I negelected to test other res modes.
  72.                 It is now fixed and will work in all res modes.        
  73.         V1.53   Changed launch code so the program can be called before 
  74.                 Workbench is available.  This allows the program to be called
  75.                 from the user-startup instead of the startup-sequence.  The
  76.                 program will detach itself and then hang around and wait
  77.                 until workbench is available before installing.  Also changed
  78.                 it so it can be launched from Workbench and gave it a commodity
  79.                 icon.  You can drag this into the WBSTARTUP drawer to launch
  80.                 it if you prefer.  If you do it this way the default script
  81.                 MUST be s:addmenu.script as WB parameters are not supported
  82.                 yet.
  83.         V1.54   Removed ability to run from Workbench beacause of severe
  84.                 problems in DOS being able to find things.  Run it from the
  85.                 user-startup and it is much better.                
  86.                         
  87.          IMPORTANT
  88.          ---------
  89.          DO NOT USE RUN OR RUNBACK, ADDMENU WILL RETURN THE CLI
  90.          TO YOU AND ALLOW IT TO CLOSE WHEN YOU GIVE AN ENDCLI.
  91.  
  92.          ADDMENU WORKS IN RATHER A SPECIAL WAY, IN ORDER TO ALLOW THE 
  93.          CLI WINDOW TO CLOSE AFTER LAUNCH IT RELAUNCHES ITSELF AGAIN 
  94.          WITH SPECIAL CODE, THIS IS DONE TO OVERCOME ALL THE NORMAL PROBLEMS 
  95.          ASSOCIATED WITH THIS.
  96.          YOU WILL NOTICE THAT SOME PROGRAMS LOSE THE PATH, STACK,
  97.          CURRENT DIRECTORY ETC, THIS IS ESPECIALLY TRUE OF PROGRAMS
  98.          WRITTEN IN C.  ADDMENU DOES NOT SUFFER FROM ANY OF THESE
  99.          PROBLEMS.  POPCLI TYPE PROGRAMS SUFFER BADLY FROM THIS, MY
  100.          AUTOCLI USES THIS SAME CODE AND SUFFERS NO PROBLEM.  IT IS
  101.          PUBLIC DOMAIN SO SEND S.S.A.E. AND DISK FOR THE LATEST VERSION.  
  102.          
  103. USAGE
  104. *****
  105.          AddMenu [script] [switch]  
  106.  
  107.          Standard redirection of output is supported. 
  108.  
  109.          EG. Addmenu >nil: [script]  [switch] 
  110.         
  111. [switches]
  112.  
  113.   -q     AddMenu must already be running for this switch to be used.
  114.          This switch allows the currently running AddMenu to be removed. 
  115.          If AddMenu is not found running an error message will result.
  116.          If this switch is used then it must be the only parameter.
  117.          To remove from workbench see 'To Remove Addmenu Completely'
  118.          below. 
  119.          
  120.   -t     Do not use temporary menus and do not place the icon on the
  121.          Workbench screen.       
  122.  
  123. [script] 
  124.          This is an optional parameter, and can be used when AddMenu is 
  125.          first launched or when updating.  By default it reads a script  
  126.          created by you, called 'addmenu.script'.  This file is expected 
  127.          to be in the S: directory , but if you wish to supply a
  128.          different path and name you can use the script parameter.  If 
  129.          this parameter is used you must supply the path to the file and 
  130.          its name.  There is an example file that accompanies this file 
  131.          to show you how to create it.  Below is an explanation of the 
  132.          script file.
  133.          
  134.          EG. AddMenu DH0:s/myscript
  135.          
  136. FROM Workbench
  137. --------------
  138.          This ability has been removed.
  139.  
  140. TEMPORARY MENU ITEMS
  141. ********************
  142.  
  143.          This function will default to on unless the -t switch was 
  144.          used at launch. AddMenu will place a special icon on the 
  145.          workbench window.  If a program is dragged and dumped over 
  146.          this icon, that program will appear at the bottom of the 
  147.          menu strip.  The program itself will not move at all and 
  148.          doing this is quite safe. These temporary menus will survive 
  149.          an update that changes to a different script.  They will 
  150.          continue to appear on the bottom of whatever script you 
  151.          update with. Once added they can be removed without removing 
  152.          AddMenu completely by double clicking on the special icon and
  153.          selecting the 'REMOVE TEMP' gadget from the window.   
  154.          If any illegal device or non-executable file is dumped over
  155.          the icon the screen will flash and a beep sound will be heard, 
  156.          and it will not be added to the menu.
  157.         
  158. ADDMENU's SPECIAL ICON
  159. **********************
  160.          
  161.          This icon does not behave like a normal icon, it is a special
  162.          icon that allows manipulation of AddMenu from the workbench.
  163.          Double clicking the icon will open a window with five gadgets.  
  164.          These gadgets allow AddMenu to be removed, temporary menus 
  165.          removed, updating a script or to cancel the operation.  They 
  166.          are all explained in the relative sections below.  This icon 
  167.          has not been given any specific position on the workbench window.  
  168.          Workbench will choose the best position for the icon, it can 
  169.          of course be dragged to any place you wish.  I may add the abilty
  170.          to snapshot in a future version.
  171.          
  172.  
  173. CANCELLING THE WINDOW
  174. *********************
  175.          If you double clicked the special icon, the window opened, and
  176.          you changed your mind and wish to exit without changes.  Click
  177.          the 'CANCEL' gadget or the CLOSE gadget on the window.  This will
  178.          abort the operation and AddMenu will be unchanged. 
  179.  
  180. UPDATING ADDMENU ONCE RUNNING
  181. *****************************
  182. From CLI
  183. --------         
  184.          If AddMenu is already installed when launched again, then it will
  185.          send a message to the running version to update itself,  If no
  186.          script is supplied then it will update from the default file.
  187.          A different script can be supplied as the update, and because this
  188.          update can called from inside an addmenu script, this allows you to
  189.          change the entire menu, by calling a menu funtion.  This allows for 
  190.          an infinite number of available menu functions.  If a different 
  191.          script is supplied to the current one then it will totally replaced
  192.          in favour of the new script.  This new script could of course
  193.          have an option to return to the original or any number of other
  194.          scripts.
  195.         
  196. From Workbench 
  197. --------------
  198.          Double click the special AddMenu icon that appeared on the 
  199.          workbench window when AddMenu was launched.  A window will
  200.          open.  Enter a new script path and filename into the string
  201.          gadget and then press RETURN or click the OK gadget.  The 
  202.          menus will be updated if your new script was found and was
  203.          valid.  
  204.  
  205. TO REMOVE ADDMENU COMPLETELY
  206. ****************************
  207. From CLI
  208. --------
  209.          Launch AddMenu again with the -q switch. (SEE Usage Above)
  210.          This could also be done by placing an entry in your script
  211.          file so quitting could be done from the menus.
  212.  
  213. From Workbench  
  214. --------------
  215.          Double click the special icon that appeared on the Workbench
  216.          window when AddMenu was launched.  Click the REMOVE ALL Gadget.
  217.          AddMenu will be completely removed.
  218.  
  219. TO REMOVE THE TEMPORARY MENUS
  220. *****************************
  221. From CLI
  222. --------        
  223.          Not possible.
  224.  
  225. From Workbench only
  226. -------------------
  227.          Double click the special icon that appeared on the Workbench
  228.          window when AddMenu was launched.  Click the REMOVE TEMP Gadget.
  229.          All temporary menus will be removed.  They cannot be removed
  230.          individually.
  231.  
  232. THE SCRIPT FILE
  233. ***************
  234.  
  235.          The script file is a group of commands you would like in the
  236.          menu along with the text you want in the actual menu. 
  237.          The format of this script is important for the program to read 
  238.          it correctly.  If the number of menu items in a single script
  239.          overflows the screen height,  the menu strips will be made
  240.          wider and the items split into columns.  The maximum number
  241.          of menus items in a single script is 63, but due to a bug
  242.          in workbench.library this is not checked for, any extra menus
  243.          over this amount will be clipped, athough I dont forsee anyone
  244.          placing this many in a single script.  The structure of the
  245.          script file is as follows.
  246.  
  247. TEXT STRINGS
  248. ------------
  249.          The text strings are actually placed in the menu, and each one
  250.          must be before its command string.  The Text string must start 
  251.          and end with a plus (+) sign.
  252.  
  253. COMMAND STRINGS
  254. ---------------
  255.          The command strings are the strings that are sent to DOS when
  256.          a menu item is selected.  Each one must come directly after
  257.          its text string and start and end with an asterisk (*).  There
  258.          are now any number of commands allowed per text string,  
  259.          DO NOT USE THE 'RUN' COMMAND WITHIN A COMMAND STRING,  'RUN'
  260.          WILL BE ADDED TO THE FRONT OF YOUR STRING AUTOMATICALLY.
  261.  
  262. END OF FILE MARKER
  263. ------------------
  264.          The script file must end with a hash (#) sign on the beginning
  265.          of a new line.
  266.  
  267. COMMENTS
  268. --------
  269.          Comments are allowed in the script file but must follow certain
  270.          guidelines.  They are allowed on a line of their own or beside
  271.          a text string or command string. They must be outside the command
  272.          or text string characters.  The best way to ensure this is to
  273.          leave at least one space before the beginning of the comment after 
  274.          the rightmost plus (+) or asterisk (*) of each comment or text
  275.          string.  They MUST NOT use the plus (+) sign, the asterisk (*) 
  276.          or the hash (#) sign within the comment, as these three 
  277.          characters are used to specify the beginning and end of command,
  278.          texts strings or end of file.  Comment lines are completely 
  279.          optional, you do not have to have any at all.
  280.  
  281. EXAMPLE OF A VALID SCRIPT 
  282. -------------------------
  283. ;this is a valid comment
  284. this is a valid comment
  285.     this is still a valid comment
  286. +NEWSHELL+                      ;Text for the menu surrounded in plus signs
  287. *c:newshell*                    ;commands surrounded in asterisk signs
  288.                                 comments are allowed between menu strings
  289. +NoVirus+                       this is still a valid comment
  290. *dh0:novirus*                   notice the path to the above command 
  291.                                 how to execute a group of commands
  292.                                 by executing a standard batch file.
  293. +WordPerfect+
  294. *execute s:wpscript*            the wp script would contain commands needed 
  295. +XCOPY+                         to assign and run it
  296. *dh0:copiers/xcopy*             now we give option to quit addmenu
  297. +Quit Addmenu+
  298. *addmenu -q*
  299.                                 now we show how to change menus or update
  300. +PageStream+                    This example shows executing a number of        
  301. *assign fonts1: dh0:pagestream* commands after a single text string.
  302. *assign fonts2: dh0:pagestream*
  303. *assign pagestream: dh0:pagestream*
  304. *assign drivers: dh0:pagestream*
  305. *cd dh0:pagestream*
  306. *dh0:pagestream/pagestream*
  307. +Another Menu+                  the next following menu.
  308. *addmenu s:different.script*
  309. #
  310.          Notice the 'end of file' marker (#) on the end of the script.
  311.          Please send comments, bug reports etc to the address at the 
  312.          top of this file.
  313.  
  314.          Nic Wilson
  315.  
  316.  
  317.  
  318.         
  319.  
  320.  
  321.  
  322.         
  323.