GUI Menus
----------------

In this section we describe another use for template files, which is 
to create Vx menus.  You may think of this as a special type of GUI 
form.  All the sidebars, topbars, pull-down, and pop-up menus in ZW3D 
are created with menu forms.


Menus in ZW3D
---------------------

Menu templates are similar to our other templates in overall format.
They contain a short header section which begins with the keyword
MENU and then is followed by a list ITEM sections.  Each Item section
corresponds to a button on the menu.  Buttons appear in the order
specified in the template (you do not need to specify their location
like you do with general GUI widgets).  Menu templates must be
compiled and loaded into Forms.Z3 (preferably a local copy).

To compile a single template file, type the following statement from
the command line of a Windows console (without the quotemarks):

      "zw3d -t template_file.t Forms.Z3".

If you have a folder which contains multiple templates then you
may compile all of them with the following command:

      "zw3d -d folder_name Forms.Z3".

The above commands must be executed from within your ZW3D user folder.
The "About..." option on the ZW3D Help pulldown menu shows the path to 
your ZW3D user folder.

----------------------------
Example Menu template

MENU=ToolBarPart
title=Tool Bar
class=tool_bar
persist
icon

# button 0
ITEM=button
accel=E
icon=ICON661.xpm
command=|FormEscape
hint=Escape from current command

# button 1
ITEM=separator

# button 2
ITEM=button
icon=ICON612.xpm
command=$CdUndo
hint=Undo last command "Ctrl+U"

# button 3
ITEM=button
icon=ICON611.xpm
command=$CdRedo
hint=Redo previous command "Ctrl+R"
-----------------------------


Format of Menu Templates
------------------------------

Basic menu format:
-------------------
   MENU = {menu name}
   title = {OPTIONAL menu title}
   class = {menu class}
   function = {menu function} used with popup menus. It is called when
      the popup menu is unmapped with the item number of the selected
      push button or toggle button.  An item number of "0" means nothing
      was selected.
   persist (OPTIONAL keyword to indicate if menu should be held in memory)
   lock (OPTIONAL keyword to bypass custom user toolbar operations)
      Only valid for user menu class.


   ITEM  = {item class}
   icon  = {icon name} or...  label = {text string}
   menu  = {menu name}, command = {command string}, form={gui form name}
   hint  = {OPTION text hint}
   group = {OPTIONAL integer group id (0 if undefined)}
   accel = {OPTIONAL accelerator key(s) string}

   on (OPTIONAL keyword to indicate that item is active)
   dynamic (OPTIONAL dynamic item indicator)
      - Only item of types "button", "toggle", and "separator" within
        a "pull_down" menu class are checked for this keyword.
      - All dynamic items need to be blocked together.
      - Only the first block of dynamic items within the pulldown menu
        is processed. The dynamic option for all other consecutive blocks
        is ignored.
   hide (OPTIONAL keyword to hide an item)
      - Only item of type "button" within a "pop_up" menu class are checked
        for this keyword.

Menu classes:
-------------
   top_bar   - defines the top menu bar
   tool_bar  - defines the tool bar menu
   side_bar  - defines the side bar menu
   pop_up    - pop up menu defintion
   pull_down - used for side pulls also
   options   - options menu on the top bar, side bar, or tooltab
   user      - defines the user bar menu
   tooltab   - defines the tool tab menu
               (ITEM=tab is the only valid item for this menu class)

Item types:
-----------
   button
   separator
   radio_box (exclusive)
   check_box (non-exclusive)
   toggle
   opt_btn - left mouse =} command, right mouse =} menu
   opt_std - standard options menu widget
   pull_down (used for side pulls also)
   help (only valid for top bar)
   switch - like a button, but stays in or out and appends On/Off to command
      label
   toggle|button - converts to a toggle on Windows or a button on UNIX
   tab - tooltab tab page (only valid with class=tooltab menu)

Command string formats:
-----------------------
   ! If a command is preceded by an exclamation point (!), it is assumed
     to be the name of a command template.  The template is retrieved
     from "Forms.Z3" and executed.

   ~ If a command is preceded by a tilda (~), it is assumed to be the
     name of a void function with void arguments (void function(void)).
     The specified function is called.

   | If a command is preceded by a pipe (|), it is assumed to be one
     of the hard-coded commands used to control the operation of the
     Input Manager (example: |FormEscape).

Icons:
-------

To have your own icons used on a menu button, use any 2D art 
package which creates "*.xpm" files on unix or "*.bmp" files
on NT.  These should be moved to the driver directory where
they will be loaded at each runtime.