MyMenu 1.1 Documentation

MyMenu is a program to allow you to create your own menus in the WorkBench
to run your own commands.  This can save you the hassle of opening up lots
of drawers or starting a CLI before executing a command.  MyMenu will allow
you to execute both CLI and WorkBench programs, and is configured with a
normal text file.

Compiling:

  MyMenu and MyMenu-Handler are included in the distribution file.
  However, the source is also included for your enjoyment.

  There is a supplied Makefile, which works with Manx 5.0, and which
  should work with most make programs.  I haven't tried to get this
  to work with 16-bit integers, or to work with Lattice.

  There are some defines in MyMenu.h that can be customized.  DO_WB
  determines if support for WorkBench programs is included.  Undefining
  this can save a lot of space if you don't need this option.  DO_PATH
  if defined will compile in code for path searching for commands.
  Currently, it is undefined.

Installation:

  Copy MyMenu to the C: directory, or elsewhere in your path.

  Copy MyMenu-Handler to the L: directory.  MyMenu will also look
  for this file in the current directory if it does not exist in
  the L: directory.

  Create the file S:MyMenu.conf.  The format of this file is described
  later.

Running:

  Step one is to start up the Workbench!
  
  The command "MyMenu" will load and start up the handler process.
  The new menus should now appear in the WorkBench menu strip.
  
  Running MyMenu while the handler is already loaded will cause
  it to re-parse the configuration file and rebuild the menus.

  The command "MyMenu quit" will terminate and unload the handler
  process.

  MyMenu may be run from the startup-sequence, but MUST be placed after
  "loadwb".

Using MyMenu:

  After running MyMenu, hold down the right mouse button while in the
  Workbench screen.  The new menus should appear in addition to the
  normal menus (Workbench, Disk, and Special).  You may select one of
  the items in the new menus (or submenus) to run the program associated
  with that item in the MyMenu.conf file.

Configuration file:

  The configuration file "MyMenu.conf" defines the menus you want, and what
  commands they will run. The file is read when you run MyMenu.
  It will be searched for in the S: directory, and then in the current
  directory.

  You may put carriage returns between keywords, but you cannot put a
  carriage return in the middle of a command.  Comments begin with a #,
  and continue until the end of the line.  The parser is not case-sensitive.

  CONFIGURATION FILE COMMANDS:

  COLOR n

    This will set the foreground pen color for new menus.  You can
    change this as often as you want.  The arguments is number that is
    the pen number to use.  The default is 2 (black).

  MENU [<command-char>] menu-name item-name [sub-item-name] | command-def

    Defines a new menu.  Each menu definition must have a menu-name and
    an item-name.  A sub-item-name is optional.  If any of these names
    contain whitespace, enclose the name in double quotes, or precede
    the whitespace character with a backslash (\).  A command character
    may be defined for the menu item by putting the character after the
    MENU keyword and surround it with <>'s.

    Separate the menu definition and the command definition with a vertical
    bar (|).  After the bar, you can have the keywords CLI or WB, to
    specify that the command is a CLI or WorkBench command.  Everything
    after WB until the end of the line is taken to be the command.
    Everything after CLI until a space or end of the line is taken to be
    the command.  Everything else will be passed as arguments to the
    CLI command.

    Specify the complete path (beginning with device) for all commands.

  Examples:

    menu Games Tetrix | WB dh0:games/tetrix

      This will define a menu "Games", with a menu item "Tetrix".
      If this is selected, the command "dh0:games/tetrix" will be run
      as a WorkBench program.

    menu <B> Games "Black Box" | WB df0:Black Box

      This will define a menu item "Black Box" under the menu "Games".
      The menu Games will already exist from the previous example, and
      will now contain "Tetrix" and "Black Box" as items.  The command
      to be run is "df0:Black Box" (Box is not an argument).
      The menu can also be selected by typing <Amiga>-B.

    color 3
    menu  Utilities DMouse "Start DMouse" | c:DMouse
    menu  Utilities DMouse "Quit DMouse" | c:DMouse quit

      This will define two sub menu items (drawn in orange).  The second
      command has an argument.

Suggestions for making your configuration file:

  Since MyMenu offers so much flexibility, you have the ability to be
  creative when designing your menus.  To start, look at the included
  sample configuration file "MyMenu.conf".  Here are some suggestions
  to help you build your own menus:

  How many menus do I need?

    While one menu is sufficient, you are may wish to make up to 3-5 menus.
    The only limit is the length of the menu bar.  The shorter the menu
    titles, the more menus that are possible.

    I like to use three menus:  Utilities, Demos, and Programming.
    Almost everything I want to do from MyMenu fits into one of these
    three categories.

    Submenus can be used to further divide each category.  For example,
    submenus under "Utilities" might include Editors, Workbench, and
    Dmouse.  Editors would then include ED, STVI, NewZap, etc.; Dmouse
    could include "Dmouse On", "Dmouse Off", "Screen Blanker On", etc.

  Should I use "WB" or "CLI" for programs that can be run either way?

    Generally, use whichever works better for you.  I use "WB" whenever
    possible, since it tends to use a little less memory and starts
    programs a little more quickly.  However, if a program is started
    using "CLI", you may exit MyMenu without terminating the program.
    Also, some text editors will save an icon with a text file if it was
    run using "WB", but will not if run using "CLI".

    Another note when using "CLI": some applications may require that you
    ALIAS a certain logical device name to the application's directory.
    This can be added to your startup-sequence, but running the program
    using "WB" instead of "CLI" will usually solve the problem.

    Of course, many programs may only be run using "CLI", and a few require
    that you use "WB".  Most will run either way.

  What is the best way to open a shell from MyMenu?

    Since MyMenu works on any WB program, you may simply tell it to run the
    Shell icon.  For example, you might use the line:

      Menu <S> Utilities Workbench "Open Shell" | WB SYS:Shell

    This will create an item called "Open Shell" in the submenu
    "Workbench" in the menu titled "Utilities".  When selected,
    a shell will be opened which has the same features, path, etc. as
    a shell run by double-clicking on the icon "Shell" in the SYS:
    directory.  The shell can also be opened by typing right-amiga-S
    after clicking on the workbench screen.

  Can I execute a script from MyMenu?

    Yes.  One way is to attach a Project icon to the script file with
    a default tool type of "C:IconX" and run the script from MyMenu in
    "WB" mode.  This will open a text input/output window for the script.

    Another way is to use the CLI command "Execute" followed by the script
    file name.

  Why won't MyMenu run my program?

    There are several possible sources of problems:
      - The path should complete, beginning with a device: (DF0: SYS:)
      - Do NOT use the .info extention for WB programs.
      - Check all spelling and paths
      - Try using the other mode ("CLI" vs. "WB")
      - It is possible that the program is not compatable with MyMenu

  If you encounter a problem with MyMenu, or find a program that MyMenu
  will not run, please let me know.  Contact Darin Johnson or John Baker
  (see end of file).

Future plans and hopeless dreams:
  AREXX support.
  A better parser.
  Support for graphical menu items.

Limitations, bugs, and other weird things:

  Line limit of 256 characters in configuration file.

  MyMenu will NOT survive a change of the workbench screen.  If "loadwb"
  is executed while MyMenu is running, MyMenu will still be attached to
  the old workbench screen.  You must run "MyMenu quit" and then "MyMenu"
  to re-establish your menus.

  MyMenu may also look strange after changing the workbench text size.
  This may be solved by simply re-running "MyMenu".

Acknowledgements:

  I have borrowed ideas and code snipits from other public domain
  programs.  I have also received help directly from some people.
  I would like to thank those people (whose names I remember):
  
    Matt Dillon		- Ideas for menu building and how to load in the
                          handler were taken from DME and DMouse.
    Peter da Silva	- Ideas taken from wblaunch program.
    Rob Peck		- Some ideas and help.
    Davide Cervone	- LOTS of ideas taken from MonIDCMP.

  And of course, thanks to John Baker for modifying the code to
  version 1.1!  Since free time is a scarce commodity for me now,
  there probably wouldn't have been a new version otherwise.
  
Signatures:

Original author (version 1.0):
  Darin Johnson
  djohnson@ucsd.edu

Modifications (version 1.1) by:
  John Baker
  jbaker@gmuvax2.gmu.edu
  Voice:	     (703) 941-6840
  Hallucination BBS: (703) 425-5824


I would like to add my thanks to the authors of Runback: Rob Peck,
Greg Searle, and Doug Keller, for providing the source code.

Also thanks to Michael Malak, sysop of Hallucination BBS, for technical
programming help, and thanks to Stephen Ford for many suggestions and
help with testing.

And most importantly, thanks to Darin Johnson for developing such a great
piece of software, and for supplying me with the source code to work on.

				John Baker