DEFINE BAR Command

Article
11/14/2006

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]] [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:
```
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.
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 version 7.

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:
```
   * 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]
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 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:
```
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 do not hide variables in SKIP FOR expressions, preventing the error messages you may experience when the spelling checker or wizards are active.

Note that _MEMVARMASK is not 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.
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.
```
DEFINE BAR 4 OF popMyPopup MRU
```

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

INVERT
Specifies that the menu displays with a sunken effect.

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

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 Designing Menus and Toolbars.

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.

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.

_** 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

DEFINE BAR Command

Parameters

Remarks

Example

See Also

Additional resources