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

patcher

Create a subpatch within a patch

Description

Creates patches within patches.

Examples

A patch can be contained (and saved) as part of another patch

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]

Object Accent Color

bgcolor [4 floats]

Sets the background color in RGBA format.

bgfillcolor [4 floats]

Sets the object background gradient color in RGBA format.

bottomtoolbarpinned [int]

Controls the display of the bottom toolbar when a file is opened.

Possible values:

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

boxanimatetime [int32]

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

clearcolor [4 floats]

Comment Background Color

color [4 floats]

Sets the object color in RGBA format.

defaultfocusbox [symbol]

Sets the patcher window to get the focus by default.

description [symbol]

Description

digest [symbol]

Digest

editing_bgcolor [4 floats]

Sets the background color displayed when the window is being edited in RGBA format.

elementcolor [4 floats]

Sets the object element color in RGBA format.

enablehscroll [int]

Toggles horizontal scrollbar display in a patcher window.

enablevscroll [int]

Toggles vertical scrollbar display in a patcher window.

filepath [symbol]

g/s(get)

Sets the file path for the patcher window.

fontface [int32]

Sets the default font style used in the patcher.

Possible values:

0 = 'regular'
1 = 'bold'
2 = 'italic'
3 = 'bold italic'

fontname [symbol]

Sets the default font used in the patcher.

fontsize [float]

Sets the default font size used in the patcher.

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]

Toggles displaying the grid in the patcher window when unlocked.

gridsize [2 floats]

Sets the grid size in pixels.

gridsnaponopen [int]

Toggles automatically setting the "Snap To Grid" option when the patcher is unlocked.

isolateaudio [int]

Toggles local stop/start of audio in the patcher.

lefttoolbarpinned [int]

Controls the display of the left toolbar when a file is opened.

Possible values:

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

locked_bgcolor [4 floats]

Sets the background color in RGBA format used when the patch is locked.

objectsnaponopen [int]

Toggles snapping to objects for alignment automatically.

openinpresentation [int]

Toggles opening the patcher in Presentation mode automatically.

openrect [4 floats]

Sets the fixed initial window position (horizontal offset/vertical offset/width/height) for the patcher window.

patchlinecolor [4 floats]

Sets the patchcord color in RGBA format.

righttoolbarpinned [int]

Controls the display of the right toolbar when a file is opened.

Possible values:

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

selectioncolor [4 floats]

Sets the object selection color in RGBA format.

showontab [symbol]

Used for creating help files.

style [symbol]

Sets the style to be applied to the patcher. Styles can be set using the Format palette.

subpatcher_template [symbol]

Names the template used when creating an embedded subpatcher with the patcher object or when a patcher created when you use the Encapsulate feature. Any objects in the template file are not added to the subpatcher, only the toolbar, style, and editing settings.

Possible values:

'<none>'
'Cardinal'
'Chesterfield'
'Default Max 7'
'Generalissimo'
'GreenScreen'
'IceCubeTray'
'TheSands'
'audiostart'
'bigpatcher'
'kiwi'
'opengl_starter'

tags [symbol]

Allows the inclusions of metatags associated with the patcher file.

tallnewobj [int] (default: 0)

Toggles use of tall object boxes.

textcolor [4 floats]

Sets the comment text color in RGBA format.

textcolor_inverse [4 floats]

Sets the object text color in RGBA format.

textjustification [int]

Sets the default text justification.

Possible values:

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

title [symbol]

Sets the title which appears in the patcher window.

toolbarvisible [int]

Toggles showing the toolbar when the patcher is opened.

toptoolbarpinned [int]

Controls the display of the top toolbar when a file is opened.

Possible values:

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

workspacedisabled [int]

Toggles reopening the patcher when Max launches if its window is visible when you quit.

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] (default: 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] (default: 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] (default: 0)

Toggles whether an object ignores mouse clicks in a locked patcher.

patching_rect [4 floats] (default: 0. 0. 100. 0.)

Sets the position and size of the object in the patcher window.

position [2 floats]

g/s(set)

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] (default: 0)

Sets whether an object belongs to the patcher's presentation.

presentation_rect [4 floats] (default: 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]

g/s(set)

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]

g/s(set)

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 [float]

Sets the color for the object's text in RGBA format.

textjustification [int]

Text Justification

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
Sharing Max Patchers Sharing Max Patchers
Search Paths Search Paths
Scripting Scripting
Organizing Your Patch Organizing Your Patch
Configuring Objects In A Patcher Configuring Objects In A Patcher
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
Max Basic Tutorial 14: Encapsulation Max Basic Tutorial 14: Encapsulation
Max pattr Tutorial 1: Patcher Storage Max pattr Tutorial 1: Patcher Storage