menubar
Put up a custom menu bar
Description
The menubar object provides control over the menu bar. It allows your patch to put up its own menus, and add items to standard File and Edit menus. When a menu item is chosen, the item number is sent out the outlet corresponding to the menu containing the item.
Discussion
You configure the menubar by writing a script in a text editor window available by double-clicking on the object in a locked patcher.
When you close the script window and confirm saving the changes, the script file is interpreted. If there are no errors, the customized menu bar will be ready for use when menubar receives a nonzero number in its inlet.
Each message should be preceded by #X and end with a semicolon (; ).
Here is an example menubar script:
#X about About Note Algorithms…;
#X closeitem;
#X menutitle 5 Algorithm;
#X item 5 1 Transpose;
#X item 5 2 Invert;
#X item 5 3 Randomize;
#X end;
Note that we suggest capitalizing each letter in a menu item to maintain a consistent style with other items in the menu.
Arguments
display and behavior[int]
optional
The argument sets the number of menus in the object's menu bar. If present, it must be at least 5 (one additional menu). The four default menus, which are always present, are File, Edit, Windows., and Help. On Macintosh, the Standard System Menu with the Apple icon and the Max application menu will appear to the left of the other menus.
Attributes
Common Box Attributes
annotation[symbol]
Sets the text that will be displayed in the Clue window when the user moves the mouse over the object.
background[int]: 0
Adds or removes the object from the patcher's background layer. background 1 adds the object to the background layer, background 0 removes it. Objects in the background layer are shown behind all objects in the default foreground layer.
color[4 floats]
Sets the color for the object box outline.
fontface[int]
Sets the type style used by the object. The options are:
plain
bold
italic
bold italic
Possible values:
0 = 'regular'
1 = 'bold'
2 = 'italic'
3 = 'bold italic'
fontname[symbol]
Sets the object's font.
fontsize[float]
Sets the object's font size (in points).
Possible values:
'8'
'9'
'10'
'11'
'12'
'13'
'14'
'16'
'18'
'20'
'24'
'30'
'36'
'48'
'64'
'72'
hint[symbol]
Sets the text that will be displayed in as a pop-up hint when the user moves the mouse over the object in a locked patcher.
ignoreclick[int]: 0
Toggles whether an object ignores mouse clicks in a locked patcher.
jspainterfile[symbol]
You can override the default appearance of a user interface object by assigning a JavaScript file with code for painting the object. The file must be in the search path.
patching_rect[4 floats]: 0. 0. 100. 0.
Sets the position and size of the object in the patcher window.
position[2 floats]
write-only
Sets the object's x and y position in both patching and presentation modes (if the object belongs to its patcher's presentation), leaving its size unchanged.
presentation[int]: 0
Sets whether an object belongs to the patcher's presentation.
presentation_rect[4 floats]: 0. 0. 0. 0.
Sets the x and y position and width and height of the object in the patcher's presentation, leaving its patching position unchanged.
rect[4 floats]
write-only
Sets the x and y position and width and height of the object in both patching and presentation modes (if the object belongs to its patcher's presentation).
size[2 floats]
write-only
Sets the object's width and height in both patching and presentation modes (if the object belongs to its patcher's presentation), leaving its position unchanged.
textcolor[4 floats]
Sets the color for the object's text in RGBA format.
textjustification[int]
Sets the justification for the object's text.
Possible values:
0 = 'left'
1 = 'center'
2 = 'right'
varname[symbol]
Sets the patcher's scripting name, which can be used to address the object by name in pattr, scripting messages to thispatcher, and the js object.
Messages
int
about
This is a script message (see above) used to modify standard menus, and is the first item to appear in a script. It takes the following arguments:
• Text of the first menu item (i.e. About My Program…).
On the Macintosh the About item appears as the first item in the application menu (Max menu). On Windows, it appears as the first item in the Help menu. The message apple may be used optionally for compatibility with older Macintosh versions of Max.
- text of first menu item
[list]
append
The append message adds an item to a menu previously defined in the menubar object's script with the menutitle message. The arguments are as follows:
• Menu number
• Item number
• Text of item
• metacharacters (optional, see item message for details)
If the menus for the object are currently showing, the item will be usable in the menu immediately. If it is not showing, the item will be included in the specified menu when the menus are showing next. After returing to the regular Max menus, any items added to the menubar object's menus with the append message will not be shown again (unless you send another append message), and are not saved in the object's script.
- menu number, item number, text
[list]
appendpermanent
The appendpermanent message adds an item to a menu previously defined in the menubar object's script with the menutitle message. The arguments are as follows:
• Menu number
• Item number
• Text of item
• metacharacters (optional, see item message for details)
If the menus for the object are currently showing, the item will be usable in the menu immediately. If it is not showing, the item will be included in the specified menu when the menus are showing next. Items will be shown for the lifetime of the menubar object are added to the object's script.
- menu number, item number, text
[list]
apple
This is a script message (see above) used to modify standard menus, and, when used, is the first item to appear in a script. It takes the following arguments:
• Text of the first menu item (i.e. About My Program…).
On the Macintosh the About item appears as the first item in the application menu (Max menu). On Windows, it appears as the first item in the Help menu. This message may be used optionally for compatibility with older Macintosh versions of Max.
- text of first menu item
[list]
checkitem
Followed by a menu number, an item number, and a code 0 or 1, checkitem puts a check before the specified item if the code is 1, otherwise it removes the check.
- checkitem
[list]
closeitem
This is a script message (see above) used to modify standard menus. The closeitem message takes an optional argument of 0 or 1. If "closeitem", "closeitem 1", or no message at all is entered in the script, the Close item will appear in the File menu for closing the active window. If "closeitem 0" is entered in the script, the Close item will be disabled in the File menu.
(mouse)
Double-clicking on the menubar object in a locked patcher will open a text editor window where you can insert a script to configure the menubar's appearance and behavior.
edit
This is a script message (see above) used to modify standard menus. It takes the following arguments:
• Item number to output
• Text of item to add to edit menu
The edit message inserts items into the standard Edit menu after the Clear item and before the Overdrive and Resume items (which are moved into the Edit menu when menubar is activated). A blank line separates the custom inserted items from the default items. Each item has a number associated with it which is sent out the third outlet of menubar when the item is chosen. The order in which your additional items appear in the Edit menu is determined by their order in the script, not by the (arbitrary) number associated with each item.
- item number, text
[list]
enableitem
Followed by a menu number, an item number, and a code 0 or 1, enableitem enables the specified item if the code is 1, otherwise it disables (and grays out) the item.
- menu-number, item-number, and enable/disable-flag (0 or 1)
[list]
end
This is a script message (see above) used to complete a script definition. This builds the menus and reports any errors encountered.
file
This is a script message (see above) used to modify standard menus. It takes the following arguments:
• Item number to output
• Text of item to add to file menu
The file message inserts items at the top of the standard File menu (before the Midi Setup... menu item). Each item has a number associated with it which is sent out the when the item is chosen. The order in which your additional items appear in the File menu is determined by their order in the script, not by the (arbitrary) number associated with each item.
- item number, text
[list]
item
This is a script message (see above) used to create new menus and menu items. It takes the following arguments:
• Menu number
• Item number
• Text of item
• metacharacters (optional)
The item message adds an item to an additional menu previously defined with a menutitle message. The order in which your items appear in the menu is determined by their order in the script, not by the (arbitrary) number associated with each item. The item number argument only specifies the number which is sent out the menubar object’s outlet when the user chooses this item. It’s a good idea to start your item numbers at 1 and list the items in the order you want them to appear in a menu.
Two characters can be used to modify the appearance of a menu item:
/ : followed by a character, assigns that character as a Command-key equivalent
(: disables the menu item
These special characters cannot appear as part of the actual item text. For example, the text On/Off will appear as Onff_O , not as On/Off .
- menu number, item number, text
[list]
markitem
This message is no longer supported.
- menu-number, item-number, and ASCII-code
[list]
newitem
This is a script message (see above) used to modify standard menus. It takes the following arguments:
• Item number to output.
The newitem message followed by a non-zero number directs Max to send the specified number out the menubar object’s File menu outlet when the user chooses the New command from the File menu, instead of opening a new patcher window. The message newitem 0 (or the absence of any newitem message) causes the New command to behave normally.
- menu item number
[int]
open
This is a script message (see above) used to modify standard menus. It takes the following arguments:
• Item number to output.
The open message followed by a non-zero number directs Max to send the specified number out the menubar object’s File menu outlet when the user chooses the Open... command from the File menu, instead of displaying the Open Document dialog box. The message open 0 (or the absence of any open message) causes the Open... command to behave normally.
- menu item number
[int]
saveas
This is a script message (see above) used to modify standard menus. It takes the following arguments:
• Item number to output.
The saveas message followed by a non-zero number directs Max to send the specified number out the menubar object’s File menu outlet when the user chooses Save or Save As... from the File menu, instead of performing the standard Save actions. The number sent out the outlet when Save is chosen will be 1 less than the number sent when Save As... is chosen. The message saveas 0 (or the absence of any saveas message) causes the Save and Save As... commands to behave normally.
- menu item number
[int]
See Also
| Name | Description |
|---|---|
| umenu | Pop-up menu |