+---------------------------------+
|          DEFINE POPUP           |
+---------------------------------+
DEFINE POPUP <popup name>
        [FROM <row1>, <col1>]
        [TO <row2>, <col2>]
        [IN [WINDOW] <window name>
        | IN SCREEN]
        [FOOTER <expC1>]
        [KEY <key label>]
        [MARGIN]
        [MARK <expC2>]
        [MESSAGE <expC3>]
        [MOVER]
        [MULTI]
        [PROMPT FIELD <expr>
        | PROMPT FILES [LIKE <skel>]
        | PROMPT STRUCTURE]
        [RELATIVE]
        [SCROLL]
        [SHADOW]
        [TITLE <expC4>]
        [COLOR SCHEME <expN>
        | COLOR  <color pair list>]

-----------------------------------
Creates a popup.
-----------------------------------

DEFINE POPUP lets you create a menu popup.  A menu popup may contain a
list of options that you define, the records from a database field, a
list of files or a list of fields from a database.  To place a set of
options that you define in a menu popup, use a series of DEFINE BAR
commands.  To place records, files or fields in a popup, use the PROMPT
FIELD, PROMPT FILES or PROMPT STRUCTURE clauses of this command.

When the menu popup is activated and displayed with the ACTIVATE POPUP
command you may choose one of the options.  Depending on the option
chosen, a routine can be executed or another menu popup can be displayed
and activated.  A menu popup that displays another menu popup or a menu
bar when an option is chosen is called a hierarchical popup.  For more
information on creating hierarchical popups, see the ON BAR command.

Clauses
-------

<popup name>
        Name of popup to be created.

FROM <row1>, <col1>
TO <row2, col2>
        Specifies where popup is placed. If you include the FROM <row1>, <col1>
clause and omit the TO <row2>, <col2> clause, FoxPro automatically sizes
the menu popup for you.  The popup will be as wide as the longest menu
option and as long as needed to display all of the menu options.  The
popup length is limited by the screen or window size.  If a menu popup
is not large enough to contain all of the menu options, the menu options
will scroll within the menu popup.  You may scroll within a menu popup
by pressing the Up and Down Arrows or by clicking the mouse on the upper
or lower border of the menu popup.

IN [WINDOW] <window name>
| IN SCREEN
        Specifies window where popup is placed.  By default, popups are placed
on the screen unless there is an active output window.

FOOTER <expC1>
        Specifies a FOOTER that appears centered in bottom border of popup.

KEY <key label>
        Accepts <key label> to specify key or key combination used to activate
popup.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 POPUP <popup name> command.  If a keyboard macro is
already defined with the same <key label>, the keyboard macro takes
precedence and the popup cannot be chosen with the specified key or key
combination.

        A check mark character can be placed before every option in a menu
popup with the MARGIN and MARK clauses and the SET MARK OF command.  A
check mark may be used to indicate that a certain condition exists - an
option is available, the option is set on or off and so forth.

MARGIN
        Places extra space to left and right of each popup option.  Check marks
are displayed in the space to the left of an option, and an arrow
indicating an additional hierarchical popup is available is displayed to
the right of an option.  If the MARGIN option isn't included, check
marks will overwrite the first character of the options; a hierarchical
arrow may overwrite the last character of options.

MARK <expC2>
        Places mark character before each option in popup.  A small diamond (.)
is the default check mark for menu popup options.  The mark character
<expC2> must be enclosed in single or double quotation marks. If more
than one character is included in <expC2>, 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 options in a popup.  A
check mark specified in a DEFINE BAR command takes precedence over a
check mark specified in a DEFINE POPUP command.  The SET MARK OF command
is used to toggle check marks on or off, and may also be used to specify
a check mark for individual options.

MESSAGE <expC3>
        Displays message whenever popup is activated.  The message appears
centered on the screen in the position specified by the SET MESSAGE
command.

MOVER
        Rearranges options in popup.  A double-headed arrow . is placed to the
left of each option in the popup.  The popup options may be rearranged
by selecting an option and moving it.  To move an option with the mouse,
click on the double-headed arrow and drag the option up or down.  With
the keyboard, first select an option and then press Ctrl+. or Ctrl+. to
move the option up or down. The GETBAR() function returns the bar number
from a position in a popup, and can be used to determine where each
option is positioned in the popup.

MULTI
        Allows multiple options to be chosen from popup.  When an option is
chosen from a popup, a check mark character (by default a small diamond
(.)) is placed to the left of the option.

        To select multiple options from a menu popup with the keyboard, hold
down the Shift key and select the options by pressing Enter or the
Spacebar.  To select consecutive options, select one option, then hold
down the Shift key and press the Up or Down arrow key.

        To select multiple options with a mouse, hold down the Shift key and
click on the options.  To select consecutive options, hold down the
Shift key and drag the mouse through the options.

        The MRKBAR() function may be used to determine which options are chosen
from the menu popup.  The MRKBAR() function returns a logical true (.T.)
value if an option is marked.  Because choosing an option from a popup
created with the MULTI keyword marks the option, MRKBAR() can be used to
determine which options are chosen.

        If you include the MULTI keyword when creating a menu popup, you may
also want to include the MARGIN keyword to reserve a space in each
option for the mark character.  If the MARGIN option isn't included, the
check mark character will overwrite the first character of each option.

        You cannot make multiple selections from a popup created with any of
the PROMPT options (FIELD, FILES or STRUCTURE).

PROMPT FIELD <expr>
        Specifies field from an open database whose records become options in
popup.  The menu popup will contain an option for each record in the
database.  When the popup is activated the work area containing the
database is selected.

        You can take advantage of Rushmore optimization if you set a filter on
the PROMPT field used in the popup.  For further details on Rushmore
optimization, see the Optimizing Your Application chapter in the FoxPro
Developer's Guide.

        The general expression <expr> can also contain multiple field names and
expressions concatenated together with the addition (+) operator.
<expr> can also be field in a database open in another work area or a
UDF (user-defined function).