                                MenuBuilder
                                Version 1.0

                   Copyright  Adam Dawes, January 1996.



Introduction to MenuBuilder
===========================

MenuBuilder is a tool designed for programmers who work with an Intuition
environment. It allows you to very easily create menu bars for use in your
programs.

Your menus are designed using a graphical interface, which makes menu
design much simpler to do than by entering menu data directly as
sourcecode. MenuBuilder offers a variety of other advantages too, such as
being able to test your menus in realtime. As you change the menu
definitions, so the test menu changes to reflect this.

When you have designed your menus completely, MenuBuilder will generate all
the sourcecode required to easily integrate them to your programs, and to
interact with them without any code modification at all.

Currently the only menus supported are Gadtools menus, and the only
language supported is C. I *do*, however, fully intend to include support
for as many GUI development systems as possible (eg, MUI, Triton, etc.) and
for as many languages as possible (AmigaE, BlitzBasic, Pascal, whatever you
like!).

If you want support for a language/environment then please contact me and
let me know.



Using MenuBuilder: Designing and editing menus
==============================================


Menu Item Types
~~~~~~~~~~~~~~~

MenuBuilder gives you full control over all the features of Amiga menus.
First of all, there are 3 types of possible menu item. These types are as
follows:


   Menu Title           One of the headings that appears at the top of the
                        screen when you press the right mouse button

   Menu Item            One of the list of items that appears under each
                        menu title

   Sub Item             One of a list of items which may appear in a sub
                        menu of one of the menu items.


MenuBuilder refers to all of these item types simply as a 'Menu Item'. You
define the type by moving the item left and right within the menu list
window using the '<' and '>' buttons. If a menu item is fully to the left,
it is considered to be a Menu Title. If it is shifted one step to the
right, it is a Menu Item. When moved fully to the right, it is a Sub Item.

Further to these item types, you may also add Seperator Bars to the menu
definitions, using the 'Add Bar' button. A Seperator Bar may not be shifted
to the Menu Title position, but you may use Seperators with both Menu
Items, and Sub Items.

There are various rules that govern where each of these menu types may be
used, all of which are fairly self explanatory. Basically:


   The first item of the menu definitions must be a Menu Title

   A Sub Item cannot follow a Menu Title, only a Menu Item

   A Sub Item cannot follow a Seperator Bar (unless the Seperator Bar
    is part of the Sub Item menu)


MenuBuilder will not immediately stop you from breaking any of these rules,
but it will not allow you to test your menus or generate sourcecode until
they are all satisfied. If it detects that one of the rules has been
broken, it will tell you what the problem is, and move the selection bar to
the menu item that has broken the rule.


Editing Menu Items
~~~~~~~~~~~~~~~~~~

When you add a menu item, there are various pieces of information that
MenuBuilder requires about it. This data is as follows:


   Caption              The actual text that appears in the menu.

   Name                 The name by which you will refer to your menu items
                        in your program code. It is a good idea to prefix
                        all Menu Title items with "TITLE_", and all Menu
                        and Sub Items with "MENU_". See the section on
                        interacting with the generated menus for more
                        information.

   ShortCut             For a Menu Item or Sub Item, you may enter a single
                        character keyboard shortcut.

   Enabled              This checkbox allows you to set whether the Menu
                        Title, Menu Item or Sub Item is enabled. If a Menu
                        Title is disabled, all Items and Sub Items
                        contained within that menu will also be disabled.

   Checkable            If a Menu Item or Sub Item is checkable, set this
                        checkbox.

   Checked              If a Checkable Menu Item or Sub Item is also to be
                        in the Checked state, set this checkbox.


That is all there is to it! You can rearrange the items in your menu
definitions by using the 'Up' and 'Down' buttons to move the selected menu
item around.

Several menu definitions copied from other software are included with
MenuBuilder in the Examples/ directory. Try loading these in to MenuBuilder
to see how they fit together.


Testing Your Menus
~~~~~~~~~~~~~~~~~~

MenuBuilder will let you test how your menus look at any time whilst you
are designing them. If you select the 'Test' item from MenuBuilder's menus,
a small window will open up below the main editor window. Any time this
window is active, the menu bar will change to reflect the menu definitions
that you are editing. This makes it particularly easy to ensure that your
menus look how you want them.

If you want to change the menu definitions, simply make the modifications,
leaving the Menu Test window open. When you have made your changes, click
on the Menu Test window to activate it again, and then press the right
mouse button to see how the changed menus look.



Using MenuBuilder: Adding the menus to your own programs
========================================================

Once you have designed your menus, you will want to be able to use them in
your own programs. To do this, select "Generate Sourcecode..." from
MenuBuilder's menus.

Firstly, MenuBuilder will perform a full validation check on your menus.
This consists of all the rule-checking described in the Editing Menus
section, aswell as the following checks:


   No two menu items have the same ShortCut key

   No two menu items have the same Name (the same Caption is fine, though)


If any of the menu definition breaks any of the rules, MenuBuilder will
tell you what is wrong, and will move the selection bar to the menu item
that caused the problem.

Assuming the menu definitions pass the validation checks, a file requester
will appear asking you where to save your sourcecode. Save the code as a
header (.h) file, as you will be using the #include directive to integrate
the menu with your own program code.

The generated sourcecode file consists of two parts: constant definitions
(a lot of #define directives) and the menu definitions (an array of NewMenu
structures). The constants will be of use when you want to interact with
the menus, and allow you to find which menu item was picked using the names
you have defined.

To add the menus to your own windows, though, you need to use the menu
definition part of the file. The array looks something like this:

 static struct NewMenu mbld[] =
 {
        {NM_TITLE,"Project", 0 ,0,0,0},
        { NM_ITEM,"Open...","O",0,0,0},
        { NM_ITEM,NM_BARLABEL, 0 ,0,0,0},
        { NM_ITEM,"Save As...","A",NM_ITEMDISABLED,0,0},
        { NM_ITEM,NM_BARLABEL, 0 ,0,0,0},
        { NM_ITEM,"Print","P",0,0,0},
        { NM_ITEM,"About...","?",0,0,0},
        { NM_ITEM,NM_BARLABEL, 0 ,0,0,0},
        { NM_ITEM,"Quit","Q",0,0,0},
        {  NM_END,0,0,0,0,0}
 };

The structure will always be given the name 'mbld'. If you need to use
several MenuBuilder menu definitions in a single code section, you will
need to edit the generated source files and change the array name. I will
add an option to define the array name in a future version of MenuBuilder.

Use the #include directive to include the generated sourcecode at the start
of your program. Then you can use this array with the gadtools/CreateMenus()
function as follows:


        MenuStrip=CreateMenus(mbld,TAG_END);
        LayoutMenus(MenuStrip,VisInfo,TAG_END);
        SetMenuStrip(TestWindow,MenuStrip);


If you wish to modify your menu definitions, simply edit them in
MenuBuilder, and then regenerate the sourcecode. You will not need to
modify your program code at all, as all the menu data is contained within
the generated file.

Included within the MenuBuilder archive is a small piece of C sourcecode
called 'TestMenus.c'. This should fully demonstrate how to integrate
MenuBuilder's generated sourcecode with a C program. The program uses a
MenuBuilder sourcecode file called 'RAM:TestMenus.h' to define the menus
for a simple window. Generate some sourcecode to 'RAM:TestMenus.h' and then
try compiling the program.



Using MenuBuilder: Interacting with the generated menus
=======================================================

When you are designing your menus, you should give a name to each of the
items that you create. For menu items that are set as Menu Titles, prefix
the name with "TITLE_". For menu items that are Menu Items or Sub Items,
prefix the name with "MENU_". So you might want to set the following menu
data up with the following names:


        Menu Item                       Item Name
        ~~~~~~~~~                       ~~~~~~~~~
        Project                         TITLE_PROJECT
            Open...                     MENU_OPEN
            Save                        MENU_SAVE
            Save As...                  MENU_SAVEAS
            Quit                        MENU_QUIT


When you generate sourcecode, MenuBuilder will include a number of #define
directives at the start of the generated sourcecode, allocating a number to
each of these names. Because of these numbers, you can very easily find
which menu item has been selected by a user of your program by using the
names you have set.

When you receive an IDCMP_MENUPICK event from intuition, the Code field of
the Message structure will contain all the data required for you to find
the selected item. Included within the <Intuition/Intuition.h> file are 3
macros which make the task even easier. The macros are defined as follows:


  #define MENUNUM(n) (n & 0x1F)
  #define ITEMNUM(n) ((n >> 5) & 0x003F)
  #define SUBNUM(n) ((n >> 11) & 0x001F)


If you use the MENUNUM() macro on the Code data that you receive from
Intuition, you will be left with a number that matches one of the defined
Menu Title names. If you use the ITEMNUM() macro on the code, you will be
left with a number matching one of the Menu Item names. Using SUBNUM()
(where appropriate) will give you one of the Sub Item names. Using C's
"switch" statement, it is very easy to react to each of the possible menu
selections, as follows:


   /* 
   ** Code goes here to receive, interpret and reply to the intuition
   ** message. The 'Code' field of the message is assumed to have been
   ** stored in a variable called 'msgcode'.
   */

   if (class == IDCMP_MENUPICK)       // user picked something from a menu
   {
      switch(MENUNUM(msgcode))
      {
         case TITLE_PROJECT:
            switch(ITEMNUM(msgcode))
            {
               case MENU_OPEN:
                  // 'Project/Open' was picked
                  break;
               case MENU_SAVE:
                  // 'Project/Save' was picked
                  break;
               case MENU_SAVEAS:
                  // 'Project/SaveAs' was picked
                  break;
               case MENU_QUIT:
                  // 'Project/Quit' was picked
                  break;
            }
            break;

         case TITLE_NEXTMENU:
            // [etc.etc.etc.]

            break;
      }
   }


As you can see, you do not need to refer to any actual numbers at any stage
of the code. All the menu handling can be done simply using the names you
have defined. And what's more, if you need to edit the menu definition,
MenuBuilder will reset all the constant values when you re-generate the
sourcecode so that the values are still correct, and your program will not
need to be modified at all.



MenuBuilder history
===================

  Version 0.1 (27.12.95) (beta test, not released)

       Original test version.


  Version 1.0 (1.1.96) (first public release)

       Cleared up many bugs.

       Sourcecode generation fully working.

       ShurtCuts working.

       Example .mbld files included with distribution.

       Menu Builder is now font and resolution sensitive. MenuBuilder uses
        the 'Screen Text' font defined in the Font preferences. If the font
        is too large, MenuBuilder drops back to using Topaz/8.



The future of MenuBuilder
=========================

There are quite a few things I still want to do with MenuBuilder. Some of
these are:


       Add support for more programming languages. Please contact me if
        you have a suggestion for a language I should support.

       Add support for more development environments (eg, MUI, Triton,
        etc.). Please contact me if you have a suggestion for an
        environment I should support.

       Get the MutualExclusive elements of menus working (these are
        currently not implemented).


Please let me know if you have any other suggestions for MenuBuilder!



Known bugs
==========

As far as I know, MenuBuilder should be completely bug-free.

If you find any bugs, please let me know!



Acknowledgements
================

My sincere thanks to the following people who helped make MenuBuilder what
it is:


        Bret McGee
                (for his excellent ButtonClass code)

        Lars Janssen, Peter Hughes, Martin Meldrum and Graham Hoyle
                (for beta testing and ideas)



Legal stuff
===========

Ok, so my associates and I have tested this program as extensively as we
can, and haven't found any bugs (other than those documented) in it, but
sod's law clearly dictates that the experiences of the many are worse than
the experiences of the few.

I won't accept responsibility for any damage done to your system or data
lost, directly or indirectly, as a result from using this program or any of
its associated files. You use the program entirely at your own risk. Of
course if you *do* experience problems then I'll do what I can to sort them
out, and please let me know so that I can try to cure them in a future
release.

MenuBuilder and its associated files are not public domain. They may be
distributed freely as long as no unreasonable charge is imposed. They may
not be included within any commercial package without express written
permission from the author; the exceptions from this are the AmiNet CDs and
Fred Fish's collections. MenuBuilder may only be distributed if all files
contained within the original archive are present.



Contacting the author
=====================

If you like MenuBuilder, have found a bug, or have suggestions for its
future, please contact me! I can be contacted via electronic mail or snail
mail. I can't promise to reply quickly to snail mail, but I will always
reply to email messages. I won't complain if anyone decides to send money!
:)

  InterNet:
      ad32@brighton.ac.uk
      adam@beachyhd.demon.co.uk

  FidoNet:
      Adam Dawes@2:441/93.5

  Snail Mail:
      Adam Dawes
      47 Friar Road
      Brighton
      BN1 6NH
      England


If you are contacting me to request for MenuBuilder to support a new
programming language or development environment, please send me a small
sample of the code that MenuBuilder should generate!


                   MenuBuilder is a "BeachWare" product
              from the Beachy Head Amiga BBS, Eastbourne, UK
                   2:441/93@FidoNet  +44 (0)1323 520999
                7 days, 24 hours   300-28800 bps   2 lines
