setclock

Create and control an alternative clock

Description

Allows the creation of alternatives to the standard millisecond clock. This includes several modes of timing that change timing activities. Each setclock is associated with a name (its first argument), and this name may be passed as the argument to a "clock" message to numerous objects that use timing in Max, such as metro, line, and pipe.

Examples

setclock becomes the clock for metro... setclock modifies the time for clocker

Arguments

name [symbol]

Obligatory. The first argument is the name of the setclock object, by which timing objects such as clocker, line, metro, pipe, and tempo can refer to the setclock. Those timing objects -- once they have received the message clock followed by the name of a setclock object -- use that setclock as their timing source instead of Max's regular millisecond clock. The setclock object need not be in the same patcher as the timing objects that refer to it. More than one setclock object may exist with the same name; setclock objects with the same name share the same clock time information. (Note: Different setclock objects that share the same name argument can have different mode arguments typed in, but they will in fact operate with the mode of whichever setclock was first loaded with that name. Thus, setclock objects with the same name but different modes may behave unpredictably, since the order in which they are loaded by Max is often unknown.)

The second (optional) argument describes the mode of clock operation this setclock object will have. The possible modes for the second argument are:

mode [symbol]

The word pass specifies passive mode. In this mode, the setclock object's current clock time is set by a number received in the left inlet, and associated timing objects will follow that clock time just as if it were a regularly progressing millisecond clock. If no second argument is present, the mode is pass by default.

The word add specifies additive mode. A number received in the left inlet is added to the current clock time to determine the new clock time.

The word mul specifies multiplicative mode. The number received in the left inlet is used as a factor by which all associated timing objects will modify their time settings. For example, a factor of 2.0 will cause all timing objects that are using the setclock as their clock source to double their time values (that is, to halve their speed). An alternative (and perhaps more truthful) way to conceptualize the behavior of mul mode is to think of the incoming float as a divisor by which setclock divides the speed at which its own clock time progresses. Thus, when it receives the number 2.0 it divides its own clock speed by 2.0, causing the objects which are following that clock to progress twice as slowly.

The word interp specifies interpolate mode. The number received in the left inlet is gradually added to the current time of setclock, over a time period determined by the amount of time elapsed since the previous number was received. During that time period, setclock linearly interpolates to set its clock to the intermediate values.

multiplier [float]

If the second argument is mul, an optional third argument specifies a multiplier for the time of all associated timing objects. If no third argument is present, the multiplier is 1.0 by default.

Attributes

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] (default: 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'

hidden [int] (default: 0)

Toggles whether an object is hidden when the patcher is locked.

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] (default: 0)

Toggles whether an object ignores mouse clicks in a locked patcher.

patching_rect [4 floats] (default: 0. 0. 100. 0.)

Sets the position and size of the object in the patcher window.

position [2 floats]

g/s(set)

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] (default: 0)

Sets whether an object belongs to the patcher's presentation.

presentation_rect [4 floats] (default: 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]

g/s(set)

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]

g/s(set)

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 [float]

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

bang

In left inlet: Sends out the current time value, according to the setclock object's own clock. Timing objects such as clocker, line, metro, pipe, and tempo can use setclock as their clock source instead of Max's regular millisecond clock.

int

Arguments

timing [int]
In left inlet: The meaning of the number depends on the second typed-in argument, which identifies the setclock object's mode of operation. If the mode is pass [ive] (the default mode), the number sets an absolute clock time which timing objects may use by comparing it to their initial time value. If the mode is add [itive], the number is added to the setclock object's current clock time. If the mode is interp [olate], setclock will change its clock time incrementally by that amount, over a time period determined by the time elapsed since the previous number was received. (However, negative numbers cause an immediate decrease in the clock time.) If the mode is ext [ernal], the number is simply ignored. If the mode is mul [tiplicative], the number is used as a multiplier for associated timing objects. For instance the number 0.5 halves the rate of increase (speed) of the associated timing objects.

In right inlet: Sets the time interval, in milliseconds, at which the setclock will report its clock information to associated timing objects. The default is 5 milliseconds.

float

Arguments

timing [float]
Performs the same function as int.

  (inlet1)

Arguments

interval [int]
In right inlet: Sets the time update interval.

clock

Arguments

clock name [symbol]
The word clock, followed by a word, specifies the name of the name of the setclock object, by which timing objects such as clocker, line, metro, pipe, and tempo can refer to the setclock.

(mouse)

Double-clicking with the mouse will print status messages in the Max Console.

reset

Arguments

interval [float]
The word reset followed by a number of milliseconds sets the timing interval at which the object will report its clock information to associated timing objects. The information is reported whenever the next report is due according to the set interval.

set

Arguments

interval [float]
The word set followed by a number of milliseconds sets the timing interval at which the object will report its clock information to associated timing objects. The information is reported to those associated objects immediately.

Output

int

When bang is received in the left inlet, setclock sends its current time reading out the outlet.

See Also

Name Description
Timing and Sequencing Events Timing and Sequencing Events
clocker Report elapsed time, at regular intervals
metro Output a bang message at regular intervals
timer Report elapsed time between two events