home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format 66 / af066sub.adf / ButMenu / ButMenu.DOC < prev    next >
Text File  |  1994-09-21  |  10KB  |  285 lines
  1.  
  2.  *****           **     **                *    *
  3.  **  **          **     **                **  **
  4.  **  **        ****** ******              ******
  5.  *****  **  **   **     **   ****  *****  ******  ****  *****  **  **
  6.  **  ** **  **   **     **  **  ** **  ** **  ** ****** **  ** **  **
  7.  **  ** **  **   **     **  **  ** **  ** **  ** **     **  ** **  ** V1.00
  8.  *****   *****    **     **  ****  **  ** **  **  ****  **  **  *****
  9.  
  10.  
  11.  
  12. CONTENTS
  13. ========
  14.    = Introduction
  15.    = Disclaimer
  16.    = Copyright
  17.    = Distribution
  18.    = Acknowledgements
  19.    = Compatibility
  20.    = Requirements
  21.    = Getting Started
  22.      - From Workbench
  23.      - From Shell
  24.    = Reference
  25.      - How To Create a Button Menu
  26.      - How To Use a Button Menu
  27.      - Height Confusion
  28.      - What to do if the items won't fit
  29.      - Limitations
  30.      - Descriptions of each Gadget
  31.    = Contacting the author
  32.    = History
  33.  
  34.  
  35. INTRODUCTION
  36. ============
  37.    ButtonMenu allows Kickstart 2.0 (and above) owners to create menus in
  38.    the form of a window full of GadTools buttons.  Two programs are
  39.    provided: one to allow you to create the menu and one which runs the
  40.    menu.  It is then possible to run your menu from a startup-sequence,
  41.    for example.  The GUI for the creator was designed to use Topaz 8,
  42.    but it will adapt to the current screen font if it is not too big.
  43.  
  44.  
  45. DISCLAIMER
  46. ==========
  47.    I cannot be held liable if this program causes you to lose valuable
  48.    data, nor can I be blamed if this program causes any other problems
  49.    with your system.  Any problems are entirely the user's responsibility.
  50.  
  51.  
  52. COPYRIGHT
  53. =========
  54.    ButtonMenu V1.00 - written with DICE C (2.07.56R) on an A600 with no HD
  55.    (c) Oliver Roberts, 1994
  56.  
  57.    ButtonMenu is public domain and the copyright remains with the author.
  58.  
  59.  
  60. DISTRIBUTION
  61. ============
  62.    ButtonMenu is freely distributable providing none of the distributed
  63.    files are changed in any way,  ButtonMenu is not sold for profit and
  64.    it is not included on any disks that are sold solely for profit.  If
  65.    ButtonMenu is to be sold for profit, permission must be obtained from
  66.    me, the author (Oliver Roberts).  Included in the above are magazine
  67.    coverdisks - let me know if you wish to use ButtonMenu menus on the
  68.    disk(s).
  69.  
  70.    For following files MUST be distributed together if the Creator is to
  71.    be included:
  72.  
  73.    ButtonMenu          (ButtonMenu Creator)
  74.    ButtonMenu.info
  75.    ButtonMenu.doc      (Document)
  76.    ButtonMenu.doc.info
  77.    BMX                 (ButtonMenu Executor)
  78.    reqtools.library    (KS2.0 V38 - Needed for Creator only)
  79.  
  80.    If you just want to distribute your created menu then you can
  81.    distribute this file without the files above:
  82.  
  83.    BMX                 (ButtonMenu Executor)
  84.  
  85.  
  86. ACKNOWLEDGEMENTS
  87. ================
  88.    Reqtools.library      (c) 1991-1994 Nico Francois
  89.  
  90.    The GUI for the Creator was created with:
  91.    GadToolsBox V2.0b     (c) 1991-1993 Jaba Development
  92.  
  93.  
  94. COMPATIBILITY
  95. =============
  96.    ButtonMenu has been tested on an A600 with KS2.05 and KS3.0 using
  97.    NTSC/PAL, chip/fake fast, chip configurations.
  98.  
  99.    ButtonMenu is fully OS-Legal, it should work on ANY Amiga with
  100.    Kickstart 2.0 or higher!
  101.    (if not - contact me!)
  102.  
  103.  
  104. REQUIREMENTS
  105. ============
  106.    Any Amiga with Kickstart 2.0 (V36) or higher.  NTSC / PAL
  107.  
  108.    To run the Creator you will need these disk based libraries in the
  109.    LIBS: drawer on you boot disk or HD.
  110.  
  111.       diskfont.library (V36 or higher)
  112.       reqtools.library (V38 or higher)
  113.  
  114.    To run the Executor you do NOT need "reqtools.library" in the LIBS:
  115.    drawer, but if you are not using a ROM font (ie Topaz 8 or Topaz 9)
  116.    for the menu you will need "diskfont.library" if the font has not
  117.    already been loaded into RAM by another program.
  118.  
  119.  
  120. GETTING STARTED
  121. ===============
  122.    First make sure you have the libraries mentioned in the REQUIREMENTS
  123.    section installed in your LIBS: drawer on you HD or boot disk.
  124.  
  125. From Workbench
  126. --------------
  127.    Double-click on the ButtonMenu icon.
  128.  
  129. From the Shell
  130. --------------
  131.    Type `ButtonMenu' at the prompt.  There are no command line options
  132.    at present.
  133.  
  134.  
  135. REFERENCE
  136. =========
  137. How to Create a Button Menu
  138. ---------------------------
  139.    Making a menu is simple with ButtonMenu.  Just enter the items you wish
  140.    to be displayed to the user and the AmigaDOS command lines.
  141.  
  142.    Entering the commands is made simplier by providing a file requester:
  143.    just click on the gadget next to the command text gadget and select the
  144.    file you want to be run when the user clicks on the button.
  145.  
  146.    You can also ask for the command to be run in the background (uses the
  147.    AmigaDOS `run' command).
  148.  
  149.    Then select the font you wish to use for the buttons, the size of the
  150.    window and the title for the window.  Then select 'Save' from the menu.
  151.  
  152. How to Use a Button Menu
  153. ------------------------
  154.    Type `BMX <filename>' at a DOS prompt and the menu will appear.  Where
  155.    <filename> is the name of a ButtonMenu datafile which you have
  156.    previously saved (defaults to `BM.dat').  The menu should now appear.
  157.  
  158.    Now just click on the button to run the corresponding commands, and
  159.    click the close gadget when you have finished.
  160.  
  161. Height Confusion
  162. ----------------
  163.    Some people may find the way the Height of the menu window is calculated
  164.    confusing - or uninteresting!  So for users who want to know why the
  165.    height is what it is, here is a little (well... long) explanation:
  166.  
  167.   "The Amiga OS will always use the screen's default font (set in Workbench
  168.    preferences) for the text in the title bars for each window opened.
  169.  
  170.    This means that the size of the title bar is variable when running the
  171.    menu with `BMX' and it is inconvenient to keep the height of the window
  172.    constant - the calculations in the ButtonMenu Creator would also have
  173.    to be used in the `BMX' program which would make the program nearly as
  174.    large as the creator, and would create incompatibilities with different
  175.    systems. I wanted the menu to be displayed as quickly as possible with
  176.    the smallest possible program.
  177.  
  178.    So, you are asked to enter the maximum inner height for the window,
  179.    which is the height of window excluding the title bar and bottom border.
  180.    The `Calculated Total Height' gadget will display an estimate for the
  181.    total height of the window, using the current screen font.
  182.  
  183.    Included is a `Height Adjust' feature.  This will alter the height
  184.    further, by removing any blank lines that will not be used giving a
  185.    slightly tidier menu.  To do this though, the `Calculated Total Height'
  186.    is calculated as before, but with the smallest possible height.     "
  187.  
  188. What to do if the items won't fit
  189. ---------------------------------
  190.    If you have the Adjust Height feature enabled, or are trying to save
  191.    your menu, and get any error message saying that the item(s) won't
  192.    fit in the window, then here are the possible causes/solutions:
  193.  
  194.    Causes
  195.    ------
  196.       * The text length of one of the items is too long
  197.         (and/or longer than the width of the window)
  198.       * The font is too large
  199.       * The window is too small
  200.       * Too many items
  201.  
  202.    Solutions (a bit obvious!)
  203.    ---------
  204.       * Shorten the length of the item texts
  205.       * Select a smaller font
  206.       * Enlarge the window
  207.       * Delete some of the longer items
  208.  
  209. Limitations
  210. -----------
  211.    The only limitation to the menus you create is that there must be at
  212.    least 1 item and no more than 100 items.  If you need more items -
  213.    let me know.
  214.  
  215. Descriptions of each Gadget
  216. ---------------------------
  217.    New Item   : Add a new item to the menu, after the currently selected
  218.                 one (or the start if there are no items).
  219.  
  220.    Delete Item: Erase the currently selected menu item.
  221.  
  222.    Up         : Move the currently selected item up the list.
  223.  
  224.    Down       : Move the currently selected item down the list.
  225.  
  226.    Item Text  : The text to be displayed on one of the menu buttons.
  227.  
  228.    DOS        : The command to be executed when the corresponding menu
  229.     Command     button is clicked.  This is to be in the same format as
  230.                 you would run it from the CLI manually.  You can also
  231.                 select commands via a file requester, so you don't need
  232.                 to remember the exact filenames.
  233.  
  234.    Run command: Tells the Amiga to run that command as a background task.
  235.     in          This does the same thing as `run >NIL: <command>' would
  236.     background  do, where <command> is the contents of the DOS Command
  237.                 gadget.
  238.  
  239.     Font Used : The font to be used for the item text on the menu buttons.
  240.     For Items   Click the Choose Font button to change the font.
  241.  
  242.     Title     : Text to be displayed in the title bar of your menu - uses
  243.                 a separate font.
  244.  
  245.     Width     : Width of the menu window (in pixels).
  246.  
  247.     Inner     : The height of your window excluding the title bar and
  248.     Height      bottom border.
  249.  
  250.     Adjust    : With this feature turned on, any blank lines at the bottom
  251.     Height      of your menu window will be removed by decreasing the
  252.                 height.  Checks will also be made to see if your items
  253.                 will actually fit in the menu window with the dimension
  254.                 you have specified whenever you alter these, the font or
  255.                 the Item Text.  With the feature off, these checks are
  256.                 only made when saving.
  257.  
  258.     Calculated: This is the estimated total height of your window including
  259.     Total       the borders.  Assumes the screen font you will use for the
  260.     Height      menu will be the same as the current one - that is why it
  261.                 is an estimate.
  262.  
  263.  
  264. CONTACTING THE AUTHOR
  265. =====================
  266.    You can contact me via e-mail at this address:
  267.  
  268.       robeoy@essex.ac.uk
  269.  
  270.    Or via snail-mail, my permanent home address is:
  271.  
  272.       30 Tillett Road
  273.       Norwich
  274.       Norfolk
  275.       NR3 4BJ
  276.       ENGLAND
  277.  
  278.  
  279. HISTORY
  280. =======
  281.  
  282. V1.00 - July 28 1994
  283.  
  284. First release.
  285.