patcher
Description
Creates patches within patches.
Examples
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]
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]
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]
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]
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.
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]
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]
If enabled, the vertical scrollbar will appear when the patcher’s content height exceeds its window height.
filepath [symbol]
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]
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]
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]
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]
If enabled, "Snap to Objects" will be on when the patcher is opened
openinpresentation [int]
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.
patchlinecolor [4 floats]
Sets the default color for patch cords.
righttoolbarpinned [int]
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] (default: )
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'
'TheSands'
'audiostart'
'bigpatcher'
'kiwi'
'opengl_starter'
tags [symbol]
Sets searchable tags (separated by spaces) used by the database.
tallnewobj [int] (default: 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]
If enabled, the toolbars will be shown when the patcher is opened.
toptoolbarpinned [int]
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.
external_mpe_tuning_enabled [int]
If enabled, Live will send tuned MPE data to the device, using per-note pitch bend messages to play in tune with the currently selected tuning system in Live. Only has an effect if the is_mpe attribute is set to 1. (The alternative approach to using Live tunings is to use Live's TuningSystem API. See the bundled Global.TuningSystem snippet for an example.)
is_mpe [int]
If enabled, a Max for Live device will receive MPE data from Live.
latency [int]
Defined Latency
minimum_live_version [symbol]
Minimum Live version required by this Max for Live device.
minimum_max_version [symbol]
Minimum Max version required by this Max for Live device.
platform_compatibility [long]
Platform compatibility of the device.
Possible values:
0 = 'All'
1 = 'Mac Only'
2 = 'Windows Only'
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.
jspainterfile [symbol]
JS Painter File
patching_rect [4 floats] (default: 0. 0. 100. 0.)
Sets the position and size of the object in the patcher window.
position [2 floats]
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]
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]
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 |
|---|---|
| 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 |