MenuName

Specifies the name of the menu to create.

FROM nRow1, nColumn1 TO nRow2, nColumn2

Specifies where the menu is placed. nRow1, nColumn1 specifies coordinates for the upper-left corner of the menu. If you omit the FROM clause, Visual FoxPro places the upper-left corner of the menu in the first row and first column of the main Visual FoxPro window or a user-defined window. To create a menu with a specific size, you can also include TO nRow2, nColumn2 to specify the location of the lower-right corner of the menu. If you include FROM nRow1, nColumn1 and omit TO nRow2, nColumn2, Visual FoxPro automatically sizes the menu. The menu is as wide as the longest menu item in it (if the items are created with DEFINE BAR) and as long as needed to display all of the menu items. The menu length is limited by the size of the main Visual FoxPro window or user-defined window in which the menu is placed. If a menu isn't large enough to contain all of the menu items, a scroll bar appears so that you can scroll through the menu items.

IN [WINDOW] WindowName

Places a menu in a user-defined window you specify with WindowName. If you omit this clause, the menu is placed on the main Visual FoxPro window by default unless there is an active user-defined window. If there is an active user-defined window, the menu is placed in the active window.

IN SCREEN

Explicitly places a menu in the main Visual FoxPro window.

FONT cFontName[, nFontSize [, nFontCharSet]]

Specifies a default font for the menu. You can override the default font for an individual menu item by including the FONT clause in DEFINE BAR. cFontName specifies the name of the font, and nFontSize specifies the point size. You can specify a language script with nFontCharSet. See the GETFONT( ) Function for a list of available language script values. For example, the following command creates a menu in 12-point Courier font:

В	Copy Code
DEFINE POPUP popMyPopup FONT 'Courier', 12

If the font you specify is not available, a font with similar font characteristics is substituted. If you include the FONT clause but omit the point size nFontSize, a 10-point font is used.

STYLE cFontStyle

Specifies a default font style for the menu. You can override the default style for an individual menu item by including the FONT clause in DEFINE BAR. If you omit the STYLE clause, or if the font style you specify is not available, the Normal font style is used. The font styles you can specify with cFontStyle are listed in the following table:

Character	Font style
B	Bold
I	Italic
N	Normal
Q	Opaque
-	Strikeout
T	Transparent
U	Underline

You can include more than one character to specify a combination of font styles. For example, the following command specifies Bold Italic:

В	Copy Code
DEFINE MENU popMyPopup STYLE 'BI'

FOOTER cFooterText

Creates a footer with the text specified with cFooterText centered in the bottom border of the menu.

KEY KeyLabel

Specifies an access key or key combination for a menu. For a list of available keys and key combinations and their key label names, see ON KEY LABEL Command. Including KEY is equivalent to issuing the following command:

В	Copy Code
ON KEY LABEL KeyLabel ACTIVATE POPUP MenuName

Note:
If a keyboard macro is already defined with the same key label, the keyboard macro takes precedence, and the menu cannot be activated with the specified key or key combination.

MARGIN

Places an extra space to the left and right of each menu item. Mark characters are displayed in the space to the left of an item, and arrows indicating additional cascading submenus are available and are displayed to the right of menu items. If you omit MARGIN, the mark characters overwrite the first character of the menu item names; hierarchical arrows overwrite the last character of the menu items.

Note:
You must include this clause if you want to use the DEFINE BAR ... PICTURE or PICTRES clauses.

MARK cMarkCharacter

Specifies a character that appears to the left of an item on the menu. The default mark character is a check mark. The MARK clause is ignored and the default mark character is used if the menu is integrated into the Visual FoxPro system menu. Also, the MARK clause is ignored if FoxFont isn't the font for the main FoxPro window or the user-defined window in which the menu is placed. MARK can be included to change the default mark character to a character specified with cMarkCharacter. If cMarkCharacter includes more than one character, only the first character is used as the mark character.

Note:
Specifying a mark character doesn't mark a menu item. Use SET MARK OF to mark a menu item.

The MARK clause sets the mark character for all items on the menu. Mark characters specified with DEFINE BAR commands take precedence over mark characters specified with the MARK clause in DEFINE POPUP. SET MARK OF is used to toggle mark characters on or off and can also be used to specify a mark character for an individual menu item or for all menu items.

MESSAGE cMessageText

Displays a message when you select a menu item. The message is placed in the graphical status bar. If the character-based status bar is turned on with SET STATUS ON, the message is centered on the last line of the main Visual FoxPro window.

MOVER

Places a double-headed arrow

in the Mover box to the left of the selected item in the menu. You can drag the double-headed arrow to move an item to another position on the menu. GETBAR(В ) can be used to determine where each item is positioned on the menu. You cannot rearrange items in a menu created with a PROMPT clause.

MULTISELECT

Allows the user to select multiple items from a menu at the same time. When the user chooses an item from a menu, the mark character is placed to the left of the item. You cannot make multiple selections from a menu created with a PROMPT clause. MRKBAR(В ) can be used to determine which items are chosen from the menu. If you include MULTISELECT in DEFINE POPUP, you can include MARGIN to reserve space in each item for the mark character. In the following example, a menu named popFruits is created. MULTISELECT is included to create a menu that allows multiple items to be chosen. Each of the four items has a different mark character. When a user chooses items from the menu, the items are marked and a routine named yourchoice displays the chosen items.

В

Copy Code

CLEAR ACTIVATE SCREEN DEFINE POPUP popFruits FROM 5,5 ; MULTISELECT MARGIN && Create multi-choice menu DEFINE BAR 1 OF popFruits ; PROMPT '\<Apples' MARK CHR(3) && First item DEFINE BAR 2 OF popFruits ; PROMPT '\<Bananas' MARK CHR(4) && Second item DEFINE BAR 3 OF popFruits ; PROMPT '\<Grapes' MARK CHR(5) && Third item DEFINE BAR 4 OF popFruits ; PROMPT '\<Lemons' MARK CHR(6) && Fourth item @ 12,5 SAY 'Your choices:' ON SELECTION POPUP popFruits DO yourchoice && Choice routine ACTIVATE POPUP popFruits PROCEDURE yourchoice && Executed when choice is made @ 13,5 CLEAR FOR gnCount = 1 TO CNTBAR('popFruits') && Loop for # of items IF MRKBAR('popFruits', gnCount) = .T. && Option is marked, ? PRMBAR('popFruits', gnCount) AT 5 && display caption ENDIF NEXT

PROMPT FIELD FieldName

Specifies the field name from an open table whose records become the items on the menu. The menu contains an item for each record in the table. When the menu is activated, the tables' work area is selected.

Tip:
You can take advantage of Rushmore Query Optimization if you set a filter on the field specified with PROMPT FIELD used in the menu. For more information on Rushmore Query Optimization, see SET OPTIMIZE Command and Using Rushmore Query Optimization to Speed Data Access in Optimizing Applications.

FieldName can also contain multiple field names and expressions concatenated with the addition operator (+). FieldName can also be the name of the field in a table open in another work area or a user-defined function. There is no limit to the number of entries that can appear in a menu created with PROMPT FIELD.

PROMPT FILES [LIKE FileSkeleton]

Creates a menu that displays the names of files available in the current directory. LIKE FileSkeleton allows you to specify the files that are displayed in the menu using wildcards. For example, to create a menu that displays the names of tables in the default drive and directory, include the following command:

В	Copy Code
PROMPT FILES LIKE *.DBF

You can create a menu that displays the names of files on other drives and in other directories or folders by including a drive or volume specification, a directory specification, or both. For example, to create a menu that displays the names of program files in a directory called PROGRAMS on drive C, include the following command:

В	Copy Code
PROMPT FILES LIKE C:\PROGRAMS\*.PRG

PROMPT STRUCTURE

Displays the names of the fields in the current table on the menu according to the table's field structure. When the menu is activated, the table's work area is selected.

RELATIVE

Specifies the order in which items are placed on a menu. If you create a menu without the RELATIVE clause, an item is positioned on a menu in an order dictated by the item's bar number. Space on the menu is reserved for undefined items. For example, if the first and third items are defined and the menu is activated, a blank line reserved for the second item is placed on the menu. If you create a menu with RELATIVE, the items appear on the menu in the order in which they are defined. Space in the menu isn't reserved for undefined items. Defining a menu with RELATIVE also lets you make use of BEFORE and AFTER clauses in DEFINE BAR to position items on a menu relative to other items. If a menu is created without RELATIVE, including BEFORE or AFTER in DEFINE BAR generates an error. Run the following two program examples and compare the placement of the items on each menu.

В

Copy Code

*** RELATIVE Example *** DEFINE POPUP popRelatYes RELATIVE FROM 1,1 DEFINE BAR 4 OF popRelatYes PROMPT '4444' DEFINE BAR 3 OF popRelatYes PROMPT '3333' DEFINE BAR 2 OF popRelatYes PROMPT '2222' DEFINE BAR 1 OF popRelatYes PROMPT '1111' DEFINE BAR 6 OF popRelatYes PROMPT '6666' BEFORE 4 ACTIVATE POPUP popRelatYes *** NON-RELATIVE Example *** DEFINE POPUP popRelatNo FROM 1,1 DEFINE BAR 4 OF popRelatNo PROMPT '4444' DEFINE BAR 3 OF popRelatNo PROMPT '3333' DEFINE BAR 2 OF popRelatNo PROMPT '2222' DEFINE BAR 1 OF popRelatNo PROMPT '1111' DEFINE BAR 6 OF popRelatNo PROMPT '6666' ACTIVATE POPUP popRelatNo

SCROLL

Places a scroll bar to the right of the menu you create. The scroll bar is displayed only when there are more items than can fit on the menu, or if the menu is too long to fit in the main Visual FoxPro window or the user-defined window in which it is placed.

SHORTCUT

Creates a shortcut menu. A shortcut menu typically appears when a selection, toolbar, or taskbar button is clicked with the right mouse button. The shortcut menu lists commands that pertain to the screen region on which the mouse was right-clicked. You can include MROW(В ) and MCOL(В ) in the FROM clause to activate the popup at the location where the mouse is clicked.

TITLE cMenuTitleText

Displays a title in the center of the top border of the menu. cTitleText specifies the menu title.

RTLJUSTIFY

Specifies that the text in the popup is justified in a right to left direction. The RTLJUSTIFY clause is intended for use with fonts that support bi-directional alignments. Issue SET SYSMENU TO LTRJUSTIFY to return the menu system to default left to right justification. This option is only available when Windows is configured to a Middle-Eastern locale.

COLOR SCHEME nSchemeNumber

Specifies the colors for all elements of a menu. By default, the colors of menus created with DEFINE POPUP are controlled by color scheme 2.

COLOR ColorPairList

Specifies the colors for all elements of a menu.

To place a set of menu items that you define on a menu, use a series of DEFINE BAR commands. To place records, files, or fields in a menu, use the PROMPT FIELD, PROMPT FILES, or PROMPT STRUCTURE options of DEFINE POPUP.

When the menu is displayed and activated with ACTIVATE POPUP, you can choose one of the items on the menu. Depending on the item chosen, a routine can be executed or another menu can be displayed and activated. A menu that displays another menu when an item is chosen is called a cascading submenu. For more information on creating submenus, see ON BAR Command.

If you use the Menu and Shortcut Designers to create your menu, you may not have to use these commands at all. The Menu Designer automatically creates the commands for your menu. The Menu Designer uses the Visual FoxPro system menu, which you can then modify by adding your own menu items.

For more information on creating menus, see Menu System Creation.