A newer version of Max is available. Click here to access the latest version of this document.

umenu

Pop-up menu, to display and send commands

Description

umenu can be used to display text associated with incoming numbers. Items start at 0.

Arguments

None.

Messages

bang Sends out the currently displayed menu item.
int item-index [int]
The number specifies a menu item to be sent out, and causes umenu to display that item. The items are numbered starting at 0. A menu item can also be chosen from a umenu with the mouse, as with any pop-up menu.
float item-index [float]
Converted to int.
(drag) When a file folder is dragged from the Max 5 File Browser to a umenu object, the folder's contents will be loaded into as menu choices.

When a file folder is dragged from the Max 5 File Browser to a blank space in an unlocked patcher window, a umenu object containing the folder's contents loaded will be created.
append message [list]
The word append, followed by any message, appends that message as the new last item in the menu.
checkitem item-index [int]
toggle (0 or 1) [int]
The word checkitem, followed by an item number and 1 or 0, places (1) or removes (0) a check mark next to the item number.
clear Removes all items from the umenu.
delete item-index [list]
The word delete, followed by one or more numbers that correspond to items in the list, deletes the item or items from the umenu.
clearchecks The word clearchecks removes check marks for all items.
count Sends the number of items in the umenu out the right outlet, preceded by the word count.
enableitem item number [int]
enable state (0 or 1) [int]
The word enableitem, followed by a number that specifies a menu item and a 1 or 0, enables or disables the specified item number. Disabled menu items cannot be selected, but their text and item number are sent from the rightmost outlet if the mouse is released while above them, prefixed by the symbols disabled_eval and disabled_item, respectively.
gettoggle Reports the current value of the umenu object's toggle state (1 or 0, for on or off), from the right outlet, preceded by the word toggle.
insert index and data [list]
The word insert, followed by a number and a message, inserts the message at the address specified by the number, incrementing all equal or greater addresses by 1 if necessary.
mode display-flag (1 2 or 3) [int]
The word mode, followed by a number in the range 0-3, sets the appearance and behavior of the umenu object. The normal pop-up menu style is 0 (the default). Scrolling mode (2) lets you scroll through the individual menu items by dragging the mouse up or down, displaying one item at a time. Label mode (2) shows the text of the selected menu item with no border around it, and does not respond to the mouse. Toggle mode (3) sets a button style. Clicking on the object in mode 3 causes it to alternate between an active and inactive state. When changing from inactive to active, the object sends the message toggle 1 from its rightmost outlet, and changes to the color set using the togcolor attribute. When changing from active to inactive, the object sends the message toggle 0 from its rightmost outlet, and changes to the color set using the bgcolor attribute. Whether activating or deactivating, the object also sends its current message from the middle outlet and its current item number from the left outlet.
(mouse) Clicking with the mouse lets you select a menu item to be sent out, and causes umenu to display that item.
next Selects the next menu item and causes the umenu object to display that item. This message will ignore disabled or separator menu items.
populate If the umenu object has a valid folder path as its prefix, the populate message will cause the menu to re-populate its items list, based on the current contents of the specified path (and filtered by the types list). After population is complete, the number of items added to the umenu object will be output from the right outlet, preceded by the word populate.
prev Selects the previous menu item and causes the umenu object to display that item. This message will ignore disabled or separator menu items.
set display-item [list]
The word set, followed by a number or symbol, specifies a menu item to be displayed by umenu, but does not send it out the outlet. If the set argument is a symbol, set searches for a menu item which begins with the symbol.
setcheck character (0 through 255) [int]
(Macintosh only) The word setcheck, followed by a number that specifies the decimal representation of a UTF-8 character (e.g. 8226 for a bullet or 62 for a greater than symbol), sets the character used to be the check mark. The word setcheck with no argument specifies the default square root checkbox.
setitem item-index and message [list]
The word setitem, followed by an item number and any message, sets the specified menu item to that message.
setsymbol menu item [symbol]
The word setsymbol, followed by a message, specifies a menu item to be displayed by name without triggering any output.
setrgb RGB-list (0 through 255) [list]
The word setrgb, followed by six numbers between 0 and 255 that specify RGB values, uses the first three numbers to set the foreground (text) color and the second three numbers to set the background (fill) color.
settoggle toggle state (0 or 1) [int]
The word settoggle, followed by a one or zero, sets the umenu object to the specified state if it is in toggle mode and performs output as if the object were clicked on (the symbol toggle, followed by a zero or one, indicating the toggle state). Without an argument, the message simply toggles the object's state and triggers output.
showchecked This message operates as follows. If the currently displayed item is checked, do nothing. Otherwise, starting at the first item in the menu, find one that is checked and set the menu to display that item. If there isn't one, do nothing.
symbol item [symbol]
Identical to the set message with a symbol argument, except that the found item number is sent out (and the text of the item is sent out the right outlet, if the Evaluate Item Text feature is enabled).
toggle toggle state (0 or 1) [int]
The word toggle, followed by a one or zero, sets the umenu object to the specified state if it is in toggle mode and performs output as if the object were clicked on (the symbol toggle, followed by a zero or one, indicating the toggle state). Without an argument, the message simply toggles the object's state and triggers output.

Attributes

Name Type g/s Description
align int
def.:0
Sets the text alignment mode. Alignment modes are:
0 left (the default)
1 center (1)
2 right alignment (2)
arrow int Toggles the drawing of the arrow and frame on the right-hand side of the umenu object.
arrowbgcolor float Sets the color of the umenu object's arrow frame in RGBA format.
arrowcolor float Sets the color of the umenu object's up/down arrows in RGBA format.
arrowframe int Toggles the drawing of the frame on the right-hand side of the umenu object.
arrowlink int Toggles linking the colors used in the background and the arrow frame. When set to 1 (the default) the same background color will be used as the arrow and frame. When set to 0, the arrow background color is used.
autopopulate int
def.:0
Toggles the automatic population of an umenu object with folder contents (default = 0). The automatic population will occur when it receives a valid folder path as the argument to a prefix message, or at patcher load, if a valid prefix is stored with the object. See the prefix, populate, and types message descriptions for more information.
bgcolor float Sets the background color of the umenu object object in RGBA format.
bgcolor2 float Sets the pop-up background color of the umenu object object in RGBA format.
depth int
def.:0
Sets the folder recursion depth used by the umenu object when populating from a valid file path.
discolor float Sets the disabled text color of the umenu object object’s menu item in RGBA format.
framecolor float Sets the frame color (i.e., the “lit” part of a 3D menu item) of the umenu object object’s menu item in RGBA format.
hltcolor float Sets the highlight color of the umenu object object’s menu item in RGBA format.
items atom The items attribute, which is only accessible using the umenu object's Inspector, lets you enter the items which you want to appear on the menu by typing into a dialog box. Menu items are separated by by commas (e.g., red, orange, yellow, green).
labelclick int
def.:0
Toggles Label Click mode on or off. In this mode, when the object is in Label mode, you can click in the object's rectangle and the current value of the menu is sent out the left outlet. In addition, the text of the current item is shown underlined.
menumode int
def.:0
Sets the appearance and behavior of the umenu object. The modes are:

0: Normal mode - the normal pop-up menu (default).
1: Scrolling mode - lets you scroll through the individual menu items by dragging the mouse up or down, displaying one item at a time.
2: Label mode - shows the text of the selected menu item with no border around it, and does not respond to the mouse.
3: Toggle mode - Clicking on the object in mode 3 causes it to alternate between an active and inactive state. When changing from inactive to active, the object sends the message toggle 1 from its rightmost outlet, and changes to the color set using the togcolor attribute. When changing from active to inactive, the object sends the message toggle 0 from its rightmost outlet, and changes to the color set using the bgcolor attribute. Whether activating or deactivating, the object also sends its current message from the middle outlet and its current item number from the left outlet.
Control-clicking allows you to change the current state of a umenu object in toggle mode.
pattrmode int
def.:0
Sets the method used by the umenu object object to report its internal state to the pattr object. When the argument is 0 (default), the umenu object reports its internal state by number (e.g. item 3 of the list of items). When the argument is 1, the umenu object reports its internal state by symbol (e.g. item 'carrots' of the list of items).
prefix symbol
def.:
Sets a menu-wide prefix, which can be concatenated or prepended to all menu item text before output. If the prefix is a valid folder path, the populate and types messages can be used to automatically fill the umenu object with a list of files in the folder. See the entries for those messages for more information. Sending a prefix message without any argument clears the currently stored prefix.
prefix_mode int
def.:0
Sets the output behavior of the prefix mode. The modes are:

0: concatenate mode; the prefix is added to the front of the outgoing message without a space.
1: prepend mode; the prefix is added to the front of the outgoing message list as a discrete symbol.
2: ignore mode; the prefix is not used for output.
rounded int
def.:8
Sets the radius, in pixels for the umenu object.
showdotfiles int
def.:0
Toggles the display of files whose names begin with a dot (.). The default is off.
textcolor float Sets the text color of the umenu object object in RGBA format.
textcolor2 float Sets the pop-up text color of the umenu object object in RGBA format.
togcolor float Sets the toggle color of the umenu object’s menu item in RGBA format.
truncate int
def.:1
Toggles the location of the truncation of text in the umenu object when the text is too long. The default is 1 (truncate the end of the text on the right-hand side). A value of 2 will cause the text to truncate in the middle in the same manner as the textbutton object.
types symbol Sets a file type filter for use by the populate message. Up to 64 file types may be entered as a list. By default, no file types are filtered.
underline int
def.:0
Toggles the underlining of text in the umenu object. The default is 0 (no underlining).

Information for box attributes common to all objects

Menu Items

Name Description
Color Choosing the Color... menu item from the Object menu when the object is selected opens a color picker, permitting adjustment to the appearance of the umenu object.

Output

anything: Out middle outlet: The text of the selected menu item is sent out as a message.

Out right outlet: The count, gettoggle, and populate, messages will cause status messages to be sent out the right outlet.
int: Out left outlet: The number of the selected menu item is sent out. Menu items are numbered beginning with 0.

Examples

Used to send commands ...or to display text associated with numbers received

See Also

Name Description
coll Store and edit a collection of different messages
fontlist List system fonts
Max Basic Tutorial 13: Movie Sequencing Max Basic Tutorial 13: Movie Sequencing