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...}
|
- [ 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
- 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.
|
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.