Directives 

Formats

Where:

Description

Use the MENU_BAR directive to define and control the menu across the top of a window.

Format 1

Define/Create Menu Bar

MENU_BAR ctl_id,menu_def$[,ERR=stmtref]

This format creates a menu bar control object. If the menu bar is not properly defined, PxPlus returns an Error #87: MENUBAR definition invalid.

Define the menu_def$ of menu groups and elements and identify each item uniquely (e.g. F and O would identify File/ Open) by marking the character the user can enter in conjunction with the Alt key (e.g. Alt - F) to select the particular item. Use the following format for your string expression:

• Enclose each menu group in square brackets.
• Delimit each item in a group with a comma.
• Prefix each item's selection character (hot key) with & (ampersand).
• Prefix each sub-menu group with its item ID.

Example:

The example below shows a menu string containing File and Edit, each with a sub-menu (File: Open, Save and Quit / Edit: Add and Delete). Each item has a shortcut key. Quit has both the shortcut key (Q) and a control ID value (4).

menu_bar 100,"-[&File,&Edit],F:[&Open,&Save,&Quit=4],E:[&Add,&Delete]"

PxPlus includes the HELP selection on all menu bars by default. You can suppress the HELP selection by inserting a "-" (minus sign) as the first character in a menu definition string, as in the above example.

Right justify a description of the menu entry (e.g. to tell users what function key will give them quick access to the selection). Use the tab character $09$ to separate the text to be right justified:

Example:

menu_bar 99,"[&File,&Edit...],E:[&Cut"+$09$+"Shft-DEL,&Paste"+$09$+"Ins]"

Assigning CTL Values

Normally, any selection from the menu bar will generate its ctl_id. You can also have individual menu items generate CTL values. To do this, append an "=" (equals sign) and CTL value to any item in the menu selection list (e.g. &Quit=4, as in the example above). It is best to use unique shortcut keys for selections from a given sub-menu in a group. If you have duplicates, you will have difficulty determining which selection a user makes unless a unique CTL value is assigned to each item. If you omit a shortcut key, PxPlus assigns a value equivalent to the item's placement in the definition string.

Add a line to separate options by inserting an additional "," (comma) as a placeholder in the definition string (e.g. between &Open &Save):

menu_bar 120,"[&File],F:[&Open,,&Save,&Quit=4]"

Menu items can be disabled or displayed in bold or with a checkmark by placing a "D", "B" or "C" after the "=" (equals sign) and before the assigned CTL value:

Example:

"[&One=1,&Two=C2,&Three=D3]"

Bitmaps and Icons

Images can be included for each item in the menu. Enclose the image name in { } (curly braces) and place it in the menu definition just prior to the specific item text:

Example:

menu_bar 1000,"-[&File],F:[&Open=1001,{!Stop}&Stop=1002]"

Use a leading "!" (exclamation point) to identify the image as internal, or specify the relative path and filename to access an image file that is external. The first bitmap determines the dimensions used to display menu items (up to 64x64). Bitmap/image transparency options can also be included. "T" indicates use of the upper left most pixel color, and "G" means use gray color as transparent (RGB: 192,192,192), as in E:[{!Copy,t}&Copy,{!Paste,g}&Paste].

For information on internal/external images and recognized image file types, see Displaying Bitmaps/Icons.

Inclusion of Special Characters

If the text you want to include has any of the characters used to define the menu bar, which is {, }, [, ], = (equals sign), & (ampersand), : (colon) or , (comma), you will need to escape these characters with the backslash and put a backslash as the first character of the menu definition string.

Example:

If you want an entry in the menu bar to read "Export [to Word]", your menu_bar command would look like this:

menu_bar 120,"\[&File],F:[&Open,,&Save,&Export \[to Word\],&Quit=4]"

The first character of the menu bar definition string being a backslash indicates to the system that the menu bar contains escaped characters. Any subsequent character in the string preceded by a backslash will not be considered as a delimiter/control character and included in the menu_bar text.

Note:
When combining the leading backslash and the leading - to suppress help, the backslash must be specified first.

(Support to allow the inclusion of the special characters used to define the menu was added in PxPlus 2021.)

Menu Colors

The MENU_BAR directive supports the use of parameters for defining colors in menus. The arg value is defined using the same format as the Color Properties.

This table lists the parameters that can be used:

Apply Color to Top Menu 

If the first character of the menu definition is an ! (exclamation point), or a first or second character of - (dash) is also specified, then the specified colors will also be applied to the top level menu (the horizontal menu at the top of the window).

By default, the color will not apply to the top level menu.

Examples

The following examples show how color can be applied when creating a menu:

Example 1 - This creates a menu with a Dark Cyan background and White text:

menu_bar 10,"!LEFT(RGB:100,100,100),FILL(Dark Cyan),TEXT(RGB:255,255,255)[&File,&Edit,&Help],F:[&Open,&Save,&Quit],E:[&Add,&Delete],H:[&Version Info]"

Example 2 - This creates a menu with a different hover color and one item on the File menu with a different color:

menu_bar 10,"-!HFILL(RGB:200,200,200),HTEXT(RGB:0,0,0)[&File,&Edit,&Help],F:[&Open,&Save=1001=FILL(RGB:0,0,230)=TEXT(RGB:255,255,255),&Quit],E:[&Add,&Delete],H:[&Version Info]"

Example 3 - This uses RGB color 200,200,200 for the left edge of all entries in this menu:

menu_bar 10,"LEFT(RGB:200,200,200),[&File,&Edit,&Help],F:[&Open,&Save,&Quit],E:[&Add,&Delete],H:[&Version Info]"

Example 4 - This uses RGB color 255,255,150 as the background color for all of the text portion of the menu:

menu_bar 10,"FILL(RGB:255,255,150),[&File,&Edit,&Help],F:[&Open,&Save,&Quit],E:[&Add,&Delete],H:[&Version Info]"

(Support to allow more control when applying top-level menu colors was added in PxPlus 2024.)

Format 2

Read Selected Item

MENU_BAR READ var$[,ERR=stmtref]

When a user selects any of the items from a menu bar, PxPlus generates the ctl_id you assigned to the menu bar.

You can return the selected CTL value in a string variable by using the MENU_BAR READ directive. A program does not receive the CTL value for the menu item the user has chosen until it is read.

Format 3

Clear Menu Bar

MENU_BAR CLEAR[,ERR=stmtref]

Use the MENU_BAR CLEAR format to remove the menu bar from the current window until a BEGIN or END is executed.

Note:
Using MENU_BAR CLEAR also causes the window to shrink unless the MENU_BAR CLEAR is followed with a SIZE mnemonic.

Format 4

Restore Standard Help

MENU_BAR RESET[,ERR=stmtref]

This format resets the current menu bar to the default Help setting.

Format 5

Set Focus

MENU_BAR GOTO[,ERR=stmtref]

MENU_BAR GOTO sets the focus on the menu bar.

Format 6

'Check'/'Uncheck' Item

MENU_BAR {ON | OFF} element[$][,ERR=stmtref]

The MENU_BAR ON option displays a check mark in front of a specified menu bar item, making it appear that it was selected. MENU_BAR OFF removes the check mark.

Toggling

For Formats 6 and 7, menu items element[$] are usually identified via shortcut keys.

Example:

menu_bar on "FPS" (Toggles items File, Print, Save)

When using CTL values and more than one menu item uses the same CTL, then all menu items using that CTL will be toggled. If toggling just one item, then use that CTL value only. If toggling more than one, then make a string of the CTL values, prefixing a "#" (pound sign) to each CTL value separated by commas:

Example:

menu_bar on 12034
menu_bar off "#12034,#12035,#12036"

Format 7

Disable/Enable Item

MENU_BAR {DISABLE | ENABLE} element[$][,ERR=stmtref]

Use the MENU_BAR DISABLE format to gray out the specified menu bar item so that it will be visible but inaccessible to users. To reactivate it, use MENU_BAR ENABLE. See Toggling.

Format 8

Remove Menu Bar

MENU_BAR REMOVE[,ERR=stmtref]

This format deletes the menu bar completely from the current session. It cannot be redisplayed until it is redefined.

Note:
Using MENU_BAR REMOVE also causes the window to shrink unless the MENU_BAR REMOVE is followed with a SIZE mnemonic.

Format 9

Return Menu Bar Character Codes

MENU_BAR FIND X$

This format returns a string consisting of all the menu bar character codes, followed by a colon and their settings. For example, if File > Open has a check mark, the string would include FO:C.

The string will include all codes currently in the menu bar and their respective status consisting of "C" for Checked, "D" for Disabled and "E" for Enabled. All codes, therefore, will have either "E" or "D" and optionally "C" if checked. Each code will be separated by a comma.

Example:

menu_bar find X$
print X$
M:E,B:E,R:E,BP:EC,BW:D,BA:E

(The MENU_BAR FIND format was added in PxPlus 2020.)

Format 10

Set Menu Bar Entries

MENU_BAR LOAD X$

This format sets the enabled/disabled and optionally the On/Off status of menu bar entries based on their codes. This is done via a string consisting of a comma-separated list of menu codes, followed by a colon and their settings: "E" for Enabled or "D" for Disabled, and optionally "C" for Checked (On). Invalid character sequences will simply be ignored.

Example:

menu_bar load "M:D,B:E,BP:EC"

(The MENU_BAR LOAD format was added in PxPlus 2020.)