Creates a menu item on a menu created with DEFINE POPUP.

DEFINE BAR nMenuItemNumber1 | SystemItemName OF MenuName 
   PROMPT cMenuItemText [PICTURE cFileName] [PICTRES cMenubarName]
   [BEFORE nMenuItemNumber2 | AFTER nMenuItemNumber3]
   [FONT cFontName [, nFontSize [, nFontCharSet]]] [STYLE cFontStyle]
   [KEY KeyLabel [, cKeyText]] [MARK cMarkCharacter]
   [MESSAGE cMessageText] [SKIP [FOR lExpression]] 
   [COLOR SCHEME nSchemeNumber | COLOR ColorPairList] 
   [MRU] [INVERT]

Parameters

nMenuItemNumber1

Specifies the menu item number. The menu item number makes it possible for you to reference the menu item in other commands and functions.

SystemItemName

Specifies a menu item on the Visual FoxPro system menu. For example, to provide access to the Print menu item, issue the following:

	Copy Code
DEFINE BAR _MFI_PRINT OF popMyPopup PROMPT "Print..."

Not all Visual FoxPro system menu items are available. Use SYS(2013) to return a list of the Visual FoxPro system menu names that are available.

OF MenuName

Specifies the name of the menu on which the menu items are placed.

PROMPT cMenuItemText

Specifies the caption that appears on the menu item.

You can create a separator bar by specifying a backslash and a dash (\-) for cMenuItemText. A separator bar is used to separate item groups on a menu. For example, including the following command in a menu definition creates a separator bar between the third and fifth menu items:

	Copy Code
DEFINE BAR 4 OF popMyPopup PROMPT '\-'

You can create multi-column menus by specifying a backslash and a vertical bar (\|) at the beginning of cMenuItemText. The menu item starts a new column, and subsequent menu items are placed in the same column until another menu item beginning with \| is encountered. For example, including the following command in a menu definition creates a new column in the menu:

	Copy Code
DEFINE BAR 4 OF popMyPopup PROMPT '\|Start a new column'

You can create an access key for a menu item by placing a backslash and a less-than sign (\<) before the character to be the access key. For example:

	Copy Code
DEFINE POPUP popReceive DEFINE BAR 1 OF popReceive PROMPT '\<Invoices' DEFINE BAR 2 OF popReceive PROMPT 'In\<quiry' ACTIVATE POPUP popReceive

The user can press the I key to choose Invoices from the Receive menu and press the Q key to choose Inquiry from the same menu.

PICTURE cPictureName

Enables you to use an existing image with the menu bar. You can specify cPictureName in a relative path.

PICTRES cMenubarName

Specifies a system menu bar name as a resource for a menu. If cPictureName = "", then contents of Resname field of the .mnx table structure is treated as filename for use in DEFINE BAR...PICTURE. This functionality was introduced in Visual FoxPro 7.0.

Note
You must include a MARGIN clause in the appropriate DEFINE POPUP command in order for the PICTURE or PICTRES clauses to function properly.

BEFORE nMenuItemNumber2

Places a menu item before the menu item specified with nMenuItemNumber2.

AFTER nMenuItemNumber3

Places a menu item after the menu item specified with nMenuItemNumber3.

Note
In order for BEFORE or AFTER to have an effect, you must include the RELATIVE clause when you create the menu with DEFINE POPUP.

You can also include _MFIRST and _MLAST in the BEFORE and AFTER clauses. If you include_MFIRST in the BEFORE clause, the menu item is the first item on the menu. If you include_MFIRST in the AFTER clause, the menu item is the second item on the menu. If you include_MLAST in the AFTER clause, the menu item is the last item on the menu. If you include_MLAST in the BEFORE clause, the menu item is the next-to-last item on the menu.

Menus created with DEFINE POPUP RELATIVE do not reserve space for undefined menu items. For example, if you define items 1, 2, 4, and 5 on a menu, a space for item 3 is not reserved. You can later insert item 3. The menu expands to accommodate it.

The following program displays the differences in the order and placement of the items on each type of menu:

Copy Code

* DEFINE POPUP... 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 * DEFINE POPUP... non-relative example DEFINE POPUP popRelatNo FROM 1,10 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 popRelatYes NOWAIT && Display "relative" poup ACTIVATE POPUP popRelatNo && Display "non-relative" popup

FONT cFontName[, nFontSize [, nFontCharSet]]

Specifies a font for the menu item. 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 item in 12-point Courier font:

	Copy Code
DEFINE BAR 1 OF popReceive PROMPT '\<Invoices' 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 font style for the menu item. If you omit the STYLE clause, the normal font style is used. If the font style you specify is not available, the normal font style is used.

The font styles you can specify with cFontStyle are as follows:

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 BAR 1 OF popReceive PROMPT '\<Invoices' STYLE 'BI'

KEY KeyLabel[, cKeyText]

Specifies an access key or key combination for a menu item. The menu does not have to be activated in order for the menu item to be chosen, unlike when you assign an access key using a backslash and a less-than sign (\<).

For a list of available keys and key combinations and their key label names, see ON KEY LABEL Command.

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

Include cKeyText to replace the key label with your own text. You can use any character in the cKeyText parameter; for example, you can use the text "^B" to indicate a key label of CTRL+B. For example, including KEY CTRL+B places the text CTRL+B on the menu to the right of the menu item name, but specifying KEY CTRL+B, "^B" places the text ^+B on the menu. You can suppress the display of a key label by specifying an empty string for cKeyText.

MARK cMarkCharacter

Specifies a mark character that appears to the left of the menu item. 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.

The default mark character is a check.

The MARK clause is ignored and the default mark character is used if the menu containing the menu item is integrated into the Visual FoxPro system menu. Also, the MARK clause is ignored if FoxFont is not the font for the main Visual FoxPro window or the user-defined window in which the menu containing the menu item is placed.

Note
Specifying a mark character does not mark a menu item. Use SET MARK OF to mark a menu item.

Mark characters specified in DEFINE BAR take precedence over mark characters specified with MARK 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 the user selects a menu item. The message is placed in the graphical status bar. If the graphical status bar is turned off with SET STATUS BAR OFF, the message is centered on the last line of the main Visual FoxPro window.

SKIP [FOR lExpression]

Specifies a condition whereby if lExpression evaluates to true (.T.), the menu item is disabled, preventing the user from choosing it; if false (.F.), the menu item is enabled. A disabled menu item appears in the disabled colors.

You can also disable a menu item by placing a backslash (\) before the text of the prompt. For example:

	Copy Code
DEFINE BAR 1 OF popReceive PROMPT '\Invoices'

A menu item disabled with SKIP or \ cannot be selected.

COLOR SCHEME nSchemeNumber

Specifies the colors for an individual menu item, overriding the default colors or the colors specified with DEFINE POPUP.

COLOR ColorPairList

Specifies the colors for an individual menu item, overriding the default colors or the colors specified with DEFINE POPUP. You can specify the colors of all menu items, mark characters, and messages.

By default, the colors of menu items are determined by color scheme 2 of the current color set.

MRU

Specifies that the menu displays vertical chevrons indicating a Most Recently Used type menu. You must provide script that dynamically handles the menus and adds any new menu bars. For menus invoked with the MRU keyword, Visual FoxPro imposes a 1-2 second delay before triggering the ON SELECTION BAR command. A user can click on the menu bar to immediately trigger the ON SELECTION BAR command.

If you use the MRU keyword, Visual FoxPro ignores PROMPT and other keywords associated with the bar.

	Copy Code
DEFINE BAR 4 OF popMyPopup MRU

INVERT

Specifies that the menu displays with a sunken effect.

	Copy Code
DEFINE BAR 4 OF popMyPopup PROMPT '\|Start a new column' ; PICTRES _med_copy INVERT

Remarks

Example

The following example uses DEFINE BAR to create items on menus. The current system menu bar is first saved to memory with SET SYSMENU SAVE, and then all system menu titles are removed with SET SYSMENU TO.

Two new system menu titles are created with DEFINE PAD, and DEFINE POPUP is used to create a drop-down menu for each menu title. DEFINE BAR is used to create items on each of the menus. When a menu title is chosen, ON PAD uses ACTIVATE POPUP to activate the corresponding menu.

When an item is chosen from a menu, ON SELECTION POPUP uses PROMPT( ) and POPUP( ) to pass the item number and menu name to the CHOICE procedure. CHOICE displays the prompt of the chosen item and the name of the menu containing the item. If Exit is chosen from the Card Info menu, the original Visual FoxPro system menu is restored.

Copy Code

*** Name this program DEFINBAR.PRG *** CLEAR SET SYSMENU SAVE SET SYSMENU TO DEFINE PAD convpad OF _MSYSMENU PROMPT '\<Conversions' COLOR SCHEME 3 ; KEY ALT+C, '' DEFINE PAD cardpad OF _MSYSMENU PROMPT 'Card \<Info' COLOR SCHEME 3 ; KEY ALT+I, '' ON PAD convpad OF _MSYSMENU ACTIVATE POPUP conversion ON PAD cardpad OF _MSYSMENU ACTIVATE POPUP cardinfo DEFINE POPUP conversion MARGIN RELATIVE COLOR SCHEME 4 DEFINE BAR 1 OF conversion PROMPT 'Ar\<ea' KEY CTRL+E, '^E' DEFINE BAR 2 OF conversion PROMPT '\<Length' ; KEY CTRL+L, '^L' DEFINE BAR 3 OF conversion PROMPT 'Ma\<ss' ; KEY CTRL+S, '^S' DEFINE BAR 4 OF conversion PROMPT 'Spee\<d' ; KEY CTRL+D, '^D' DEFINE BAR 5 OF conversion PROMPT '\<Temperature' ; KEY CTRL+T, '^T' DEFINE BAR 6 OF conversion PROMPT 'T\<ime' ; KEY CTRL+I, '^I' DEFINE BAR 7 OF conversion PROMPT 'Volu\<me' ; KEY CTRL+M, '^M' ON SELECTION POPUP conversion; DO choice IN definbar WITH PROMPT( ), POPUP( ) DEFINE POPUP cardinfo MARGIN RELATIVE COLOR SCHEME 4 DEFINE BAR 1 OF cardinfo PROMPT '\<View Charges' ; KEY ALT+V, '' DEFINE BAR 2 OF cardinfo PROMPT 'View \<Payments' ; KEY ALT+P, '' DEFINE BAR 3 OF cardinfo PROMPT 'Vie\<w Users' KEY ALT+W, '' DEFINE BAR 4 OF cardinfo PROMPT '\-' DEFINE BAR 5 OF cardinfo PROMPT '\<Charges ' DEFINE BAR 6 OF cardinfo PROMPT '\-' DEFINE BAR 7 OF cardinfo PROMPT 'E\<xit ' ON SELECTION POPUP cardinfo; DO choice IN definbar WITH PROMPT( ), POPUP( ) PROCEDURE choice PARAMETERS mprompt, mpopup WAIT WINDOW 'You chose ' + mprompt + ; ' from popup ' + mpopup NOWAIT IF mprompt = 'Exit' SET SYSMENU TO DEFAULT ENDIF

See Also