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
- You cannot define a SHARED or NEW SHARED menu widget in a persistent procedure. If you
do, ABL raises ERROR on the RUN statement that creates the procedure.
- You cannot define a SHARED or NEW SHARED menu widget in a class definition
(.cls) file. If you do, ABL generates a compilation error.
- Keyboard accelerators are specified for menu-items forward and backward. The user can
press PAGE-DOWN key to look at the next Customer record and the PAGE-UP to view the
previous Customer record.
- The menu item quititem has a label E&xit; the ampersand makes X the mnemonic for
that menu item.
- 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.