Club Amiga de Montreal - CAM/CAM_CD_1.iso/files/337.lha/SuperMenu_v1.51/SuperMenu.doc.pp/SuperMenu.doc

Text File | 1990-02-07 | 25.5 KB | 535 lines

                                 SuperMenu

                        (c) 1989 by Paul T. Miller
                           All rights reserved.

INTRODUCTION

   SUPERMENU is an information display system you can use to quickly and
easily display text files (and sections of text files) with the press of a
button. SuperMenu can be configured by you to perform in a variety of ways -
you have complete control over what buttons appear (and how they look and are
accessed), what section of the text is displayed (and it's position and size
and how it is referenced), how the program is run (and how it operates), and
a variety of other things.
   SuperMenu can be run from the Workbench or CLI, and can be run once or
made resident for immediate activation by a user-defined hot-key. SuperMenu
uses two or more external files - one is the configuration file that makes
the magic (and open-endedness) of SuperMenu possible. With this file you have
complete control over all of SuperMenu's output and operation. The other file
(or files) contain the information you wish to display (usually an ASCII text
file - support is in the works for future additions of picture and sound
files). Each file can be typed in and edited with a standard word processor,
and must be in ASCII format.
   SuperMenu has any number of uses, and it is constantly being updated and
laden with new features. See below for a few examples and the explanation of
SuperMenu's features.

USES

   I) You have an application that you use often, but find yourself looking
      to the manual for help a lot. With SuperMenu, you can type a text file
      with any ASCII word processor. Within the file, you can separate the
      various sections pertaining to a particular function, giving each one
      a specific KEYWORD for which SuperMenu will search. Then you can create
      a configuration file for SuperMenu, describing how you want it to look
      and what functions to have help available for. When you're finished,
      you can run SuperMenu, pick a function from the menu, and SuperMenu
      will display that section of your file, allowing you to scroll through
      it if it's more than a specified height. You can have all your favorite
      help sections separated nicely and instantly available from within
      SuperMenu. (this is the reason SuperMenu was written)

  II) You have a disk with all your favorite game docs on it. You can create
      a configuration file allowing you to select a documentation file to
      flip through at will (and from within games that allow you to multi-
      task).

 III) You've created a personal "disk-magazine" of all of your favorite
      articles. SuperMenu will let you customize your disk so any of these
      is instantly available at a gadget-click away.


FUNCTIONS and PARAMETERS: SuperMenu's custom Configuration File

   With SuperMenu's configuration file, you can set up any of the following
customizable parameters:

   1) SCREEN:     This function is no longer supported (but is still in the
                  function list for future use). SuperMenu windows open up
                  automatically on the front-most screen.

   2) FONT:       The font you want to use in displaying the menu.
                  format = "FONT: Fontname Fontsize"
                  default = "Topaz 8"

   3) COLUMNS:    The maximum number of horizontal columns of menu choices
                  SuperMenu will display.
                  format = "COLUMNS: column_number"
                  default = 3

   4) ROWS:       The maximum number of vertical rows of menu choices
                  SuperMenu will display.
                  format = "ROWS: row_number"
                  default = 15

   5) HSPACING:   Horizontal Spacing, the number of pixels horizontally
                  between each of the menu choices.
                  format = "HSPACING: horizontal_spacing"
                  default = 10

   6) VSPACING:   Vertical Spacing, the number of pixels vertically
                  between each of the menu choices.
                  format = "VSPACING: vertical_spacing"
                  default = 5

   7) TITLE:      The title SuperMenu will display in the menu window. See
                  the NOTE below about string conventions (and the use of the
                  underscore instead of spaces).
                  format = "TITLE: Menu_window_title"
                  default = "SuperMenu v1.01"

   8) KEYS:       This option will automatically generate a keyboard-
                  equivalent for the first 26 menu options (A-Z).
                  format = "KEYS: ON <or> OFF"
                  default = OFF

   9) BOXES:      This option will draw a box around each of the menu
                  choices (making a button appearance).
                  format = "BOXES: ON <or> OFF"
                  default = OFF

  10) STATUS:     This option will display the amount displayed percentage
                  (and number of lines in the section) in the text window.
                  format = "STATUS: ON <or> OFF"
                  default = OFF

  11) FILE:       This defines a default "resident file" that is always in
                  memory (see below).
                  format = "FILE: resident_textfile_path"
                  default = NONE

  12) PREFIX:     This defines a 2-character prefix code used for finding
                  individual sections in the text files (see below).
                  format = "PREFIX: two-character_prefix_code"
                  default = "*:"

  13) JUSTIFY:    This sets the default justification used on your menu text.
                  format = "JUSTIFY: LEFT <or> RIGHT <or> CENTER"
                  default = LEFT

  14) RESIDENT:   This makes SuperMenu start up in the background, and wait
                  until the HELP Key is pressed before it displays its menu.
                  Closing the menu (with the CLOSE gadget) causes SuperMenu
                  to return to background mode until HELP is pressed again.
                  (Note: a feature has been added to customize the hot-key)
                  format = "RESIDENT: ON <or> OFF"
                  default = ON

  15) MENUPOS:    This allows you to set the position of the Menu Window
                  when the program is run (or when you press the hot-key
                  if the program is resident). X and Y are coordinates on
                  the screen. If either (or both) equal -1 then the menu
                  window will be centered in that axis.
                  format = "MENUPOS: left_edge top_edge"
                  default = -1 -1

  16) QUIET:      This turns off any printing of messages (either to the CLI
                  or the Workbench titlebar) by SuperMenu. Beware, you will
                  not know if an error occurs while it's loading, or whether
                  or not it was installed or removed correctly.
                  format = "QUIET: ON <or> OFF"
                  default = OFF

  17) REOPEN:     With this option turned on, SuperMenu will automatically
                  reopen any text files you left open when you made it
                  resident again (when you click on the CLOSEGADGET of the
                  menu window - only works when SuperMenu is made resident
                  with the resident option).
                  format = "REOPEN: ON <or> OFF"
                  default = ON

  18) WINSIZE:    This option allows you to set the size of the text window
                  when you click on an option. If there is not enough text
                  to fit vertically in the window, the window will open up
                  as to the set width, but only tall enough to display the
                  text. If the window is too small horizontally, you may not
                  be able to see all of your text. The window will open up
                  just large enough for the text in either direction if a
                  -1 is set for that size (and will be centered).
                  format = "WINSIZE: horizontal_size vertical_size"
                  default = -1 -1

  19) COMKEY:     User-defined command-key to invoke program. Must be a
                  RAWKEY code in hexadecimal (with "0x" prefix).
                  format = "COMKEY: 0xrawkey_code"
                  default = HELP KEY

  20) QUALIFIER:  User-defined qualifier key use to modify command key. Must
                  be a valid event Qualifier code in hexadecimal (with "0x"
                  prefix). See Qualifier Code Chart below for valid codes.
                  format = "QUALIFIER: 0xqualifier_code"
                  default = NO QUALIFIER

  21) SCRSIZE:    The user-defined size to constrain all SuperMenu output
                  to (width and height). A size of -1 will use the size of
                  that axis of the Workbench Screen.
                  format = "SCRSIZE: screen_width screen_height"
                  default = -1 -1

   If any of the above parameters are ommitted from the configuration file,
the defaults will be used.

NOTE: Any string (used in a screen, title, or file name) MUST have an
   underscore character ("_") in place of ANY spaces in the string. If you
   leave any spaces in the string (except at the end), SuperMenu will only
   display the string up to that space. (So don't forget those underscores!)
   Example: "Screen: Workbench_Screen" or "Title: My_Help_File"

NOTE: When you make SuperMenu resident (with the RESIDENT: command - this
   should NOT be confused with the "resident file" - see below), the only
   way to clear SuperMenu from memory is to press CONTROL-C while the menu
   window is being displayed. (You can also run it again - this will tell
   itself to remove itself :-)


Common Qualifier Codes

Key               Code
----------------  ------
Left SHIFT        0x0001
Right SHIFT       0x0002
Either SHIFT Key  0x0003
CONTROL           0x0008
Left ALT          0x0010
Right ALT         0x0020
Either ALT Key    0x0030
Left AMIGA        0x0040
Right AMIGA       0x0080
Either AMIGA Key  0x00C0


RESIDENT FILE

   Any text file may be made "resident" at the start of the program by
specifying it in the parameter list in the Configuration File.
   SuperMenu will load this text file and keep it resident while SuperMenu
is running. If one of your buttons makes a reference to this file, it will
not have to be loaded again, because it's already in memory. This greatly
improves the speed at which the text is display for often-used text files.


KEYWORDS

   Any text file may be broken down into sections, with each section having
its own "keyword" to help SuperMenu find it. This allows you to have many
different functions explained in one text file, rather than having a bunch
of separate files. Placing all of your function information in one file, and
then making that file resident, completely removes any disk access once the
program is running, and provides almost instant feedback to the text
requested.
   To place keywords in your text file, locate the line just before the
section you want to start at, and type in some identifying word that you want
to be used as a keyword. This word must be on a line of its own, MUST BE IN
ALL UPPERCASE, and must have a two-character keyword prefix in front of it
(which you set in the configuration file with the PREFIX: parameter, if you
don't want to use the default of "*:"). This keyword prefix is provided so
your keyword won't get mixed up with other text in the file, and SuperMenu
will know it's a keyword ("*:" was chosen because it is unlikely it would
occur randomly at the beginning of a line - use your own 2-character prefix
if you prefer).
   When you click on a gadget that uses a keyword, SuperMenu will search
through the file for that prefix code and keyword, and will display the text
until it encounters THE NEXT keyword or the end of the file.


CONFIGURATION FILE

   SuperMenu requires this configuration file to run. Even if you want all
of the default parameters and don't require a resident file or optional
window title, you've still got to define your menu options, and this is
where that is done too!
   The format of the SuperMenu conguration file is somewhat strict, and is
defined below:

   If SuperMenu is run from the CLI, and no command-line parameters are used,
it will look for a configuration file named "sm.config" which resides in the
"s:" device (usually the "s" directory on the disk where your startup-
sequence is). If you have a configuration file named something else, you can
direct SuperMenu to load it instead of the default one by specifying your
config file name after the name of the program (ie. "SuperMenu config.file").
   If you're running SuperMenu from the Workbench, you may set an alternate
configuration file by setting one of the ToolTypes with the Workbench Info
option. Use the ADD command and type "CONFIG=filename" into the tooltype bar,
where "filename" is the name of your configuration file. Don't forget to SAVE
the modified Info file.
   The file must be standard ASCII format, and the FIRST LINE of the file
MUST BE the string "SMCF1", which stands for "SuperMenu Configuration File
version 1". This is provided for upward compatibility, and SuperMenu WILL NOT
RUN if this header string is missing.
   Next come your parameter definitions, in any order you choose, with the
parameter command first (in upper or lower case) followed by a colon
(ie. "Screen:" or "SCREEN:" or "screen:"), and a space. Then comes the
actual parameter value, be it a string (see the above NOTE:) or number (some
commands may require more than one parameter, such as the font name and
size - ie. "Font: Topaz 8"). After that, you can place a semi-colon (";")
followed by a comment of your choice (no longer than 40 characters).

   NOTE: There must be a space between the Parameter Command and each of the
         successive parameter values. There should be no quotes surrounding
         any text strings (and no spaces in them either, see above NOTE).
         Everything is ignored after the correct number of parameter values,
         so you may place a short comment if you wish (place it after a
         semi-colon, so you'll know it's a comment). See the sample config
         file to examine a typical configuration file structure.

   After all of your parameter options, place the word "DATA" in upper-case
on a line of its own. This tells SuperMenu that the menu definitions will
follow. Don't forget this! SuperMenu won't work properly without it.

   Next come your menu definitions, each of which follow a strict line format
of their own. Each successive line may begin with one of the following:

TITLE       (a non-selectable choice used for delimiting sections of
             choices - ie. "User Functions" or "Adventure Games")

MENU        (an actual choice definition)

BLANK       (a blank line in the menu between two choices)


The format of a "TITLE" option would be the following:

"TITLE  title_name  color  rendering_flags"

   "title_name" is the text to place in the title
   "color" is the rendering color of the text (0-3 on Workbench Screen)
   "rendering_flags" are the rendering style of the text (see below)

   Example: "TITLE User_Functions: 3 BU"

      This title ("User Functions:") will be drawn in color 3 and will be
         BOLDFACE and UNDERLINED.


The format of a "MENU" option would be the following:

"MENU  menu_name  color  rendering_flags  file_name  keyword"

   "menu_name" is the text to place in the menu
   "color" is the rendering color of the text (0-3 on Workbench Screen)
   "rendering_flags" are the rendering style of the text (see below)
   "file_name" is the name of the text file to access for this option
   "keyword" is the UPPERCASE word used to search for the specific section

   Example: "MENU Load 1 N DOC:program.HELP LOAD"

      This menu ("Load") will be drawn in color 3 and will be a normal style.
         When it is selected, the text file "DOC:program.HELP" will be loaded
         and the section under the keyword "LOAD" will be displayed.

   NOTE: If the file this option is supposed to load is the resident file,
         use an asterisk ("*") in place of the filename. Also, do not place
         the keyword prefix code in front of the keyword. If this option has
         no keyword, and you just want the whole file displayed (or to start
         at the beginning) specify a keyword of "*".

The "BLANK" option has no parameters. Just place it on a line by itself.


RENDERING FLAGS

   You may select specific rendering styles for your title or menu text
within the menu window by using one-character codes in the "rendering style"
field of the option. You may use any of the following:
   N  - normal text (no special rendering style)
   B  - BOLDFACE
   I  - ITALICS
   U  - UNDERLINED
   L  - LEFT-justify text within gadget field
   R  - RIGHT-justify text within gadget field
   C  - CENTER text within gadget field

   (Boldface, Italics, and Underlined may all be combined in any way you
   like, ie. BIU or BI or UB, etc. The last justification flag encountered
   will be the one used. If no justification flag is supplied, the default
   one will be used, as set in the configuration file.)

NOTE: If any of your option text or filenames have spaces in them, replace
the spaces with underscores ("_"). Do NOT forget this, or SuperMenu is
likely to run unpredictably. For example, a title of "User Functions:" should
really be defined as "User_Functions:".

TITLE, MENU, or BLANK options may have comments after the last parameter,
just like the configuration parameters.

   The last line in the configuration file must be the string "ENDDATA" in
all UPPERCASE and on a line of its own. SuperMenu will display the titles,
menus, and blank lines in the menu window in the same order you placed them
into the configuration file, so make sure they are layed out the way you
want them first. Also, when SuperMenu draws a title, menu, or blank on the
last line of the menu window (as set by the ROWS: configuration parameter),
the next one will be drawn at the top of the window in the next column over.
Keep in mind that your menu window will reflect the way you set up your
maximum sizes and choices in the config file. If you have fewer options
than the maximum sizes allow, SuperMenu will display a menu window just
large enough for your options, automatically.

NOTE: You can use a different configuration file when SuperMenu is run from
   the CLI by typing the path name of the config file you want to use after
   the program's name (ie. "Run SuperMenu t:my_config").
   You may include the QUIET option after the program name and config file
   name to turn off program messages (ie. "Run SuperMenu t:my_config QUIET"),
   or you may include this in the configuration file parameter list instead.

NOTE: You can close open text windows with the window's CLOSEGADGET, or by
   pressing ESC or RETURN while the window is active.


Hints for using SuperMenu effectively:

1) If you've developed a config file and some text to be used in a LORES
   display, you will have to set the margins in your text processor so that
   the text lines are under 40 characters in length (make sure the edited
   file is saved in a Text or ASCII format). Now you will have to inform
   SuperMenu that its output should be constrained to a width of 320 (it will
   automatically be set to the width of the Workbench Screen, 640, when it's
   run) by using the SCRSIZE: option in the configuration file with a width
   set to 320 (the height can stay at -1, the default height, but still must
   be set: "SCRSIZE: 320 -1").

2) Whenever you need to add something new to the menu and your text files,
   you can easily accomplish this by typing in the new text where it needs to
   go (and giving it a keyword) and inserting a new MENU item for it in the
   configuration file. SuperMenu was designed to be easy to expand and simple
   to customize.

3) If you're running SuperMenu from the Workbench, all you need is to copy
   the default icon to the name you want, and fill in the path name of the
   SuperMenu program into the Default Tool section in the Info file, and the
   configuration file to use in the ToolTypes section with "CONFIG=filename"
   (this allows several icons to access the same program, each using
   different configuration files).

4) To quit SuperMenu (and remove it from memory), type a CONTROL-C while the
   menu window is active, or run the program again.


** MODIFICATION HISTORY **

V1.62 RELEASE NOTES  12/14/89
      - Remove SCREEN: config option. SuperMenu's windows now open on the
        currently-active (front-most) screen.
      - Add SCRSIZE: config option to force SuperMenu to constrain all of its
        output (menu and text windows) to a certain size.
      - Sorry. Still no ANSI...

V1.61 RELEASE NOTES  12/03/89
      - Moved some pointers around having to do with the textwindow titlebar
        Now keeps track of title and percentage in window info section so we
        don't go around hacking up memory blocks when we make un/resident
        (also brings code size down about 1K - neato)

V1.60 RELEASE NOTES  11/28/89
      - Yeah!! Workbench bug was NOT a bug - this thing wouldn't work at ALL
        except under my development environment (don't know why) - I changed
        the handler code to an older format (with an assembler stub) and it
        now works FINE! Hurrah! (I though Lattice 5.02 worked OK with reg.
        parameters - guess not...)
      - Text windows now display choice name in title bar with status info

V1.51 PRERELEASE NOTES  11/28/89
      - Program now sets up its own port (for future AREXX compatibility)
        so it knows where it is. If you run it twice, it will remove itself
        (as if you did it manually with CTRL-C)
      - Multiply-opened windows now open just below (if possible) the bottom-
        most window on the screen (open one, move it to the top, and then
        open some more for a screen full of little windows)
      - Workbench bug still there (crashes horribly when run from WB, I don't
        know why!! <sob> - works great from CLI, though, so put it in your
        startup-sequence (later found to be WRONG - see v1.60 notes)
      - Boxes bug still there, but it's no big deal anyway - don't use them

V1.50 PRERELEASE NOTES  11/26/89
      - User-defined command and qualifier keys for invoking program

V1.40 PRERELEASE NOTES  11/25/89
      - Size of the text window may be set with WINSIZE option
      - Windows left open when made resident will re-open automatically
        next time program is invoked (only in Resident mode)

V1.30 PRERELEASE NOTES  11/23/89
      - Multiple or sections of the same text files may be open at once
      - Multiple open text files may be manipulated independently
      - QUIET config/command-line option for no messages printed
      - Bug in BOXES mode makes strange lines all over (hmmmm...)
      - Crazy bug in Workbench implementation, freezes for no apparent reason
        after installing

V1.20 PRERELEASE NOTES  11/20/89
      - Workbench support added: CONFIG ToolType sets config file
      - MenuPos parameter added in config file to set menu window position
      - If menu window is moved and closed, it opens in place it was closed

V1.10 PRERELEASE NOTES  11/16/89
      - Resident option, can be called up at any time with HELP key
      - CONTROL-C on menu window removes SuperMenu from memory
      - Minor menu window heuristics bugs fixed
      - Still need workbench icon selecting config file

V1.01 BETA NOTES        11/15/89
      - User-supplied config filename from command-line
      - Justification parameters for menu text
      - Resident parameter for upward compatibility to next revision

V1.00 BETA NOTES        11/14/89
      - Doesn't support ANSI control codes in text files
      - No command-line options
      - No workbench icon support


AUTHOR NOTE

   SuperMenu is SHAREWARE. You may use and/or redistribute this program
as you like, but if you find it exceptionally useful (or are just feeling
generous, or you like my work, or my writing style, or anything else possibly
worthwhile), please feel free to send me a small donation of $10 or so. This
could make a struggling college student's day (and believe me, IT DOES!), and
may go into helping me write more interesting and helpful programs (as well
as some possible enhancements to SuperMenu - which I may already be planning!
How about picture support? Hmmmm.... At the rate I'm adding stuff to this
program it should be able to scramble eggs within six months!)
   Here's a deal for you! Send me $20.00 and I'll send you the latest and
greatest, new and improved, debugged and enhanced (smells nice too), version
of SuperMenu on disk and register you for notification of future updates and
other cool stuff (I'll also throw in some of my other ShareWare and PD stuff
too). This includes the lastest manual revision and any SuperMenu scripts I
happen to create or come across (also the upcoming blender attachment and
turnip twaddler, absolutely FREE). What a baagin!


Send any comments, criticisms, suggestions, donations, etc. to:

   Paul T. Miller
   129 Orchard Avenue
   Rocky Mount, VA 24151

or call me at [phone] for a chat or something.

------------ What are these "CUT HERE" lines REALLY for, anyway? -----------
    _________
   | _______ |
   ||       ||              AMIGA HAS THE "ELEMENTS" OF CREATIVITY
   ||     //||
   ||    // ||
   ||\\ //  ||                "What could be better than my Lattice `C'
   || \\/   ||                  and some Dr. Pepper?"
   ||_______||  "I love my Amiga 1000!"
   |_________|           ___
  ______________        |---|
 |              |       |. '|
 |          --- | ____   \./   <- supposed to be a brandy snifter
 |______________|| __ |   |
  |============| |____|  _|_  (This probably looks weird in non-interlace..)
----------------------------------------------------------------------------