Package Max

patcher

Create a subpatch within a patch

Description

Creates patches within patches.

Discussion

Take a patch contained within a single patcher window, place it within a patcher object, add inlet s and outlet s, and you can instantiate it as an object (or many copies of that object) capable of its own messaging, embedded within a larger patch.

The number of inlets in a patcher object is determined by the number of inlet objects contained within its subpatch window. The messaging which the patcher object can handle depends upon the patch you embed within it. Double-clicking on a patcher object with the mouse opens the subpatcher in a new window.

Arguments

subpatch[symbol]
optional

The subpatch can be given a name by the argument, so that its name appears in the title bar of the subpatch window. The name in the title bar of the subpatch window is displayed in brackets to indicate that it is part of another file. If there is no argument typed in, the subpatch window is named [sub patch]. Different patcher objects that share the same name are still distinct subpatches, and do not share the same contents.

Attributes

accentcolor[4 floats]

Sets the default accented background color for objects.

assistshowspatchername[int]: 0

If set to 0 (default) and an inlet or outlet object in the subpatcher has a comment, the patcher name is not shown. If there is no comment, it is shown. If the attribute is set to 1, the patcher name is always shown whether or not the inlet / outlet object has a comment.

bgcolor[4 floats]

Sets the default background color for objects.

bgfillcolor[4 floats]

Sets the default gradient fill for objects.

bottomtoolbarpinned[int]: 0

Controls the display of the bottom toolbar when a file is opened. If set to "last saved", the toolbar will be shown only if it was visible when the patcher was saved. If set to "pin", the bottom toolbar will always be visible. If set to "unpin" the toolbar will always be invisible until the cursor moves over the bottom edge of the window. Possible values:

0 = 'last saved' ( Last saved )
The bottom toolbar will be shown only if it was visible when the patcher was saved.

1 = 'pin' ( Pinned visible )
The bottom toolbar will always be visible.

2 = 'unpin' ( Unpinned )
The bottom toolbar will always be invisible until the cursor moves over the bottom edge of the window.

boxanimatetime[int32]: 200

Sets the time, in milliseconds, used for animation of object behavior in the patcher window.

bubble_bgcolor[4 floats]

Bubble Background Color

bubble_outlinecolor[4 floats]

Bubble Outline Color

clearcolor[4 floats]

Sets the default background color for comment objects.

cluebar[int]: 0

Show Clue Bar on Open Possible values:

0 = 'Current Preference'
1 = 'Yes'
2 = 'No'

color[4 floats]

Sets the default foreground color for objects.

defaultfocusbox[symbol]

The scripting name of the object that will receive keyboard focus when the patcher is first opened.

description[symbol]:

Sets a searchable description used by the database and documentation system.

digest[symbol]:

Sets a searchable short description used by the database and documentation system.

editing_bgcolor[4 floats]

Sets the patcher background color when the patcher is unlocked.

elementcolor[4 floats]

Sets the default border color for objects.

enablehscroll[int]: 1

If enabled, the horizontal scrollbar will appear when the patcher’s content width exceeds its window width.

enabletransparentbgwithtitlebar[int]

When set to 1, this enables patchers with locked and unlocked backgrounds set to 0% opacity to become fully transparent. Please note that you must change the opacity setting for the Locked Patcher Background Color, locked_bgcolor, and Unlocked Patcher Background Color, editing_bgcolor.

enablevscroll[int]: 1

If enabled, the vertical scrollbar will appear when the patcher’s content height exceeds its window height.

filepath[symbol]
read-only

The patcher’s complete file location if saved (read-only).

fontface[int32]

The default font style used for new text objects. Possible values:

0 = 'regular' ( Regular font )
Regular font

1 = 'bold' ( Bold font )
Bold font

2 = 'italic' ( Italic font )
Italic font

3 = 'bold italic' ( Bold and italic font )
Bold and italic font

fontname[symbol]

Sets the default font used for new text objects.

fontsize[float]

Sets the default font size used for new text objects. Possible values:

'8'
'9'
'10'
'11'
'12'
'13'
'14'
'16'
'18'
'20'
'24'
'30'
'36'
'48'
'64'
'72'

globalpatchername[symbol]

Sets the global name by which this patcher can be referred to by pattr objects (for more information, see the pattrmarker object).

gridonopen[int]: 0

If enabled, a grid will be displayed in the unlocked patcher background when the patcher is opened.

gridsize[2 floats]

Sets the X and Y size of the grid in pixels.

gridsnaponopen[int]: 0

If enabled, "Snap to Grid" will be on when the patcher is opened.

helpsidebarclosed[int]

If enabled, keep the sidebar closed when opening the help patcher. If the help patcher is tabbed then this must be applied to the root patcher of the help file.

integercoordinates[int]

Snap to Pixel

isolateaudio[int]

If enabled, starting or stopping audio in this patcher will not affect the audio in other patcher windows.

lefttoolbarpinned[int]: 0

Controls the display of the left toolbar when a file is opened. If set to "last saved", the toolbar will be shown only if it was visible when the patcher was saved. If set to "pin", the left toolbar will always be visible. If set to "unpin" the toolbar will be invisible until the cursor moves over the left edge of the window. Possible values:

0 = 'last saved'
1 = 'pin'
2 = 'unpin'

locked_bgcolor[4 floats]

Sets the patcher background color when the patcher is locked.

objectsnaponopen[int]: 1

If enabled, "Snap to Objects" will be on when the patcher is opened

openinpresentation[int]: 0

If enabled, the patcher opens in presentation mode.

openrect[4 floats]

Sets the initial window position (horizontal offset/vertical offset/width/height) for the patcher window. If non-zero, changes to the patcher window's size or position will not be reflected when the file is saved.

oscparamenableddefault[int]: 0

Enable / disable OSC for parameters by default. Possible values:

0 = 'App Default'
Apply the setting in the global Max preferences.

1 = 'Enabled'
Enable OSC for parameters by default.

2 = 'Disabled'
Disable OSC for parameters by default.

oscprefix[symbol]:

Prefix to prepend to all OSC addresses generated by Max. Can be overridden by changing the value in the patcher inspector.

oscprefixmode[int]: 0

The type of prefix to prepend to OSC addresses generated by Max. Possible values:

0 = 'App Default'
Apply the setting in the global Max preferences.

1 = 'None'
Do not add any OSC prefix to addresses generated by Max.

2 = 'Patcher Name'
Prepend the name of the patcher to OSC addresses generated by Max.

3 = 'Custom'
Prepend a custom prefix to OSC addresses generated by Max.

oscqueryenable[int]: 0

Enable/Disable OSCQuery for this Patch. Possible values:

0 = 'App Default'
Apply the setting in the global Max preferences.

1 = 'Off'
Disable OSCQuery for this patch.

oscreceivemode[int]: 0

Select whether and how this patcher should respond to incoming OSC packets. Possible values:

0 = 'App Default'
Apply the setting in the global Max preferences.

1 = 'Off'
Disable the ability to control this patcher remotely by OSC.

2 = 'UDP With Global Port'
Enable the ability to control this patcher by sending OSC over UDP to the port set in the global Max preferences.

3 = 'UDP With Custom Port'
Enable the ability to control this patcher by sending OSC over UDP to a custom port.

oscreceiveudpport[int]: 30338

The default UDP port this patcher will listen to for incoming OSC packets.

oscsendmode[int]: 0

Select whether and how this patcher should send OSC data. Possible values:

0 = 'App Default'
Apply the setting in the global Max preferences.

1 = 'Off'
Disable sending OSC data from this patcher.

2 = 'UDP With Global Destination'
Enable this patcher to send OSC data over UDP using the address and port set in the global Max preferences.

3 = 'UDP With Custom Destination'
Enable this patcher to send OSC data over UDP using a custom address and port.

oscsendudpaddr[symbol]: 127.0.0.1

The UDP address that this patcher will send outgoing OSC packets to.

oscsendudpport[int]: 30337

The UDP port that this patcher will send outgoing OSC packets to.

oscuseparamprefix[int]: 0

Prepend /param to OSC addresses that describe parameters. Possible values:

0 = 'App Default'
Apply the setting in the global Max preferences.

1 = 'Yes'
Do prepend /param to OSC addresses that describe parameters.

2 = 'No'
Do not prepend /param to OSC addresses that describe parameters.

oscvaluemode[int]: 0

Select the type of value(s) Max should send. Possible values:

0 = 'App Default'
Apply the setting in the global Max preferences.

1 = 'Raw Only'
Send only the raw (scaled) value.

2 = 'Raw With Suffix'
Send only the raw (scaled) value and append a /raw suffix to the OSC address.

3 = 'Normalized Only'
Send only the normalized [0,1] value if available.

4 = 'Normalized With Suffix'
Send only the normalized [0,1] value if available and append a /normalized suffix to the OSC address.

5 = 'Raw & Normalized'
Send both the raw (scaled) and normalized [0,1] values. /raw and /normalized suffixes will be automatically appended to distinguish them.

patchlinecolor[4 floats]

Sets the default color for patch cords.

righttoolbarpinned[int]: 0

Controls the display of the right toolbar when a file is opened. If set to "last saved", the toolbar will be shown only if it was visible when the patcher was saved. If set to "pin", the right toolbar will always be visible. If set to "unpin" the toolbar will be invisible until the cursor moves over the right edge of the window. Possible values:

0 = 'last saved'
1 = 'pin'
2 = 'unpin'

selectioncolor[4 floats]

Sets the default selection color for objects.

showontab[atom]

If set to 1 (parent), the patcher’s title will appear as a tab in its parent patcher. If set to 2 (top-level), the patcher's title will appear as a tab of the top-level patcher. In a top-level patcher this attribute is ignored. Possible values:

0 = 'none'
1 = 'parent'
2 = 'top-level'

stripecolor[4 floats]

Sets the default background color for objects that display lists.

style[symbol]:

Sets the style to be applied to the patcher. Styles can be defined and edited using the Format Palette.

subpatcher_template[symbol]:

Sets the template used when creating an embedded subpatcher with the patcher object or when a patcher is created using the Encapsulate feature. Only the toolbar, style, and editing settings are used by the template; objects are not added to the subpatcher. Possible values:

'<none>'
'Cardinal'
'Chesterfield'
'Default Max 7'
'Generalissimo'
'GreenScreen'
'IceCubeTray'
'MP-Rnbo'
'MaxScore Combo'
'TheSands'
'audiostart'
'bigpatcher'
'kiwi'
'mute_bottom_toolbar'
'opengl_starter'

syntax_attrargcolor[4 floats]

Syntax Attribute Argument Color

syntax_attributecolor[4 floats]

Syntax Attribute Name Color

syntax_objargcolor[4 floats]

Syntax Object Argument Color

syntax_objectcolor[4 floats]

Syntax Object Name Color

tags[symbol]:

Sets searchable tags (separated by spaces) used by the database.

tallnewobj[int]: 0

If enabled, the default object box is slightly taller to make its text easier to read.

textcolor[4 floats]

Sets the default text color for comment objects.

textcolor_inverse[4 floats]

Sets the default text color for objects.

textjustification[int]

Sets the default text justification used for new text objects. Possible values:

0 = 'left'
1 = 'center'
2 = 'right'

title[symbol]

Sets the name shown in the patcher’s title bar.

toolbarvisible[int]: 1

If enabled, the toolbars will be shown when the patcher is opened.

toptoolbarpinned[int]: 0

Controls the display of the top toolbar when a file is opened. If set to "last saved", the toolbar will be shown only if it was visible when the patcher was saved. If set to "pin", the top toolbar will always be visible. If set to "unpin" the toolbar will be invisible until the cursor moves over the top edge of the window. Possible values:

0 = 'last saved'
1 = 'pin'
2 = 'unpin'

workspacedisabled[int]

If enabled, the patcher will not be re-opened when relaunching if it was open when last quitting Max.

is_mpe[int]

Patch supports MPE (Max for Live)

latency[int]

Defined Latency (Max for Live)

minimum_live_version[symbol]

Minimum required Live version (Max for Live)

minimum_max_version[symbol]

Minimum required Max version (Max for Live)

platform_compatibility[long]

Platform Compatibility (Max for Live) Possible values:

0 = 'All'
1 = 'Mac Only'
2 = 'Windows Only'

Common Box Attributes

Below is a list of attributes shared by all objects. If you want to change one of these attributes for an object based on the object box, you need to place the word sendbox in front of the attribute name, or use the object's Inspector.

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'

hidden[int]: 0

Toggles whether an object is hidden when the patcher is locked.

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]

JS Painter File

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.

Output

anything

The number of outlets a patcher object has is determined by the number of outlet objects contained within the subpatch window. Output can also be sent via send and value objects contained in the subpatch. The actual messages sent out of a patcher object depend on the contents of the subpatch.

When a patcher object is first created, the subpatch window is automatically opened for editing. To view or edit the contents of a patcher object (or any subpatch object) later on, double-click on the object when the patcher window is locked.

All the objects in a subpatch of a patcher object are saved as part of the patcher which contains the object.

See Also

Name Description
bpatcher Embed a subpatch with a visible UI
inlet Receive messages from outside a patcher
outlet Send messages out of a patcher
pcontrol Open and close subwindows
thispatcher Send messages to a patcher