MENU_BAR |
Create/Control Menu Bar |
MENU_BAR ctl_id,menu_def$[,ERR=stmtref] | |
MENU_BAR READ var$[,ERR=stmtref] | |
3. Clear Menu Bar: |
MENU_BAR CLEAR[,ERR=stmtref] |
MENU_BAR RESET[,ERR=stmtref] | |
5. Set Focus: |
MENU_BAR GOTO[,ERR=stmtref] |
MENU_BAR {ON | OFF} element[$][,ERR=stmtref] | |
MENU_BAR {DISABLE | ENABLE} element[$][,ERR=stmtref] | |
8. Remove Menu Bar: |
MENU_BAR REMOVE[,ERR=stmtref] |
The following were added in PxPlus 2020: | |
MENU_BAR FIND X$ | |
10. Set Menu Bar Entries: |
MENU_BAR LOAD X$ |
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=4 for 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. Helpful Tip: |
stmtref |
Program line number or statement label to which to transfer control. |
var$ |
String variable to receive the last selected menu item. |
Use the MENU_BAR directive to define and control the menu across the top of a window.
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:
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]"
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]"
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 colour, and "G" means use gray colour 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.
(Support to allow the inclusion of the special characters used to define the menu was added in PxPlus 2021.)
The MENU_BAR directive supports the use of two optional parameters for defining background and left edge colours in menus (similar to MS Office applications):
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. |
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 RGB colour 255,255,150 is used 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, 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.
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.
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"
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.
MENU_BAR REMOVE[,ERR=stmtref]
This format deletes the menu bar completely from the current session. It cannot be redisplayed until it is redefined.
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.)
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.)