Max 5 API Reference

Old-Style Classes
[Classes]

Collaboration diagram for Old-Style Classes:

Functions

void setup (t_messlist **ident, method makefun, method freefun, short size, method menufun, short type,...)
 Use the setup() function to initialize your class by informing Max of its size, the name of your functions that create and destroy instances, and the types of arguments passed to the instance creation function.
void addmess (method f, char *s, short type,...)
 Use addmess() to bind a function to a message other than the standard ones covered by addbang(), addint(), etc.
void addbang (method f)
 Used to bind a function to the common triggering message bang.
void addint (method f)
 Use addint() to bind a function to the int message received in the leftmost inlet.
void addfloat (method f)
 Use addfloat() to bind a function to the float message received in the leftmost inlet.
void addinx (method f, short n)
 Use addinx() to bind a function to a int message that will be received in an inlet other than the leftmost one.
void addftx (method f, short n)
 Use addftx() to bind a function to a float message that will be received in an inlet other than the leftmost one.
void * newobject (void *maxclass)
 Use newobject to allocate the space for an instance of your class and initialize its object header.
void freeobject (t_object *op)
 Release the memory used by a Max object.
void * newinstance (t_symbol *s, short argc, t_atom *argv)
 Make a new instance of an existing Max class.
void alias (char *name)
 Use the alias function to allow users to refer to your object by a name other than that of your shared library.
void class_setname (char *obname, char *filename)
 Use class_setname() to associate you object’s name with it’s filename on disk.
void * typedmess (t_object *op, t_symbol *msg, short argc, t_atom *argp)
 Send a typed message directly to a Max object.
method getfn (t_object *op, t_symbol *msg)
 Use getfn() to send an untyped message to a Max object with error checking.
method egetfn (t_object *op, t_symbol *msg)
 Use egetfn() to send an untyped message to a Max object that always works.
method zgetfn (t_object *op, t_symbol *msg)
 Use zgetfn() to send an untyped message to a Max object without error checking.

Function Documentation

void addbang ( method  f  ) 

Used to bind a function to the common triggering message bang.

Parameters:
f Function to be the bang method.
void addfloat ( method  f  ) 

Use addfloat() to bind a function to the float message received in the leftmost inlet.

Parameters:
f Function to be the int method.
void addftx ( method  f,
short  n 
)

Use addftx() to bind a function to a float message that will be received in an inlet other than the leftmost one.

Parameters:
f Function to be the float method.
n Number of the inlet connected to this method. 1 is the first inlet to the right of the left inlet.
Remarks:
This correspondence between inlet locations and messages is not automatic, but it is strongly suggested that you follow existing practice. You must set the correspondence up when creating an object of your class with proper use of intin and floatin in your instance creation function New Instance Routine.
void addint ( method  f  ) 

Use addint() to bind a function to the int message received in the leftmost inlet.

Parameters:
f Function to be the int method.
void addinx ( method  f,
short  n 
)

Use addinx() to bind a function to a int message that will be received in an inlet other than the leftmost one.

Parameters:
f Function to be the int method.
n Number of the inlet connected to this method. 1 is the first inlet to the right of the left inlet.
Remarks:
This correspondence between inlet locations and messages is not automatic, but it is strongly suggested that you follow existing practice. You must set the correspondence up when creating an object of your class with proper use of intin and floatin in your instance creation function New Instance Routine.
void addmess ( method  f,
char *  s,
short  type,
  ... 
)

Use addmess() to bind a function to a message other than the standard ones covered by addbang(), addint(), etc.

Parameters:
f Function you want to be the method.
s C string defining the message.
type The first of one or more integers from e_max_atomtypes specifying the arguments to the message.
... Any additional types from e_max_atomtypes for additonal arguments.
See also:
Anatomy of a Max Object
void alias ( char *  name  ) 

Use the alias function to allow users to refer to your object by a name other than that of your shared library.

Parameters:
name An alternative name for the user to use to make an object of your class.
void class_setname ( char *  obname,
char *  filename 
)

Use class_setname() to associate you object’s name with it’s filename on disk.

Parameters:
obname A character string with the name of your object class as it appears in Max.
filename A character string with the name of your external’s file as it appears on disk.
method egetfn ( t_object op,
t_symbol msg 
)

Use egetfn() to send an untyped message to a Max object that always works.

Parameters:
op Receiver of the message.
msg Message selector.
Returns:
egetfn returns a pointer to the method bound to the message selector msg in the receiver’s message list. If the method can’t be found, a pointer to a do-nothing function is returned.
void freeobject ( t_object op  ) 

Release the memory used by a Max object.

freeobject() calls an object’s free function, if any, then disposes the memory used by the object itself. freeobject() should be used on any instance of a standard Max object data structure, with the exception of Qelems and Atombufs. Clocks, Binbufs, Proxies, Exprs, etc. should be freed with freeobject().

Parameters:
op The object instance pointer to free.
Remarks:
This function can be replaced by the use of object_free(). Unlike freeobject(), object_free() checkes to make sure the pointer is not NULL before trying to free it.
See also:
newobject()
object_free()
method getfn ( t_object op,
t_symbol msg 
)

Use getfn() to send an untyped message to a Max object with error checking.

Parameters:
op Receiver of the message.
msg Message selector.
Returns:
getfn returns a pointer to the method bound to the message selector msg in the receiver’s message list. It returns 0 and prints an error message in Max Window if the method can’t be found.
void* newinstance ( t_symbol s,
short  argc,
t_atom argv 
)

Make a new instance of an existing Max class.

Parameters:
s className Symbol specifying the name of the class of the instance to be created.
argc Count of arguments in argv.
argv Array of t_atoms; arguments to the class’s instance creation function.
Returns:
A pointer to the created object, or 0 if the class didn’t exist or there was another type of error in creating the instance.
Remarks:
This function creates a new instance of the specified class. Using newinstance is equivalent to typing something in a New Object box when using Max. The difference is that no object box is created in any Patcher window, and you can send messages to the object directly without connecting any patch cords. The messages can either be type- checked (using typedmess) or non-type-checked (using the members of the getfn family).

This function is useful for taking advantage of other already-defined objects that you would like to use “privately” in your object, such as tables. See the source code for the coll object for an example of using a privately defined class.

void* newobject ( void *  maxclass  ) 

Use newobject to allocate the space for an instance of your class and initialize its object header.

Parameters:
maxclass The global class variable initialized in your main routine by the setup function.
Returns:
A pointer to the new instance.
Remarks:
You call newobject() when creating an instance of your class in your creation function. newobject allocates the proper amount of memory for an object of your class and installs a pointer to your class in the object, so that it can respond with your class’s methods if it receives a message.
void setup ( t_messlist **  ident,
method  makefun,
method  freefun,
short  size,
method  menufun,
short  type,
  ... 
)

Use the setup() function to initialize your class by informing Max of its size, the name of your functions that create and destroy instances, and the types of arguments passed to the instance creation function.

Parameters:
ident A global variable in your code that points to the initialized class.
makefun Your instance creation function.
freefun Your instance free function (see Chapter 7).
size The size of your objects data structure in bytes. Usually you use the C sizeof operator here.
menufun No longer used. You should pass NULL for this parameter.
type The first of a list of arguments passed to makefun when an object is created.
... Any additional arguments passed to makefun when an object is created. Together with the type parameter, this creates a standard Max type list as enumerated in e_max_atomtypes. The final argument of the type list should be a 0.
See also:
Anatomy of a Max Object
void* typedmess ( t_object op,
t_symbol msg,
short  argc,
t_atom argp 
)

Send a typed message directly to a Max object.

Parameters:
op Max object that will receive the message.
msg The message selector.
argc Count of message arguments in argv.
argp Array of t_atoms; the message arguments.
Returns:
If the receiver object can respond to the message, typedmess() returns the result. Otherwise, an error message will be seen in the Max window and 0 will be returned.
Remarks:
typedmess sends a message to a Max object (receiver) a message with arguments. Note that the message must be a t_symbol, not a character string, so you must call gensym on a string before passing it to typedmess. Also, note that untyped messages defined for classes with the argument list A_CANT cannot be sent using typedmess. You must use getfn() etc. instead.

Example:

    //If you want to send a bang message to the object bang_me… 
    void *bangResult; 
    bangResult = typedmess(bang_me,gensym("bang"),0,0L);
method zgetfn ( t_object op,
t_symbol msg 
)

Use zgetfn() to send an untyped message to a Max object without error checking.

Parameters:
op Receiver of the message.
msg Message selector.
Returns:
zgetfn returns a pointer to the method bound to the message selector msg in the receiver’s message list. It returns 0 but doesn’t print an error message in Max Window if the method can’t be found.

Copyright © 2008, Cycling '74