+---------------------------------+
|           DEFINE MENU           |
+---------------------------------+
DEFINE MENU <menu name>
        [BAR [AT LINE <expN1>]]
        [IN [WINDOW] <window name>
        | IN SCREEN]
        [KEY <key label>]
        [MARK <expC1>]
        [MESSAGE <expC2>]
        [NOMARGIN]
        [COLOR <color pair list>
        | COLOR SCHEME <expN2>]

-----------------------------------
Creates menu bar.
-----------------------------------

The DEFINE MENU command is used to create a menu system.  A menu system
usually contains a horizontal menu bar with menu popups under each of
the menu bar pads.  As you move from pad to pad on the menu bar a menu
popup appears under each pad.  You can then choose an option from the
menu popup.

To create a menu system, first create the menu bar using the DEFINE MENU
command.  Provide a <menu name> for the menu bar you create.  Next,
define each of the pads on the menu bar using a series of DEFINE PAD
commands.  Specify which menu popup will be displayed under each menu
pad with ON PAD ... ACTIVATE POPUP commands.  Finally, create the menu
popup for each of the menu pads using DEFINE POPUP commands, and display
the entire menu system with the ACTIVATE MENU command.

Choosing a menu bar pad does not have to ACTIVATE a POPUP.  When a pad
is chosen, another menu bar can be activated with an ON PAD ... ACTIVATE
MENU command, or a routine can be executed with an ON SELECTION PAD ...
DO command.

Clauses
-------

<menu name>
        Name of menu bar to be created.

BAR [AT LINE <expN1>]
        Creates bar menu that behaves like FoxPro System menu bar.  If the size
or number of pads you define exceeds the size of the screen or a window
where the menu bar is placed, the menu bar will scroll.  You may specify
the screen or window row that a menu bar is placed on with the AT LINE
option of the BAR clause.  Include in <expN1> the screen or window row
number where the menu bar will appear.

IN [WINDOW] <window name> | IN SCREEN
        Places menu bar in specific window or screen.  By default, menu bars
are placed on the screen unless there is an active output window.  If
there is an active output window, the menu bar is placed in the output
window.

KEY <key label>
        Activates menu bar by pressing key or combination of keys.  The KEY
option accepts a <key label> to specify the key or key combination used
to activate the menu bar.  See the ON KEY LABEL command in this help
facility for a listing of available keys and key combinations and their
<key label> names.  Including the KEY clause is equivalent to issuing an
ON KEY LABEL <key label> ACTIVATE MENU <menu name> command.  If a
keyboard macro is already defined with the same <key label>, the
keyboard macro takes precedence and the menu bar cannot be activated
with the specified key or key combination.

MARK <expC1>
        Places character mark before each pad in menu bar.  A check mark may be
used to indicate that a certain condition exists - a menu popup is
available for the pad, an option controlled by the pad is on or off and
so forth.

        A small diamond (.) is the default check mark for menu bar pads.  You
may specify your own check mark for all menu bar pads by including the
MARK option and a mark character in <expC1>.  The mark character <expC1>
must be enclosed in single or double quotation marks.  Do not include
the quotation marks if <expC1> is a memory variable or array element
containing a character string.  If more than one character is included
in <expC1>, only the first character is used as the check mark.  You may
also specify a check mark with the CHR() function.

        The MARK option sets the check mark for all pads in a menu bar.  Check
marks specified in DEFINE PAD commands take precedence over check marks
specified by the MARK option in DEFINE MENU.  The SET MARK command is
used to toggle check marks on or off, and may also be used to specify a
check mark for an individual menu bar pad or for all menu bar pads.

MESSAGE <expC2>
        Displays <expC2> when pad is selected.  The message will appear
centered on the screen row specified by the SET MESSAGE command.  The
DEFINE MENU message will be overwritten by a message created in a DEFINE
PAD command.

NOMARGIN
        Removes left and right spaces from menu pad.

COLOR SCHEME <expN2> |
COLOR <color pair list>
        Overrides default color settings.  By default the colors of menu bars
created with DEFINE MENU are controlled by color scheme 2, Usr Menus.
You can specify the color of all elements of the menu bar directly, or a
menu bar can draw its colors from another specified color scheme.

+---------------------------------+
|         Program Example         |
+---------------------------------+
In example below, menu bar named MAINMENU is created.  BAR is included
to emulate behavior of FoxPro system menu bar. Menu bar is placed on
line one of screen.

KEY is included to activate menu when Alt+Z key combination is pressed.
Mark character (square block) is specified for menu pads with MARK
CHR(254).

When pad is chosen from menu bar, TMENU procedure is executed. DO TMENU
IN MENUEXAM specifies that routine is in MENUEXAM.PRG program, so be
sure to give this program that name.  TMENU procedure uses two
parameters, MMENU and MPAD which receive their values from MENU() and
PAD().  MMENU contains menu name, and MPAD contains name of pad chosen
from menu bar.

TMENU procedure then displays menu name and your menu pad choice in
window.  If you choose Quit, message is displayed and menu bar is
removed from screen and memory.

*** This program must be named MENUEXAM.PRG ***
CLEAR
DEACTIVATE MENU mainmenu
DEFINE MENU mainmenu BAR AT LINE 1 KEY ALT+Z MARK CHR(254)
DEFINE PAD invoices  OF mainmenu PROMPT '\<Invoice'
DEFINE PAD customers OF mainmenu PROMPT '\<Customers'
DEFINE PAD inventory OF mainmenu PROMPT 'I\<nventory'
DEFINE PAD quit      OF mainmenu PROMPT '\<Quit'
ON SELECTION MENU mainmenu ;
DO tmenu IN menuexam WITH MENU(), PAD()
ACTIVATE MENU mainmenu NOWAIT

PROCEDURE tmenu
PARAMETER mmenu, mpad
WAIT WINDOW 'Selected menu pad of ' + mmenu + ' is ' + mpad NOWAIT
SET MARK OF PAD(PAD()) OF mainmenu TO ;
        ! MRKPAD('mainmenu', PAD()) && Toggle mark character
IF mpad = 'QUIT'
        DEACTIVATE MENU mainmenu
        RELEASE MENU mainmenu
ENDIF
RETURN

-----------------------------------

See Also:  ACTIVATE MENU, CNTPAD(), DEACTIVATE MENU, DEFINE PAD,
GETPAD(), HIDE MENU, MRKPAD(), ON PAD, ON SELECTION PAD, PRMPAD(),
RELEASE, SET MARK OF, SHOW MENU

-----------------------------------