Release 10.1A: OpenEdge Development:
Progress 4GL Reference

> ## DEFINE MENU statement

> Defines and creates a pop-up menu or a menu bar for use in one or more procedures.

> 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 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 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 data member for a class, and optionally specifies an access mode for that data member. Do not specify the access mode when defining a menu widget for a method within a class.

> PRIVATE data members can be accessed only by the defining class. The default access mode is PRIVATE.

> Note: This option is applicable only when defining a data member for a class in a class definition (`.cls`) file.

> `MENU `menu-name``

> Identifies the name of the menu you are defining. You can define the menu widget in a procedure or a method within a class.

> `BGCOLOR `expression``

> Supported only for backward compatibility. Progress does not support this option in Windows or character interfaces.

> `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. Progress does not support this option in Windows or character interfaces.

> `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. Progress does not support this option in Windows or character interfaces.

> `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 Progress, such as a, F1, or ALT+SHIFT+F1.

> `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.cust-num.
>     ON CHOOSE OF MENU-ITEM addr
>       DISPLAY customer.address customer.address2 customer.city
>         customer.state customer.postal-code WITH FRAME addr-frame NO-LABELS
>         COLUMN 25.
>     ON CHOOSE OF MENU-ITEM othrinfo
>       DISPLAY customer EXCEPT name cust-num address
>         address2 city state postal-code
>         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, Progress 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, Progress 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, Progress 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. For more information on menu item references, see the chapter on menus in OpenEdge Development: Progress 4GL Handbook .

> #### See also

> COLOR phrase, DEFINE SUB-MENU statement, RUN statement

Copyright © 2005 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095