thispatcher
Send messages to a patcher
Description
Allows modification of a patcher window with Max messages.
Discussion
thispatcher can be used to modify and/or close a patcher window - it sends a message to the patcher window in which it is contained.
See the bpatcher reference page for information on how to use the thispatcher object with bpatchers.
Note: Use of the thispatcher object to create new objects is not supported.
Arguments
None.
Attributes
Snapshot Attributes
autosave[int]
write-only
When the containing patcher is saved, the state of this object's snapshots will also be saved.
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.
adds the object to the background layer, 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]
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.
Messages
anything
See
and discussion.- message
[list]
end
Used internally.
savewindow
The word thispatcher will be saved as part of the patch the next time the patch is saved. The message means that changes to the window caused by messages to thispatcher will not be retained when the patch is saved; the prior patcher window settings are saved. If no message has been received, the patcher will be saved with a normal window appearance.
, followed by a non-zero number, means that any unusual window settings caused by messages to- flag
[int]
setactivetab
In a tabbed patcher, the active tab may be changed by passing the
message followed by the name of the subpatcher as displayed on the tab itself.- message
[list]
Snapshot Messages
snapshot
7.0.0
Create a snapshot. When
is on it will be saved into the current patcher. Otherwise it will be saved in an external file. You can determine the filename by an argument to this message.- file-name
[symbol]
restore
7.0.0
Restore a snapshot. When
is on, the snapshot that is embedded in the current patcher will be used. Otherwise it will be loaded from an external file. You can determine the filename by an argument to this message.- file-name
[symbol]
addsnapshot
Add a new snapshot. If there are no arguments, it will append the new snapshot to the current list of snapshots. If the first argument is a string containing a file path, Max will try to save a .maxsnap file to that location. If the first argument is a number, it will save the snapshot to that slot, incrementing subsequent slots. If the second argument is a string, it will set the name of the snapshot.
- userpath
[String]
- index
[Number]
- name
[String]
deletesnapshot
Delete a snapshot at the given index, decrementing subsequent slots.
- index
[Number]
exportsnapshot
Exports a snapshot from the given index, specified by the first argument. The second argument specifies the file name and path to export a maxsnap file to. If the second argument is empty, a File dialog box will open, allowing you to specify a file name and location.
- index
[Number]
- filename
[String]
importsnapshot
Imports a snapshot to the given index, specified by the first argument. The second argument specifies the file name and path to load a maxsnap file from. If the second argument is empty, a File dialog box will open, allowing you to choose a file.
- index
[Number]
- filename
[String]
setsnapshotname
Set the name of the snapshot at the given index.
- index
[Number]
- name
[String]
setembedsnapshot
Set the embed state of the snapshot at the index.
- index
[Number]
- embedstate
[Number]
movesnapshot
Change a snapshot's index.
- srcindex
[Number]
- dstindex
[Number]
Patcher Behavior and Display
The script message
The thispatcher permits dynamic control over object creation, deletion, sizing and positioning, and patching. The word is followed by a keyword that indicates a function. Following the keyword are arguments that specify what objects are to be affected by the message.
In the discussion of each message that follows, the syntax indicates required arguments for the message after the keyword in angle brackets. An example of each message is also provided.
A variable-name is a symbol that names either a new or existing object. You can set variable names by choosing Name... from the Object menu, or with certain scripting messages such as and .
Patcher Messages
anything
In addition to the patcher messages below, thispatcher will accept messages to control any of the attributes found in the patcher inspector by sending the attribute name followed by the appropriate value(s).
clean
The
message resets the patch's dirty bit in the window so that you won't be asked to save changes in the patch.dirty
The
message is the opposite of the method; it sets the patch's dirty bit in the window.dispose
*USE AT YOUR OWN RISK* - Closes the patcher or destroys the subpatcher that the thispatcher object is contained in.
front
The thispatcher object to the front. If the patcher is not open, the message opens the patch and brings it to the front.
message brings the window that contains theloadbang
The loadbang object itself.
message will send the message to all objects in the patch - including thelockdown
The
message will disable editing of the patcher.locked
The
message, followed by a 0 or 1, will lock or unlock the patcher.path
The thispatcher object out the right outlet of the thispatcher object.
If the patch is an abstraction, hosted by a bpatcher, in a poly~, etc, this message will report the topmost patcher's path, not the abstraction's path.
presentation
The
message, followed by a 0 or 1, will cause the patcher to enter or exit presentation mode.title
The
message, followed by a symbol, will change the title displayed in the patcher window.topmost
The
message, followed by a 0 or 1, will set whether or not the patcher window is always on top. An argument of 1 causes the window to always be on top. Please note that the message will only work after the patcher has been made visible at least once.write
When sent to a patcher that is not saved to disk, the
message opens a standard File Dialog window where the user can manually set a file name and a location to save the file. If the patcher is already saved to disk, the message resaves the file to the same location, with the same name.Scripting Messages
bringtofront
Bring an object to the front of the layer it's currently in.
Syntax:
Example:
If is in the foreground layer, this message moves it to the front of the foreground layer. Otherwise it moves it to the front of the background layer.
class
Assigns a variable name to the first instance of a specified class with matching arguments
Syntax:
Example:
Assigns the name to the first instance found of + with argument in the patcher.
connect
Connects two objects together with a patch cord
Syntax:
Example:
Connects the left outlet of the object with the variable name to the left inlet of the object with the variable name .
Note: Adding the keyword (e.g., creates hidden connections.
connectcolor
Modify the color of an existing patch cord, setting it to one of Max's 16 standard colors.
Syntax:
Example:
Changes the color of the connection between the left outlet of the object with the 3rd inlet of the object to the color stored at index 12.
delete
Deletes an object in a patcher window.
Syntax:
Example:
Deletes the object associated with the variable name .
disconnect
Disconnect two objects connected by a patch cord
Syntax:
Example:
This message undoes the connection between the left outlet of and the left of bobo.
hide
Hide a visible object.
Syntax:
Example:
Hides the object named
ignoreclick
Set an object not to respond to mouse clicks.
Syntax:
Example:
Makes the object named ignore mouse clicks.
move
Move an object to an absolute position relative to the current top-left corner of a patcher window. Note that the 0,0 point is underneath the icon bar.
Syntax:
Example:
Moves the object named to the left edge of the window, 100 pixels down from the top.
new
Creates a new object in a patcher window and gives it a name.
Syntax:
Example:
Creates a new toggle object 15 pixels square at 101 93 and assign it to the variable footog.
The format of the arguments (after the class name) to the message are based on the legacy Max file format.
newdefault
Creates a new named object with default properties in a patcher window.
Syntax:
Example:
Creates a new filtergraph~ object at its default size at 10 10 and assign it to the variable thatgraph.
Example:
Creates a new pack object instantiated with the arguments foo bar bap at 200 100 and assign it to the variable buffy.
nth
Assigns a variable name to the nth instance of a specified class
Syntax:
Example:
Assigns the name to the first toggle found in the patcher.
The order of objects in a patcher is determined by the front-to-back ordering. Objects in back of the patcher that draw behind other objects are first in the search order.
offset
Move an object a distance from its current position. Positive distances move the object down and to the right, negative distances move it up and to the left.
Syntax:
Example:
Moves the object named 30 pixels to the right and 40 pixels up.
offsetfrom
Move an object a set distance from another object.
Syntax:
The top-left-flag is 1 if the distance is relative to the top-left corner of the object, and 0 if it is relative to the bottom-right corner.
Example:
Moves the object named 100 pixels to the left of the left side of the object named , and 120 pixels above the top of the object named .
respondtoclick
Set an object to respond to mouse clicks.
Syntax:
Example:
Makes the object named respond to mouse clicks.
selected
Assigns a variable name to the first object found that is selected
Syntax:
Example:
Assigns the name to the first object found that is selected. Obviously this message only works when the patcher is unlocked, since no object can be selected in a locked patcher.
For all three connection messages described below, inlets and outlets are specified by , with 0 denoting the leftmost inlet or outlet. The first variable specified is the object whose outlet you are connecting or disconnecting and the second variable is the one whose inlet you are connecting. Messages can then flow from outlet to inlet.
send
Send a message to an object. This message is the same as using a message box with a semicolon or a send object, but you use the object variable name feature of scripting to specify the object that will receive the message -- using to communicate with a named receive object does not work. The message can only be sent to an object within the patcher as the thispatcher object receiving the message.
Syntax:
Example:
The object with the variable name receives an message. If were a number box, its displayed value would change to 666.
sendbox
Send a message to an object box. This message is identical to send except that it sends the message to an object's box rather than the object referred to by the box. There is currently only one object, bpatcher, in which the object and box are different objects. The box is a bpatcher, and the object is a patcher. What can you tell a bpatcher to do? One example is the message. Peek inside the bpatcher Inspector for other ideas.
Syntax:
Example:
If names a bpatcher object, this message would tell it not to draw its border.
sendtoback
Move an object to the back of the layer it's currently in.
Syntax:
Example:
If is in the foreground layer, this message moves it to the back of the foreground layer. Otherwise it moves it to the back of the background layer. Note that objects that are "in the back" are the first objects to be found by the variable assignment messages and .
show
Show a hidden object.
Syntax:
Example:
Makes the object named visible.
size
Change an object's size. There are some objects that have restrictions on their size, but they generally do not protect themselves against sizes they don't expect, so use this message with some caution. For instance the toggle object expects to be a square. It may not draw properly if it's made into a rectangle.
Syntax:
Example:
Changes the object named to be 30 by 30 pixels.
Sending Messages to Objects
Output
symbol
Out right outlet: The full pathname of the folder or volume containing the patcher's file in response to the
message. If the patcher has not been saved, there is no output.window
Out left outlet: When the message thispatcher sends out the words followed by the screen coordinates (in pixels from the top left corner of the screen) of the left, top, right, and bottom limits of the window. When the message is received, the message or is sent out, depending on whether the window has a title bar. When the message is received, thispatcher sends out the words followed by the visibility of the scroll bars and grow box ( or ), the close box ( or ), and the zoom box ( or ).
is received,See Also
Name | Description |
---|---|
bpatcher | Embed a subpatch with a visible UI |
bgcolor | Set background color |
join | Combine items into a list |
pack | Create a list |
patcher | Create a subpatch within a patch |
pattrforward | Send any message to a named object |
pcontrol | Open and close subwindows |
pvar | Connect to a named object in a patcher |
sprintf | Format a message of words and numbers |