bpatcher
Embed a subpatch with a visible UI
Description
The bpatcher object holds the contents of a patcher or subpatcher, displaying only those visual elements that fall within its box rectangle. The number of inlets and outlets in a bpatcher object is determined by the number of inlet and outlet objects contained in its contained subpatcher.
Discussion
The inlet to the bpatcher object is used for sending messages to its contained patcher, not for sending messages to or setting attributes on the bpatcher object itself. Setting an attribute or sending a message to the bpatcher object must be done via scripting messages to the thispatcher object. See the replace message for an example.
Arguments
None.
Attributes
args[256 atoms]:
The args attribute lets you set arguments passed to your patcher that will be saved with the bpatcher in its parent patcher. Arguments can replace #1 - #9 in the contained patcher and/or parsed by the patcherargs object.
bgcolor[4 floats]: 1. 1. 1. 1.
Sets the background color of the patcher visible in the bpatcher window.
bgmode[int]: 0
border[int]: 0
When enabled, the border attribute draws a one pixel black border around the object's box
clickthrough[int]: 0
embed[int]: 0
When enabled, embed will save the contained patcher in its parent patcher. When disabled (the default), the contained patcher is loaded from a file specified by the name attribute.
enablehscroll[int]: 0
Enables a horizontal scrollbar for scrolling the contents of the contained patcher
enablevscroll[int]: 0
Enables a vertical scrollbar for scrolling the contents of the contained patcher
lockeddragscroll[int]: 0
Determines whether you can scroll the contents of the bpatcher by holding down the shift and command (control on Windows) keys and dragging
Possible values:
0 = 'Unlocked Only'
(
Drag scrolling only works when the parent patcher is unlocked
)
1 = 'Locked and Unlocked'
(
Drag scrolling is always enabled
)
2 = 'Never'
(
Drag scrolling is never enabled
)
lockedsize[int]: 0
When lockedsize is enabled, you cannot resize the bpatcher object's rectangle by dragging its selection rectangle. You can change the size using the inspector however.
name[symbol]: <none>
Designates the pathname of the patcher file for the bpatcher to use. The name attribute can only be set using the inspector.
offset[2 floats]: 0. 0.
Offset
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. 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'
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]
You can override the default appearance of a user interface object by assigning a JavaScript file with code for painting the object. The file must be in the search path.
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
(drag)
When a patcher file is dragged from the Max File Browser to a bpatcher object, the file will be loaded.
(mouse)
When the window containing the bpatcher object is locked (or the Command key on Macintosh or Control key on Windows is held down) and the mouse is clicked inside the bpatcher object’s box, the gesture is handled by the patch inside the box.
If the Shift and Command keys on Macintosh or Shift and Control keys on Windows are held down while clicking on a bpatcher object, dragging the mouse moves the upper-left corner of the visible part of the patch inside the box. The Assistance area of the patcher window shows the pixel values of the offset. If Enable Drag-Scrolling is unchecked in the bpatcher Inspector window, this feature is disabled.
If the Command and Option keys on Macintosh or Control and Alt keys on Windows are held down while clicking in a bpatcher object, a pop-up menu allows you to open the original file of the patch contained inside the box in its own window, or change the patch currently contained inside the box in its own window.
replace
The replace message is intended for use in conjunction with scripting messages to the thispatcher object. If you send a replace message via an inlet to the bpatcher object, it will only work if there is no patcher inside the bpatcher; the inlet to the bpatcher object is used for sending messages into its subpatcher, not for sending messages to the bpatcher object itself.
To use the replace message feature via scripting messages, give your bpatcher object a Scripting Name using the Inspector, then use the message script sendbox <bpatcher-name> replace <patcher-name> to send the message to the named bpatcher object.
- filename
[symbol]
Output
See Also
| Name | Description |
|---|---|
| Search Path | Search Path |
| patcher | Create a subpatch within a patch |
| patcherargs | Retrieve patcher arguments |
| pcontrol | Open and close subwindows |
| thispatcher | Send messages to a patcher |