A newer version of Max is available. Click here to access the latest version of this document.
Tutorial 4: Metro and Toggle
Automated actions
Open the tutorial.
This tutorial focuses on automated actions and the ability to control them. We will work with the toggle user interface object to control the metro timing object. We will also look further into object arguments and overriding those arguments.
One of the most used objects in your home is the light switch – it provides a simple user interface to a complex system (the lights in your home). Likewise, the toggle object, combined with the automated timing function of metro, offer a simple interface into an otherwise complicated world of automated and scheduled actions.
Fun with the toggle object
Take a look at the 04mMetroAndToggle patcher. The left-most patch features a series of message boxes (and a button) connected to a square box. Start by clicking in that box – we see its interior fill with a checkbox. A 1 message was also sent from the object downstream to the number box connected below it. Clicking in the object again will remove the checkbox and send out a 0. That's all this object does - it outputs either a zero or non-zero value, depending on its state (off or on). This object’s formal name is toggle, and it is one of the most-used objects in Max programming.
Unlike most of the checkboxes that we run into when using our computers, this checkbox can be automated by sending it messages. Click on the message boxes that are connected to the toggle to see their effect on the object’s state. By looking at the connected number box, we see that any number other than 0 turns it to "on" (the check mark is visually set); the toggle also "echoes" the value of the number that turned it on out its outlet. Clicking on the 0 message turns the toggle off, and outputs a 0.
The action of the button object is even more interesting. Clicking on the button switches the toggle object on and off, with the output (seen in the Max window and in the number box) alternating between 0 and 1. This is the root of the toggle object's name – its ability to "toggle" states based on incoming bang messages.
Introduction to metro: the metronome object
The patch in the center introduces a new object: metro. The metro produces bang messages, much like the button object. However, unlike button, metro objects send these messages automatically on a scheduled basis. Once started, metro will continue to send bang messages until stopped. Click on the toggle that is connected to the metro, and watch the result – it sends a bang message (in this case, to a button object) once every second. We can turn it off by un-checking (turning off) the toggle. the metro object is one of the Max objects that can be used to create automated or self-running actions in our programs.
If we click on the button that is connected to the metro we see that it, too, starts the metro running. If we click on it again, we see that it immediately triggers a bang out of the metro immediately; rapidly click on the button, and the output continues being generated. It is only when we pause that we see the scheduled event generation. When a metro receives a bang, the metro will "re-start" itself and begin scheduling subsequent bang messages from the moment we triggered it. When we want to turn it off, we can click on the stop message to turn off event generation; telling a metro to stop with a message is equivalent to sending it a 0.
How did we determine the speed at which the metro outputs bang messages? We determine the speed of a metro by setting its period. The metro object takes an argument (the number 1000, in this case) that sets the time interval (in milliseconds) between messages. 1000 milliseconds equals 1 second, which is why we see the bang messages coming out at that rate. How do we change this rate? That is the function of metro object's right inlet – it allows you to send a new time interval setting without having to type in a new argument value.
In our patch, there is a number box with several message boxes connected to it. Click on the 2000 message, and (after the next scheduled period) the output will slow to one message every two seconds. Click on the 500 and the metro speeds up, sending bang messages twice a second. The message 250 will cause four bang messages per second. Changing the interval setting doesn’t change any other aspect of metro (e.g. whether it is "on" or "off").
Changing the interval with a message in the right inlet also does not change the argument of the metro. Why not? Wouldn’t it be convenient to see the new value? Perhaps, but it would mean that any changes to the object would change the value saved with the patch – and, most times, you want to maintain the typed-in argument since it functions as the default starting value of the metro. Many Max objects behave in this way: they have one or more arguments that can be overridden by messages sent into inlets.
Running in parallel
The third patcher in our tutorial features a single toggle attached to three additional toggle objects, each of which is connected to a metro with a different argument. Turn on the top-level toggle, and the metro objects generate a "galloping" light show. This is because the three time interval arguments of the metro objects are related: the first metro fires every second (1000 milliseconds), the second triggers three times per second, and the third fires every quarter-second. There is nothing managing this pattern – it just occurs because the scheduled output of the metro objects are constant, so the pattern keeps appearing. Note that the time interval of a metro can be both an integer (e.g. 1000) or a floating-point (e.g. 333.33) number.
Let’s expand on the idea of creating rhythmic patterns by using some of the other ideas we just learned. We can change the pattern by changing the time values of each metro; let’s start by adding three message boxes, of values 500, 200 and 750, and connecting one to the right inlet of each metro. When we click them to change the time intervals of our metro objects, no apparent pattern exists. This is because we need to synchronize the start of the metro objects to see the pattern. This can be accomplished by turning the top-most toggle off and on again. The result is a quickly flashing center light, with a syncopated outside pattern.
Let’s make another pattern, using message boxes for the values 200, 400, and 600, respectively. However, instead of using the toggle to switch the metro objects off and on, connect a single button object to the left inlet of all three metro objects. Click on the three message boxes, and then click on the button to restart all of the metro objects. The button forces the metro objects to restart in sync, giving us the expected "rolling" light show.
Automated actions are at the heart of many Max performance patches, and metro objects are often used as the starting point for these actions. Once started, the scheduling system of Max provides a stable timing system for Max output, and we can allow the events to run without further interaction.
Controlling patches using the checkbox-like toggle object is also a key programming tool, since a single toggle can provide a simple on/off interface to much more complicated processes.

See Also

Name Description
toggle Switch between off and on (0 and 1)
metro Output a bang message at regular intervals