Interface Tutorial 1: bpatchers
This tutorial references the patcher 01uBpatchers.maxpat
Introduction
This tutorial looks at a useful object for embedding subpatchers within a patcher so that their interface is visible. The bpatcher object is superficially similar to making any abstraction: we create a patcher file (with inlets and outlets, as necessary) and save it to disk. Rather than instantiating it with an object box, however, we use the bpatcher object to 'embed' it visibly inside another patcher. This allows us to construct a library of interface elements - pieces of patcher logic that show an interface that we can re-use multiple times.
To open the tutorial patch, click on the Open Tutorial button in the upper right-hand corner of the documentation window.
Overview of the tutorial patcher
Take a look at the tutorial patcher. The reasonably sparse window contains a toggle labeled "Start", three button objects ("draw", "see", and "erase"), and three identical-looking interface areas, each with a "clear button>.
Click on the toggle labeled "Start". Move the mouse over to the left-hand interface area and draw in the blue rectangle that contains the small yellow ball. This is a jsui object loaded with a user-interface that presents an X-Y function to track the mouse when clicked. As you draw by dragging in the jsui, the gesture of your drawing will be traced in red in the lcd object below. The lcd object has its border turned off, so you won't see anything until you draw something in the jsui. If you clear the lcd (with the "erase" button) you should see your gesture draw again.
Go to the second and third jsui objects and "draw" in them with the mouse. Notice that they generate tracings in the lcd object in green and blue, respectively. Hit the "erase" button to clear the lcd and see them redraw.
Turn up the slider objects next to the jsui objects and you will see that the tracings become noisy - the gestures recorded from the jsui are now being randomized a bit to add more texture to the drawing. Click any of the button objects labeled "clear" to erase the captured gesture. You can then redraw a new gesture in the appropriate jsui.
With some gestures loaded, click on the button labeled "see" at the top of the patcher. Notice that the three interface areas suddenly look different - a new set of jsui objects appear that play back the gestures as you entered them, and the associated controls have gone away. Where did the original jsui, slider, and "clear" button for each interface go?
The bpatcher object
Unlock the tutorial patcher. Notice that a number of hidden objects appear; moreover, light blue boxes appear around the three interface areas. The blue boxed areas are in fact bpatcher objects containing an abstraction patcher saved on disk. These patcher files have parts of their interface shown inside the main tutorial patch. The concept is that a patch contained in the bpatcher is behind the main patcher and shows through an opening.
Click on any of the three interface areas and notice that, rather than being able to edit the objects within, you can merely move and resize the bpatcher (blue box) area. Control-click (Mac) or right-click (Windows) on one of the blue boxes to get its contextual menu. From the menu, go down to the Object submenu and select "Open Original doodlepatch.maxpat". The original copy of the three interface areas will open. Let's take a look at that patcher.
Unlock the "doodlepatch.maxpat" abstraction. Notice that all we see is the interface elements of the patcher, regardless of whether the patcher is unlocked. This is because the patcher is in Presentation Mode - we can set any patcher to open in Presentation Mode by checking "Open In Presentation" in the Patcher Inspector. From the View menu, uncheck Presentation and the patcher will morph back to its original view and a bunch of patcher logic will appear.
Take a look at the code in the patcher. It uses a coll object as well as some supporting logic to take the drawing data from the jsui object and record it (this is a form of gesture capture, as seen in "Data Tutorial 3"). The second jsui (to the right) immediately reanimates the data from the coll in response to bang messages coming in from the inlet and driving a counter object.
Offsetting a bpatcher
Without closing the "doodlepatch.maxpat" file, switch back to the tutorial patcher and look at the "draw" and "see" button objects when the patcher is unlocked. Notice that they trigger message boxes containing the messages offset -60 0 and offset -360 0, respectively, sent into the second inlet of the bpatcher objects.
Look in the bpatcher patch and see what the second inlet is connected to. Notice that it talks to a thispatcher object. The thispatcher object provides functionality for controlling the appearance of a patcher file, including its size, position on the screen, and whether the title bar is visible or not. When used within a bpatcher file, the thispatcher object can scroll the interface of the bpatcher object based on coordinates provided with the offset message. This allows our main tutorial patcher to switch between two different viewpoints on the same bpatcher file - in this case, the "draw" view and the "see view".
Arguments for bpatcher objects
Look a the patcher logic attached to the outlet of the bpatcher file. There is an append object with three pound-sign abstraction arguments (#1 #2 #3). These arguments would normally be provided in the object box if we were to load "doodlepatch.maxpat" as a normal abstraction in our patcher. In order to set these arguments within a bpatcher object, we have to use the object's Inspector.
Close the bpatcher abstraction file and go back to the tutorial patcher. Click on one of the bpatcher objects and open its Inspector. Notice that at the bottom we can find the name of the Patcher File loaded by the object. Directly under this is the Argument(s) field, which contains three numbers. These numbers are substituted for the patcher arguments for each bpatcher independently, allowing us to differentiate multiple copies of them in our patch.
The arguments for our bpatcher in this tutorial control the three colors drawn by the gesture capture system in the lcd (in short, they provide the last three numbers for the frameoval commands sent to the lcd). Open the Inspector for each bpatcher and change those values to a different color value in RGB form (0 - 255). When you record new gestures, you will see them appear in the lcd using the colors you selected.
Summary
The bpatcher object provides an extremely useful way to embed visual interfaces within a larger project. An interface can be designed (with whatever supporting logic is required), saved, and displayed in another patch. The offset message to a thispatcher object within a bpatcher allows us to "scroll" the viewing rectangle of the object to reveal different portions of the interface. This, combined with the use of Presentation Mode, allows us to customize the interface further. Just as with other types of abstractions, patchers made for use with the bpatcher object can process arguments, set through the object's Inspector.