+---------------------------------+
|           DEFINE BAR            |
+---------------------------------+
DEFINE BAR <expN1> |
        <System option name>
        OF <popup name> PROMPT <expC1>
        [BEFORE <expN2>
        | AFTER <expN2>]
        [KEY <key label> [, <expC2>]]
        [MARK <expC3>]
        [MESSAGE <expC4>]
        [SKIP [FOR <expL>]]
        [COLOR <color pair list>
        | COLOR SCHEME <expN2>]

-----------------------------------
Creates menu option in popup.
-----------------------------------

DEFINE BAR is used with DEFINE POPUP to create popups.  A popup is
created and assigned a name with DEFINE POPUP.  Menu options are then
placed in the popup with a series of DEFINE BAR commands.

When a menu option is chosen, another popup can be displayed or a
routine can be executed.  A popup that displays another popup or a menu
bar is called a hierarchical popup.  For more information on creating
hierarchical popups, see ON BAR.

You can fill a popup with options created with a series of DEFINE BAR
commands. DEFINE BAR is required for each option in a popup.  You must
include in DEFINE BAR the <popup name> where the option will be placed.

You can define more menu options than will fit in a popup.  Doing so
creates a scrollable popup.  You can scroll through the options by
pressing the Up or Down Arrow keys or by clicking the mouse on the top
or bottom border lines of the popup.

Utilizing the FoxPro system menu bar and its popups is the preferred
method of including popups in your applications.  If you utilize the
system menu bar popups, it is not necessary to first define the popups,
and in fact will generate an error if you do.  For more information on
utilizing the system menu bar and its popups, see SET SYSMENU.

A popup can also be created containing records or fields from a database
file or a list of files available on disk.  See the PROMPT FIELD, PROMPT
STRUCTURE and PROMPT FILES options of DEFINE POPUP for more information.

Clauses
-------

<expN1>
        Assigns bar number.

<System option name>
        Places option from System menu popup into popup.  A list of System
names is returned by SYS(2013). For example, to provide access to the
Calendar/Diary in a popup named "OTHER", you could create the option
with the command

        DEFINE BAR _MST_DIARY OF OTHER PROMPT 'Enter Appointments'

        Whenever this option is chosen from the popup, the FoxPro
Calendar/Diary is opened.

OF <popup name>
        Name of popup where options are to appear.

PROMPT <expC1>
        Defines text that appears in option.  A separating bar can be created
and placed between options by using a backslash and a dash (\-) in a
PROMPT expression <expC1>.  This allows you to group options together.
For example, including the command

        DEFINE BAR 4 PROMPT '\-'

        in a popup definition creates a separator between the third and fifth
options.

        You can create a hot key for a menu option by placing a backslash and a
less than sign (\<) before the character you would like to be the hot
key.  A hot key is a letter on the keyboard than can be pressed to
choose the corresponding option.  With a hot key it isn't necessary to
highlight your choice and then press the Spacebar or Enter.

BEFORE <expN2> | AFTER <expN2>
        Places option in popup relative to another option in popup.  Two
special names, _MFIRST and _MLAST, let you reference the first and last
items in a popup.

KEY <key label> [, <expC2>]
        In addition to pressing a hot key, an option can be chosen by pressing
another key or key combination.  The KEY option accepts a <key label> to
designate the key or key combination used to choose the option.  See ON
KEY LABEL in this help facility for a listing of available keys and key
combinations and their <key label> names.

        . If a keyboard macro is already defined with the same <key label>, the
keyboard macro takes precedence and the option cannot be chosen with the
specified key or key combination.

        The <key label> is placed to the right of an option.  Including the
optional character expression <expC2> lets you replace the <key label>
with your own text.  For example, including KEY Ctrl+B places Ctrl+B as
text after the option - instead you could use KEY Ctrl+B, "".   is
then used as a reminder of the key combination that chooses the option.
The <key label> can be suppressed by including the null string in
<expC2>.

MARK <expC3>
        Places mark before option in popup.  The default mark character is a
small diamond (.).  MARK <expC1> can be included to change the default
mark character.  Specifying a mark character does not mark an option --
use SET MARK OF to mark an option.

        If more than one character is included in <expC1>, only the first
character is used as the mark character.

        Marks specified in a DEFINE BAR take precedence over marks specified by
MARK in a DEFINE POPUP.  SET MARK OF is used to toggle marks on or off,
and can also be used to specify a mark for an individual popup option or
for all popup options.

SKIP [FOR <expL>]
        Enables or disables option based upon logical condition <expL>.  If you
include the SKIP FOR <expL> option, the logical condition <expL> is
evaluated, and based on the result (true or false), the option is
disabled or enabled.  If <expL> evaluates to true (.T.) the option is
disabled and cannot be selected or chosen.  If <expL> evaluates to false
(.F.) the option is enabled.

        Another method for disabling a popup option is placing a backslash (\)
before the text of the prompt.

MESSAGE <expC4>
        Displays message when option is selected.  When the option is selected
the MESSAGE appears centered on the screen row specified by SET MESSAGE.

COLOR SCHEME <expN2> | COLOR <color pair list>
        Overrides default color settings.  By default, the colors of options in
popups are determined by color scheme 2, (User Menus) of the current
color set.

+---------------------------------+
|             Examples            |
+---------------------------------+
*** RELATIVE Example ***

DEFINE POPUP relatyes RELATIVE FROM 1,1

DEFINE BAR 4  OF relatyes PROMPT '4444'
DEFINE BAR 3  OF relatyes PROMPT '3333'
DEFINE BAR 2  OF relatyes PROMPT '2222'
DEFINE BAR 1  OF relatyes PROMPT '1111'
DEFINE BAR 6  OF relatyes PROMPT '6666' BEFORE 4

ACTIVATE POPUP relatyes

*** NON-RELATIVE Example ***

DEFINE POPUP notrelat FROM 1,10
DEFINE BAR 4  OF notrelat PROMPT '444'
DEFINE BAR 3  OF notrelat PROMPT '3333'
DEFINE BAR 2  OF notrelat PROMPT '2222'
DEFINE BAR 1  OF notrelat PROMPT '1111'
DEFINE BAR 6  OF notrelat PROMPT '6666'