DEFINE SUB-MENU statement

Defines a submenu widget that is created at compile time for use within a single procedure or class. You can use a submenu widget as a pull-down menu within a menu bar or as a submenu of a pull-down menu or pop-up menu.

Note: Does not apply to SpeedScript programming.

Syntax

DEFINE [ PRIVATE ] SUB-MENU `submenu` [ BGCOLOR `expression` ] [ DCOLOR `expression` ] [ FGCOLOR `expression` ] [ PFCOLOR `expression` ] [ FONT `number` ] [ SUB-MENU-HELP ] { LIKE `menu` \| `menu-element-descriptor` ... }

DEFINE [ PRIVATE ] SUB-MENU submenu 
  [ BGCOLOR expression ] 
  [ DCOLOR expression ] 
  [ FGCOLOR expression ]  
  [ PFCOLOR expression ] 
  [ FONT number ] 
  [ SUB-MENU-HELP ]  
  { LIKE menu | menu-element-descriptor ... }

[ PRIVATE ] SUB-MENU submenu

Defines and identifies a sub-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 sub-menu widget as a data element in a method or procedure.

Note: This option is applicable only when defining a class-scoped sub-menu widget in a class definition (.cls) file.

SUB-MENU submenu

Defines and identifies a submenu for access only within the current procedure, class, or method of a class.

BGCOLOR expression

Specifies the background color for the submenu in graphical interfaces. This option is ignored in character interfaces and Windows.

DCOLOR expression

Specifies the display color for the submenu in character interfaces. This option is ignored in graphical interfaces.

FGCOLOR expression

Specifies the foreground color for the submenu in graphical interfaces. This option is ignored in character interfaces.

PFCOLOR expression

Specifies the prompt-for color for the submenu in character interfaces. This option is ignored in graphical interfaces.

FONT number

Has no effect; supported only for backward compatibility.

SUB-MENU-HELP

Has no effect; supported only for backward compatibility.

LIKE menu

Specifies a previously defined menu or submenu whose characteristics you want to apply to the new submenu. If you name a menu with this option, you must have previously defined that menu in the procedure. If you name a submenu with this option, that submenu must have already been used as part of a menu definition.

menu-element-descriptor

Specifies an element displayed on the menu. Each element is either a choosable menu item, a submenu, non-choosable text, a rule, or a blank space. You must specify one or more menu elements, unless you use the LIKE option.

This is the syntax for menu-element-descriptor:


{ RULE SKIP SUB-MENU `submenu` [ DISABLED ] [ LABEL `label` ] `menu-item-phrase` }

RULE

Specifies that a rule or line is inserted at this point in the submenu. You can use this, for example, to divide the submenu into sections.

SKIP

Specifies that a blank line is inserted at this point in the submenu. You can use this, for example, to divide the submenu into sections.

SUB-MENU submenu [ DISABLED ] [ LABEL label ]

Specifies that a submenu is displayed at this 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 choosable 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  
  [ 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—possibly modified by SHIFT, CONTROL, or ALT—that chooses a menu item even if the menu is not displayed. The value keylabel must be a 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 interfaces. If you omit this option, the menu item inherits the background color of the submenu.

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 submenu.

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 interfaces. If you omit this option, the menu item inherits the foreground color of the submenu.

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 displays in the submenu for a choosable menu item or submenu. If you omit LABEL, the AVM displays the item handle by default.

You can include an ampersand (&) within the label to indicate that the following letter acts 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 a double ampersand (&&).

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 submenu.

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-menu.p procedure defines three pull-down submenus. One of the submenus, myedit, contains a nested submenu, myobjects. The procedure defines a menu bar, mybar, that contains two submenus labelled File and Edit. The handle of mybar is assigned to a window mywin. The ON statements define triggers to execute when you choose the corresponding menu items.

r-menu.p
DEFINE VARIABLE mywin AS HANDLE NO-UNDO. DEFINE SUB-MENU myfile MENU-ITEM m1 LABEL "Save" MENU-ITEM m2 LABEL "Save As" MENU-ITEM m3 LABEL "Exit". DEFINE SUB-MENU myobjects MENU-ITEM m1 LABEL "Circle" MENU-ITEM m2 LABEL "Line" MENU-ITEM m3 LABEL "Rectangle" MENU-ITEM m4 LABEL "Text". DEFINE SUB-MENU myedit SUB-MENU myobjects LABEL "Add" MENU-ITEM e1 LABEL "Delete" MENU-ITEM e2 LABEL "Copy". DEFINE MENU mybar MENUBAR SUB-MENU myfile LABEL "File" SUB-MENU myedit LABEL "Edit". CREATE WINDOW mywin ASSIGN MENUBAR = MENU mybar:HANDLE. DEFINE BUTTON b1 LABEL "Text Mode". DEFINE BUTTON b2 LABEL "Graphics Mode". CURRENT-WINDOW = mywin. FORM b1 at X 10 Y 120 b2 at x 120 Y 120 WITH FRAME x. ENABLE b1 b2 WITH FRAME x. ON CHOOSE OF b1 IN FRAME x DO: MENU-ITEM m1:SENSITIVE IN MENU myobjects = FALSE. MENU-ITEM m2:SENSITIVE IN MENU myobjects = FALSE. MENU-ITEM m3:SENSITIVE IN MENU myobjects = FALSE. MENU-ITEM m4:SENSITIVE IN MENU myobjects = TRUE. END. ON CHOOSE OF b2 IN FRAME x DO: MENU-ITEM m1:SENSITIVE IN MENU myobjects = TRUE. MENU-ITEM m2:SENSITIVE IN MENU myobjects = TRUE. MENU-ITEM m3:SENSITIVE IN MENU myobjects = TRUE. MENU-ITEM m4:SENSITIVE IN MENU myobjects = FALSE. END. WAIT-FOR CHOOSE OF MENU-ITEM m3 IN MENU myfile. DELETE WIDGET mywin.

r-menu.p

DEFINE VARIABLE mywin AS HANDLE NO-UNDO. 
DEFINE SUB-MENU myfile 
  MENU-ITEM m1  LABEL "Save" 
  MENU-ITEM m2  LABEL "Save As" 
  MENU-ITEM m3  LABEL "Exit". 
DEFINE SUB-MENU myobjects 
  MENU-ITEM m1  LABEL "Circle" 
  MENU-ITEM m2  LABEL "Line" 
  MENU-ITEM m3  LABEL "Rectangle" 
  MENU-ITEM m4  LABEL "Text". 
DEFINE SUB-MENU myedit 
  SUB-MENU myobjects LABEL "Add" 
  MENU-ITEM e1       LABEL "Delete" 
  MENU-ITEM e2       LABEL "Copy". 
DEFINE MENU mybar MENUBAR 
  SUB-MENU myfile LABEL "File" 
  SUB-MENU myedit LABEL "Edit". 
CREATE WINDOW mywin 
  ASSIGN MENUBAR = MENU mybar:HANDLE. 
DEFINE BUTTON b1 LABEL "Text Mode". 
DEFINE BUTTON b2 LABEL "Graphics Mode". 
CURRENT-WINDOW = mywin. 
FORM  
  b1 at X 10  Y 120  
  b2 at x 120 Y 120 
  WITH FRAME x. 
ENABLE b1 b2 WITH FRAME x. 
ON CHOOSE OF b1 IN FRAME x DO: 
  MENU-ITEM m1:SENSITIVE IN MENU myobjects = FALSE. 
  MENU-ITEM m2:SENSITIVE IN MENU myobjects = FALSE. 
  MENU-ITEM m3:SENSITIVE IN MENU myobjects = FALSE. 
  MENU-ITEM m4:SENSITIVE IN MENU myobjects = TRUE. 
END. 
ON CHOOSE OF b2 IN FRAME x DO: 
  MENU-ITEM m1:SENSITIVE IN MENU myobjects = TRUE. 
  MENU-ITEM m2:SENSITIVE IN MENU myobjects = TRUE. 
  MENU-ITEM m3:SENSITIVE IN MENU myobjects = TRUE. 
  MENU-ITEM m4:SENSITIVE IN MENU myobjects = FALSE. 
END. 
WAIT-FOR CHOOSE OF MENU-ITEM m3 IN MENU myfile. 
DELETE WIDGET mywin.

Notes

To create the compile-time defined submenu you are defining, along with any of its descendents (submenus and menu items), you must define a compile-time defined menu that contains the submenu. Each menu you define that contains the same submenu creates an additional instance of the submenu and each of its descendents. The handles for a compile-time defined submenu and its descendents are not available until the submenu is created in a menu.

You cannot define a submenu with the same name more than once in the same menu tree. Thus, if menu mFile contains both submenu mOptions and submenu mSave, submenu mSave cannot also contain submenu mOptions.

Menu items in different menus and submenus can have the same names. In the above procedure, the menu items in myfile and myobjects share the same names. To avoid ambiguity, use the IN MENU or IN SUB-MENU option to identify the parent menu or submenu.

There are instances where you cannot avoid ambiguity in menu item references. In such instances, ABL always references the first unambiguous instance of the menu item. In particular, if the same submenu containing a menu item appears in more than one menu and each menu defines another instance of the same menu item, you can only reference that menu item in the submenu from the first menu that contains it. Thus, if submenu mOptions contains menu item mSave and the menus mFile and mDraw (in that order) both contain submenu mOptions and another menu item mSave, you can only reference menu item mSave in submenu mOptions from menu mFile. You cannot uniquely reference menu item mSave in submenu mOptions from menu mDraw because menu mDraw contains another menu item mSave.

When a menu item is disabled, it appears grayed-out (if the environment supports that) and it cannot be chosen.