home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 408.lha / MyMenu_v1.1 / MyMenu.DOC < prev    next >
Encoding:
Text File  |  1990-09-04  |  9.7 KB  |  252 lines
  1. MyMenu 1.1 Documentation
  2.  
  3. MyMenu is a program to allow you to create your own menus in the WorkBench
  4. to run your own commands.  This can save you the hassle of opening up lots
  5. of drawers or starting a CLI before executing a command.  MyMenu will allow
  6. you to execute both CLI and WorkBench programs, and is configured with a
  7. normal text file.
  8.  
  9. Compiling:
  10.  
  11.   MyMenu and MyMenu-Handler are included in the distribution file.
  12.   However, the source is also included for your enjoyment.
  13.  
  14.   There is a supplied Makefile, which works with Manx 5.0, and which
  15.   should work with most make programs.  I haven't tried to get this
  16.   to work with 16-bit integers, or to work with Lattice.
  17.  
  18.   There are some defines in MyMenu.h that can be customized.  DO_WB
  19.   determines if support for WorkBench programs is included.  Undefining
  20.   this can save a lot of space if you don't need this option.  DO_PATH
  21.   if defined will compile in code for path searching for commands.
  22.   Currently, it is undefined.
  23.  
  24. Installation:
  25.  
  26.   Copy MyMenu to the C: directory, or elsewhere in your path.
  27.  
  28.   Copy MyMenu-Handler to the L: directory.  MyMenu will also look
  29.   for this file in the current directory if it does not exist in
  30.   the L: directory.
  31.  
  32.   Create the file S:MyMenu.conf.  The format of this file is described
  33.   later.
  34.  
  35. Running:
  36.  
  37.   Step one is to start up the Workbench!
  38.   
  39.   The command "MyMenu" will load and start up the handler process.
  40.   The new menus should now appear in the WorkBench menu strip.
  41.   
  42.   Running MyMenu while the handler is already loaded will cause
  43.   it to re-parse the configuration file and rebuild the menus.
  44.  
  45.   The command "MyMenu quit" will terminate and unload the handler
  46.   process.
  47.  
  48.   MyMenu may be run from the startup-sequence, but MUST be placed after
  49.   "loadwb".
  50.  
  51. Using MyMenu:
  52.  
  53.   After running MyMenu, hold down the right mouse button while in the
  54.   Workbench screen.  The new menus should appear in addition to the
  55.   normal menus (Workbench, Disk, and Special).  You may select one of
  56.   the items in the new menus (or submenus) to run the program associated
  57.   with that item in the MyMenu.conf file.
  58.  
  59. Configuration file:
  60.  
  61.   The configuration file "MyMenu.conf" defines the menus you want, and what
  62.   commands they will run. The file is read when you run MyMenu.
  63.   It will be searched for in the S: directory, and then in the current
  64.   directory.
  65.  
  66.   You may put carriage returns between keywords, but you cannot put a
  67.   carriage return in the middle of a command.  Comments begin with a #,
  68.   and continue until the end of the line.  The parser is not case-sensitive.
  69.  
  70.   CONFIGURATION FILE COMMANDS:
  71.  
  72.   COLOR n
  73.  
  74.     This will set the foreground pen color for new menus.  You can
  75.     change this as often as you want.  The arguments is number that is
  76.     the pen number to use.  The default is 2 (black).
  77.  
  78.   MENU [<command-char>] menu-name item-name [sub-item-name] | command-def
  79.  
  80.     Defines a new menu.  Each menu definition must have a menu-name and
  81.     an item-name.  A sub-item-name is optional.  If any of these names
  82.     contain whitespace, enclose the name in double quotes, or precede
  83.     the whitespace character with a backslash (\).  A command character
  84.     may be defined for the menu item by putting the character after the
  85.     MENU keyword and surround it with <>'s.
  86.  
  87.     Separate the menu definition and the command definition with a vertical
  88.     bar (|).  After the bar, you can have the keywords CLI or WB, to
  89.     specify that the command is a CLI or WorkBench command.  Everything
  90.     after WB until the end of the line is taken to be the command.
  91.     Everything after CLI until a space or end of the line is taken to be
  92.     the command.  Everything else will be passed as arguments to the
  93.     CLI command.
  94.  
  95.     Specify the complete path (beginning with device) for all commands.
  96.  
  97.   Examples:
  98.  
  99.     menu Games Tetrix | WB dh0:games/tetrix
  100.  
  101.       This will define a menu "Games", with a menu item "Tetrix".
  102.       If this is selected, the command "dh0:games/tetrix" will be run
  103.       as a WorkBench program.
  104.  
  105.     menu <B> Games "Black Box" | WB df0:Black Box
  106.  
  107.       This will define a menu item "Black Box" under the menu "Games".
  108.       The menu Games will already exist from the previous example, and
  109.       will now contain "Tetrix" and "Black Box" as items.  The command
  110.       to be run is "df0:Black Box" (Box is not an argument).
  111.       The menu can also be selected by typing <Amiga>-B.
  112.  
  113.     color 3
  114.     menu  Utilities DMouse "Start DMouse" | c:DMouse
  115.     menu  Utilities DMouse "Quit DMouse" | c:DMouse quit
  116.  
  117.       This will define two sub menu items (drawn in orange).  The second
  118.       command has an argument.
  119.  
  120. Suggestions for making your configuration file:
  121.  
  122.   Since MyMenu offers so much flexibility, you have the ability to be
  123.   creative when designing your menus.  To start, look at the included
  124.   sample configuration file "MyMenu.conf".  Here are some suggestions
  125.   to help you build your own menus:
  126.  
  127.   How many menus do I need?
  128.  
  129.     While one menu is sufficient, you are may wish to make up to 3-5 menus.
  130.     The only limit is the length of the menu bar.  The shorter the menu
  131.     titles, the more menus that are possible.
  132.  
  133.     I like to use three menus:  Utilities, Demos, and Programming.
  134.     Almost everything I want to do from MyMenu fits into one of these
  135.     three categories.
  136.  
  137.     Submenus can be used to further divide each category.  For example,
  138.     submenus under "Utilities" might include Editors, Workbench, and
  139.     Dmouse.  Editors would then include ED, STVI, NewZap, etc.; Dmouse
  140.     could include "Dmouse On", "Dmouse Off", "Screen Blanker On", etc.
  141.  
  142.   Should I use "WB" or "CLI" for programs that can be run either way?
  143.  
  144.     Generally, use whichever works better for you.  I use "WB" whenever
  145.     possible, since it tends to use a little less memory and starts
  146.     programs a little more quickly.  However, if a program is started
  147.     using "CLI", you may exit MyMenu without terminating the program.
  148.     Also, some text editors will save an icon with a text file if it was
  149.     run using "WB", but will not if run using "CLI".
  150.  
  151.     Another note when using "CLI": some applications may require that you
  152.     ALIAS a certain logical device name to the application's directory.
  153.     This can be added to your startup-sequence, but running the program
  154.     using "WB" instead of "CLI" will usually solve the problem.
  155.  
  156.     Of course, many programs may only be run using "CLI", and a few require
  157.     that you use "WB".  Most will run either way.
  158.  
  159.   What is the best way to open a shell from MyMenu?
  160.  
  161.     Since MyMenu works on any WB program, you may simply tell it to run the
  162.     Shell icon.  For example, you might use the line:
  163.  
  164.       Menu <S> Utilities Workbench "Open Shell" | WB SYS:Shell
  165.  
  166.     This will create an item called "Open Shell" in the submenu
  167.     "Workbench" in the menu titled "Utilities".  When selected,
  168.     a shell will be opened which has the same features, path, etc. as
  169.     a shell run by double-clicking on the icon "Shell" in the SYS:
  170.     directory.  The shell can also be opened by typing right-amiga-S
  171.     after clicking on the workbench screen.
  172.  
  173.   Can I execute a script from MyMenu?
  174.  
  175.     Yes.  One way is to attach a Project icon to the script file with
  176.     a default tool type of "C:IconX" and run the script from MyMenu in
  177.     "WB" mode.  This will open a text input/output window for the script.
  178.  
  179.     Another way is to use the CLI command "Execute" followed by the script
  180.     file name.
  181.  
  182.   Why won't MyMenu run my program?
  183.  
  184.     There are several possible sources of problems:
  185.       - The path should complete, beginning with a device: (DF0: SYS:)
  186.       - Do NOT use the .info extention for WB programs.
  187.       - Check all spelling and paths
  188.       - Try using the other mode ("CLI" vs. "WB")
  189.       - It is possible that the program is not compatable with MyMenu
  190.  
  191.   If you encounter a problem with MyMenu, or find a program that MyMenu
  192.   will not run, please let me know.  Contact Darin Johnson or John Baker
  193.   (see end of file).
  194.  
  195. Future plans and hopeless dreams:
  196.   AREXX support.
  197.   A better parser.
  198.   Support for graphical menu items.
  199.  
  200. Limitations, bugs, and other weird things:
  201.  
  202.   Line limit of 256 characters in configuration file.
  203.  
  204.   MyMenu will NOT survive a change of the workbench screen.  If "loadwb"
  205.   is executed while MyMenu is running, MyMenu will still be attached to
  206.   the old workbench screen.  You must run "MyMenu quit" and then "MyMenu"
  207.   to re-establish your menus.
  208.  
  209.   MyMenu may also look strange after changing the workbench text size.
  210.   This may be solved by simply re-running "MyMenu".
  211.  
  212. Acknowledgements:
  213.  
  214.   I have borrowed ideas and code snipits from other public domain
  215.   programs.  I have also received help directly from some people.
  216.   I would like to thank those people (whose names I remember):
  217.   
  218.     Matt Dillon        - Ideas for menu building and how to load in the
  219.                           handler were taken from DME and DMouse.
  220.     Peter da Silva    - Ideas taken from wblaunch program.
  221.     Rob Peck        - Some ideas and help.
  222.     Davide Cervone    - LOTS of ideas taken from MonIDCMP.
  223.  
  224.   And of course, thanks to John Baker for modifying the code to
  225.   version 1.1!  Since free time is a scarce commodity for me now,
  226.   there probably wouldn't have been a new version otherwise.
  227.   
  228. Signatures:
  229.  
  230. Original author (version 1.0):
  231.   Darin Johnson
  232.   djohnson@ucsd.edu
  233.  
  234. Modifications (version 1.1) by:
  235.   John Baker
  236.   jbaker@gmuvax2.gmu.edu
  237.   Voice:         (703) 941-6840
  238.   Hallucination BBS: (703) 425-5824
  239.  
  240.  
  241. I would like to add my thanks to the authors of Runback: Rob Peck,
  242. Greg Searle, and Doug Keller, for providing the source code.
  243.  
  244. Also thanks to Michael Malak, sysop of Hallucination BBS, for technical
  245. programming help, and thanks to Stephen Ford for many suggestions and
  246. help with testing.
  247.  
  248. And most importantly, thanks to Darin Johnson for developing such a great
  249. piece of software, and for supplying me with the source code to work on.
  250.  
  251.                 John Baker
  252.