Tutorial 1: Hello
This tutorial references the patcher 01mHello.maxpat
Max patcher basics
In this tutorial, we will examine the building blocks of a Max patcher: the object box, the message box and the comment box. We will also delve into some of the basic editing functions provided by the Max environment.
This brief tour of a simple patcher will show the basic typology of simple programs written in Max: object boxes that perform command actions within a patch; message boxes that allow us to create messages that can be sent to the objects; comment boxes that allow us to document our patchers to make them easier to understand.
To open the tutorial patch, click on the blue Open Tutorial button in the upper right-hand corner of the documentation window.
Looking around
Take a look at the patcher 01mHello. At the top-center of the patcher window, we can see three types of boxes.
The first element is the box labeled print. This is an object box, and can be recognized by its light grey border and (in this case) a small "port" at the top left that we call an inlet. Object boxes are the basic logic element of Max – they contain functions that perform some sort of task, and operate like miniature programs within the larger environment.
Just below the object box is a message box (labelled with the word "message"). These are visually different from the object box – they have a gray background, and do not have a border. Message boxes contain some information (called a message) that can be sent to objects, and can operate as either commands or control data.
The third box doesn’t look like a box at all – it appears to be text on the background of patcher window. This is a comment. There is actually a box around this text, but it is not visible until we decide to edit our patch. A comment box is used to add text for labeling controls (e.g. "click me"), or for adding information to your patch to make its operation more apparent to you or anyone you might share your patch with.
Max programs function by passing messages between objects. Object boxes can be connected to one another, and message boxes can be used to originate or, in some cases, process messages that are used to control other objects.
Unlocking the patcher
When you first opened this patcher, it was in a "locked" state – meaning that you cannot edit any of the objects or text in the window. When a patcher is locked, the intention is that it be used as a program. Since the power of Max is that we can edit and manipulate these programs to do whatever we like, let's unlock this patch and do some editing.
Choose Edit from the View menu. You will see several changes in the patcher. First, the boxes surrounding the comment boxes are revealed (we told you they were there). Secondly, the message and comment boxes show inlets that were hidden in the locked state. In addition, a port on the bottom of the message box is revealed; this is an outlet. Finally, many more of the icons at the bottom of the patcher window are now available for our use.
In addition to the visible changes, we are now free to edit the contents of the window. Double-click inside the object box in the upper-right that says print; the text is selected, and you can type another object name into that box. Type "metro" (without the quotes), and click outside the object box to complete the edit. We have now changed the function of that object - it is now a metro object. You will see the object box change size, and the number of inlets and outlets will change as the function of the object has changed. We learn Max by building up a vocabulary of objects, including how they connect to other objects and what messages they understand and transmit.
Double-click inside the message box on the right. Change the message text to anything (for example, type in the word "anything"), then click outside the box to accept the change. Note that changing the message text does not change the inlets or outlets, since only the contents (but not the function) of the message box has changed.
Finally, double-click inside the comment box and change its text. Since the comment box has no function other than adding text to the patch, you are free to put in any text that pleases you.
Interacting with a locked patcher
Lock the patch by unchecking Edit in the View menu. Let’s see what happens when we click on each of the box types. In the top-center of the patch, click on the object box (which we changed from print to metro) – nothing happens. Clicking on the message box directly below it, however, acts like a button – you can see the text get pushed back when you click it.
Click on the Max console icon on the right-hand side of the window to open the sidebar. On the left side of our patcher, there are three message boxes connected (with lines called patchcords) to a print object . Click on each of these message boxes in turn, then look at the Max Console; you will see that the contents of the message boxes we clicked are displayed there. This was a result of clicking on the message boxes: they generated a message (the content of the message box) and sent it down the patchcord to the print object. The print object takes any message it receives in its inlet and displays it in the Max Console.
Commas change everything
You probably noticed that two of the message boxes have almost identical text, but the display in the Max Console is different. The message box with the text "Good morning, everybody!" caused the text to be displayed on two lines. The message "Good morning\, everybody!" was displayed on a single line in the Max Console. The difference is in the use of the comma, which has a special meaning in message boxes within Max. In a message box, the comma is used as a message separator; in essence, it turns a single line of text into two discrete messages. Thus, the message "Good morning, everybody!" is really treated like two messages: "Good morning" is sent out the outlet of the message box, followed immediately by "everybody!". In order to treat the comma as text (rather than as a message separator), you need to let the message box know that you are overriding the comma’s special behavior. You do this by preceding the comma with the backslash ("\") character, which tells the message box to ignore the comma’s special use, and treat it as a literal text character. Those of you familiar with textual programming languages will be familiar with the use of a backslash character to "escape" a character that has special meaning.
Unlock the patcher, click inside the lower message box (the one with the backslash) and remove the slash. Lock the patch and click on the edited message box – you will see that it, too, now creates two lines of text in the Max Console. Edit the first message box, adding a backslash before its comma, and lock the patch; it now exhibits the expected behavior of printing the entire message on a single line.
Getting help
The print object is obviously doing something to send text to the Max Console. To determine what function any object box performs, you can view several types of document to get help. Unlock the patcher for these operations:
Select the print object box by either clicking into it or clicking and dragging the mouse over it to highlight it. Select Open print Help from the Help menu. A new patcher window (called a Help patcher) opens with an example that shows the print object in action. Note that this is an actual Max patch, and can be unlocked, edited, or copied elsewhere, retaining any of the displayed functionality.
Select the print object as before and then click on the Reference icon in the right patcher window toolbar to open the sidebar. An abbreviated reference will appear with information on the object's function, arguments, messages, attributes and links to similar objects. You will have already seen this in the help patcher, which opens with the sidebar open.
Select the print object and choose Open print Reference from the Help menu. A browser window is displayed with the Reference Manual page for the print object. This gives detailed information about the object, including the function of all of its inlets and outlets, and how it responds to each message. It even provides an example patch for your reference. This is the most detailed information available for any object. Objects and topics relevant or similar to the object you're viewing can be viewed by clicking on links in the See Also section at the bottom of the reference. The reference page is also available via a right click on an object or in the "?" tab of an object's help file.
Create some new messages
Let’s add some objects to our patch, and create our own message passing logic. First, with the patcher unlocked, click on the plain Object icon in the top patcher window toolbar and drag it to the patching window. This will place an empty object box on your patcher window, ready for you to enter its name. Type "print", then either hit return or click outside the box to accept this name. We need some clear space above it, so if necessary move the object by dragging it.
Next, click on the Message icon in the top patcher window toolbar and drag it to the patching window. When it appears, type in the message "Goodbye!". Place this message box above the print object. Finally, connect the two boxes by clicking on the outlet of the message box, dragging the mouse to the inlet of the print object, then releasing the mouse button. This will create a patchcord between the two objects, allowing messages to pass from the message box to the print object.
Lock the patch and click on the new "Goodbye!" message. You will see the text "Goodbye!" appear in the Max Console. Congratulations – you’ve just done your first Max patching!
Summary
The three main elements of a Max patch (object boxes, message boxes and comment boxes), along with patchcords, are the core of all Max programs. Each type of element responds to a variety of messages and editing functions; these can be explored by viewing the help files and Reference Manual documents. Each of these aspects will be expanded upon in later tutorials.