DEFINE MENU statement

Defines a menu widget that is created at compile time for use in one or more procedures, or within a single class. You can use a menu widget as a pop-up menu or a menu bar.

Note: Does not apply to SpeedScript programming.

Syntax

DEFINE {[[ NEW ] SHARED ]|[ PRIVATE ]} MENU menu-name 
  [ FGCOLOR expression]
  [ BGCOLOR expression] 
  [ DCOLOR expression]
  [ PFCOLOR expression]
  [ FONT number]
  [{ TITLE title}| MENUBAR ] 
  [{ LIKE menu}|menu-element-descriptor...]
NEW SHARED MENU menu-name
Defines and identifies a menu widget that can be used by other procedures. The menu remains available to other procedures until the procedure that contains this statement ends.
SHARED MENU menu-name
Defines and identifies a menu widget that was created in another procedure with the DEFINE NEW SHARED MENU statement.
[ PRIVATE ] MENU menu-name

Defines and identifies a menu widget as a class-scoped object. A class-scoped handle-based object is not a member of a class, but provides a resource that is privately available to the class definition similar to a non-shared data element in a procedure definition. The option to specify the PRIVATE access mode is provided for readability. You cannot specify PRIVATE when defining a menu widget as a data element in a method or procedure.

Note: This option is applicable only when defining a class-scoped menu widget in a class definition (.cls) file.
MENU menu-name
Defines and identifies a menu widget for access only within the current procedure, class, or method of a class.
BGCOLOR expression
Supported only for backward compatibility.
DCOLOR expression
Specifies the display color for the menu in character interfaces. This option is ignored in graphical interfaces.
FGCOLOR expression
Supported only for backward compatibility.
PFCOLOR expression
Specifies the prompt-for color for the menu in character interfaces. This option is ignored in graphical interfaces.
FONT number
Supported only for backward compatibility.
MENUBAR
Specifies that the menu displays as a menu bar.
TITLE title
Specifies the title of the menu. Only pop-up menus can have titles. This option is invalid for menu bars. The title displays at the top of the menu. In environments that do not support this option, it is ignored.
LIKE menu
Specifies a previously defined menu whose characteristics you want to apply to the new menu. If you name a menu with this option, you must have defined that menu previously in the procedure.
menu-element-descriptor

Specifies an element display on the menu. Each element is either a normal menu item, a submenu, a rule, or a blank space. The last two are valid only for pop-up menus. You must specify one or more menu elements, unless you use the LIKE option.

This is the syntax for menu-element-descriptor:

{ menu-item-phrase
   SUB-MENU submenu [ DISABLED ][ LABEL label ]
   RULE
   SKIP
}
RULE
Specifies that a rule or line is inserted at this point in the menu. You can use this, for example, to divide the menu into sections.
SKIP
Specifies that a blank line is inserted at this point in the menu. You can use this, for example, to divide the menu into sections.
SUB-MENU submenu[ DISABLED ][ LABEL label]
Specifies that a submenu displays as a menu item. The submenu must be previously defined in the procedure. The submenu appears when the user chooses that item. The submenu cannot be a menu bar. The DISABLED and LABEL options for a submenu are the same as described for the menu-item-phrase.
menu-item-phrase

Specifies a normal menu item. This is the syntax for menu-item-phrase:

MENU-ITEM menu-item-name 
  [ ACCELERATOR keylabel]
  [ BGCOLOR expression]
  [ DCOLOR expression]
  [ DISABLED ]
  [ FGCOLOR expression] 
  [ FONT expression]
  [ LABEL label]
  [ PFCOLOR expression]
  [ READ-ONLY ]
  [ TOGGLE-BOX ]
  [trigger-phrase]
MENU-ITEM menu-item-name
The name of the menu item you are defining.
ACCELERATOR keylabel
Specifies a keyboard accelerator for this menu item. A keyboard accelerator is a key—sometimes modified by SHIFT, CONTROL, or ALT—that chooses a menu item even if the menu is not displayed. The value keylabel must be character-string expression that evaluates to a valid key label recognized by the AVM, such as a, F1, or ALT+SHIFT+F1. See the chapter on handling user input in the OpenEdge Development: Programming Interfaces for the precedence rules that the AVM uses for handling keyboard input.
BGCOLOR expression
Specifies the background color for the menu item in graphical environments. If you omit this option, the menu item inherits the background color of the menu.
DCOLOR expression
Specifies the display color for the menu item in character interfaces. If you omit this option, the menu item inherits the display color of the menu.
DISABLED
Specifies that the menu item is initially disabled for input. This means that the user cannot choose this item. Disabled items are grayed out (in environments that support it).
FGCOLOR expression
Specifies the foreground color for the menu item in graphical environments. If you omit this option, the menu item inherits the foreground color of the menu.
FONT expression
Specifies the font for the menu item. If you omit this option, the menu item inherits the font of the menu.
LABEL label

Specifies the text that is displayed in the menu for a choosable menu item or submenu. Include an ampersand (&) within the label to assign the following letter as a mnemonic for the menu item. This means that when the menu is displayed, the user can choose the item by pressing that single key. If you do not include an ampersand within the label, Windows treats the first character as a mnemonic.

To include a literal ampersand within a label, specify two ampersands (&&).

PFCOLOR expression
Specifies the prompt-for color for the menu item in character interfaces. If you omit this option, the menu item inherits the prompt-for color of the menu.
READ-ONLY
Specifies that this menu item is read-only text. The user cannot choose this item.
TOGGLE-BOX
Specifies that the menu item is displayed as a checkbox that the user can toggle on or off. In environments that do not support this option, it is ignored.
trigger-phrase

Specifies application triggers for the menu item. Typically, you associate a CHOOSE trigger with each menu item.

For more information, see the Trigger phrase reference entry.

Example

The r-bar.p procedure defines a menu bar, mbar, that contains three pull-down submenus labeled Topic, Move, and Exit. The handle of mbar is assigned to the current window. The ON statements define triggers to execute when you choose the corresponding menu items.

r-bar.p

DEFINE SUB-MENU topic
  MENU-ITEM numbr    LABEL "Cust. Number"
  MENU-ITEM addr     LABEL "Address"
  MENU-ITEM othrinfo LABEL "Other".
DEFINE SUB-MENU move
  MENU-ITEM forward  LABEL "NextRec" ACCELERATOR "PAGE-DOWN"
  MENU-ITEM backward LABEL "PrevRec" ACCELERATOR "PAGE-UP".
DEFINE SUB-MENU quitit
  MENU-ITEM quititem LABEL "E&xit".

DEFINE MENU mbar MENUBAR
  SUB-MENU topic  LABEL "Topic"
  SUB-MENU move   LABEL "Move"
  SUB-MENU quitit LABEL "E&xit".

ON CHOOSE OF MENU-ITEM numbr
  DISPLAY Customer.CustNum.

ON CHOOSE OF MENU-ITEM addr
  DISPLAY Customer.Address Customer.Address2 Customer.City
    Customer.State Customer.PostalCode 
    WITH FRAME addr-frame NO-LABELS COLUMN 25.

ON CHOOSE OF MENU-ITEM othrinfo
  DISPLAY Customer EXCEPT Customer.Name Customer.CustNum Customer.Address
    Customer.Address2 Customer.City Customer.State Customer.PostalCode
    WITH FRAME oth-frame SIDE-LABELS.

ON CHOOSE OF MENU-ITEM forward DO:
  HIDE ALL NO-PAUSE.
  CLEAR FRAME name-frame.
  FIND NEXT Customer NO-ERROR.
  IF AVAILABLE Customer THEN
    DISPLAY Customer.Name WITH FRAME name-frame. 
END.

ON CHOOSE OF MENU-ITEM backward DO:
  HIDE ALL NO-PAUSE.
  CLEAR FRAME name-frame.
  FIND PREV Customer NO-ERROR.
  IF AVAILABLE Customer THEN
    DISPLAY Customer.Name WITH FRAME name-frame.
END.

FIND FIRST Customer.
DISPLAY Customer.Name LABEL "Customer Name" WITH FRAME name-frame.
ASSIGN CURRENT-WINDOW:MENUBAR = MENU mbar:HANDLE.
WAIT-FOR CHOOSE OF MENU-ITEM quititem.

Notes

See also

Class-based data member access, COLOR phrase, DEFINE SUB-MENU statement, RUN statement