Where:

ctl_id	Unique logical identifier for the menu bar. Use an integer between -32000 to +32000. Avoid integers that conflict with keyboard definitions (e.g., 4 cancels CTL=4for the F4 key) or special negative CTL values set by the system. See Negative CTL Definitions.
element[$]	Individual menu selection. Expression consisting of shortcut letters or assigned item CTL values for accessing the selection.
menu_def$	Menu structure and elements. String expressions. Maximum 2047 elements. A bitmap/icon can be included for each element in the menu. Tip: To determine how many elements you already have, count the ampersands (&).
stmtref	Program line number or statement label to which to transfer control.
var$	String variable to receive the last selected menu item.

MENU_BAR ctl_id,menudef$[,ERR=stmtref]

This format creates a menu bar control object. If the menu bar is not properly defined, ProvideX returns an Error #87: MENUBAR definition invalid. Define the menuef$ of menu groups and elements and identify each item uniquely (e.g., Fand O would identify ile/pen) 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 & (an ampersand).
• Prefix each sub-menu group with its item ID.

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

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

ProvideX includes the HELPselection on all menu bars by default. You can suppress the HELPselection by inserting a minus sign "-" as the first character in a menu definition string, as in the example above.

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; e.g.,

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, 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'll have difficulty determining which selection a user makes unless a unique CTL value is assigned to each item. If you omit a shortcut key, ProvideX 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 place holder 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 = (equal sign) and before the assigned CTL value. ; e.g.,
"[&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; e.g.,

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 colour, and "G" means use gray colour as transparent (RGB: 192,192,192) as in E:[{!Copy,t}&Copy,{!Paste,g}&Paste].

For more information on internal/external images and recognized image file types, refer to Displaying Bitmaps/Icons

LEFT(arg)	Background colour for the bitmap portion of the menu. Must be placed outside "[...]" menu definitions.
FILL(arg)	Background colour for the right/text side. If placed outside "[...]" menu definitions it will serve as the default colour for all menuitems. If placed within "[...]", it will be considered the colour associated with a specific menu item. The arg value is defined using the same format as the Colour Properties. :

In the following example, the RGB colour 200,200,200 is used for the left edge of all entries in this menu

MENU_BAR 10,"LEFT(RGB:200,200,200),[&File,&Edit,&Help],F:[...."

The next example uses the RGB colour 255,255,150 as the background colour for all of the text portion of the menu.

MENU_BAR 10,"FILL(RGB:255,255,150),[&File,&Edit,&Help],F:[...."

MENU_BAR READ var$[,ERR=stmtref]

When a user selects any of the items from a menu bar, ProvideX 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.

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.

MENU_BAR RESET[,ERR=stmtref]

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

MENU_BAR GOTO[,ERR=stmtref]

MENU_BAR GOTO sets the focus on the menu bar.

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; e.g., 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; e.g.,

MENU_BAR ON 12034
MENU_BAR OFF "#12034,#12035,#12036"

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, above.

MENU_BAR REMOVE[,ERR=stmtref]

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