Creates a menu item on a menu created with DEFINE POPUP.
Syntax
DEFINE BAR nMenuItemNumber1 | SystemItemName
OF MenuName PROMPT cMenuItemText
[BEFORE nMenuItemNumber2 | AFTER nMenuItemNumber3]
[FONT cFontName [, nFontSize]]
[STYLE cFontStyle]
[KEY KeyLabel [, cKeyText]]
[MARK cMarkCharacter]
[MESSAGE cMessageText]
[SKIP [FOR lExpression]]
[COLOR SCHEME nSchemeNumber
| COLOR ColorPairList]
Arguments
nMenuItemNumber1
Specifies the menu item number. The menu item number allows 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:
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:
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:
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:
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.
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 don't 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.
Run the following program examples and note the differences in the order and placement of the items on each menu:
*** 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,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 popRelatNo
FONT cFontName [, nFontSize]
Specifies a font for the menu item. cFontName specifies the name of the font, and nFontSize specifies the point size. For example, the following command creates a menu item in 12-point Courier font:
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:
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.
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 isn't 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 doesn't 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:
DEFINE BAR 1 OF popReceive PROMPT '\Invoices'
A menu item disabled with SKIP or \ cannot be selected. Menus you create that include SKIP FOR expressions may not behave properly when the spelling checker or wizards are active.
SKIP FOR expressions typically depend on the value of skip variables, but the skip variables are not visible to your menus when the spelling checker or wizards are active. In the initialization code of the spelling checker and wizard applications (SPELLCHK.APP and GENGRAPH.APP respectively), PRIVATE ALL is intentionally issued. This hides skip variables from user-defined menus and causes an error message when you choose a menu.
To correct this situation, the following code is placed at the beginning of the spelling checker and wizard applications:
IF TYPE("_memvarmask") = "C" and !EMPTY(_memvarmask)
PRIVATE ALL EXCEPT &_memvarmask
ELSE
PRIVATE ALL
ENDIF
Suppose a certain menu item should be skipped when the variable named "skipvar" evaluates to true. You should include the following lines in your menu startup code to take advantage of the _MEMVARMASK variable:
PUBLIC _memvarmask
_memvarmask = "skipvar"
STORE .T. TO skipvar && Skip initially.
To create a set of skip variables, include the following lines in your menu startup code:
PUBLIC _memvarmask
_memvarmask = "skip*"
STORE .T. TO skipthis, skipthat && Skip initially.
When you run the spelling checker and wizards, they don't hide variables in SKIP FOR expressions, preventing the error messages you may experience when the spelling checker or wizards are active.
Note that _MEMVARMASK isn't a system variable.
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.
For more information on color schemes and color pairs, see the Colors Overview topic.
Remarks
DEFINE BAR is used with DEFINE POPUP to create menus. A menu is created and assigned a name with DEFINE POPUP. Menu items are placed on the menu with a series of DEFINE BAR commands.
If you use the Menu Designer 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 "Creating a Menu System" in Chapter 11, Designing Menus and Toolbars, in the Programmer's Guide.
You can also create a menu that contains records or fields from a table or a list of files available on disk. For more information, see the PROMPT FIELD, PROMPT STRUCTURE and PROMPT FILES clauses in DEFINE POPUP.
Use ON BAR to create a cascading submenu for a menu item.