Max 5 API Reference

Classes

When a user types the name of your object into an object box, Max looks for an external of this name in the searchpath and, upon finding it, loads the bundle or dll and calls the main() function. More...

Collaboration diagram for Classes:

Data Structures

struct  t_class
 The data structure for a Max class. More...

Modules

 Old-Style Classes
 Inlets and Outlets
 

Routines for creating and communicating with inlets and outlets.


Defines

#define CLASS_BOX   gensym("box")
 The namespace for all Max object classes which can be instantiated in a box, i.e.
#define CLASS_NOBOX   gensym("nobox")
 A namespace for creating hidden or internal object classes which are not a direct part of the user creating patcher.

Enumerations

enum  e_max_class_flags {
  CLASS_FLAG_BOX = 0x00000001L,
  CLASS_FLAG_POLYGLOT = 0x00000002L,
  CLASS_FLAG_NEWDICTIONARY = 0x00000004L,
  CLASS_FLAG_REGISTERED = 0x00000008L,
  CLASS_FLAG_UIOBJECT = 0x00000010L,
  CLASS_FLAG_ALIAS = 0x00000020L,
  CLASS_FLAG_SCHED_PURGE = 0x00000040L,
  CLASS_FLAG_DO_NOT_PARSE_ATTR_ARGS = 0x00000080L,
  CLASS_FLAG_NOATTRIBUTES = 0x00010000L,
  CLASS_FLAG_OWNATTRIBUTES = 0x00020000L
}
 

Class flags.

More...

Functions

t_class * class_new (C74_CONST char *name, C74_CONST method mnew, C74_CONST method mfree, long size, C74_CONST method mmenu, short type,...)
 Initializes a class by informing Max of its name, instance creation and free functions, size and argument types.
t_max_err class_free (t_class *c)
 Frees a previously defined object class.
t_max_err class_register (t_symbol *name_space, t_class *c)
 Registers a previously defined object class.
t_max_err class_alias (t_class *c, t_symbol *aliasname)
 Registers an alias for a previously defined object class.
t_max_err class_addmethod (t_class *c, C74_CONST method m, C74_CONST char *name,...)
 Adds a method to a previously defined object class.
t_max_err class_addattr (t_class *c, t_object *attr)
 Adds an attribute to a previously defined object class.
t_symbol * class_nameget (t_class *c)
 Retrieves the name of a class, given the class's pointer.
t_class * class_findbyname (t_symbol *name_space, t_symbol *classname)
 Finds the class pointer for a class, given the class's namespace and name.
t_class * class_findbyname_casefree (t_symbol *name_space, t_symbol *classname)
 Finds the class pointer for a class, given the class's namespace and name.
t_max_err class_dumpout_wrap (t_class *c)
 Wraps user gettable attributes with a method that gets the values and sends out dumpout outlet.
void class_obexoffset_set (t_class *c, long offset)
 Registers the byte-offset of the obex member of the class's data structure with the previously defined object class.
long class_obexoffset_get (t_class *c)
 Retrieves the byte-offset of the obex member of the class's data structure.
long class_is_ui (t_class *c)
 Determine if a class is a user interface object.

Detailed Description

When a user types the name of your object into an object box, Max looks for an external of this name in the searchpath and, upon finding it, loads the bundle or dll and calls the main() function.

Thus, Max classes are typically defined in the main() function of an external.

Historically, Max classes have been defined using an API that includes functions like setup() and addmess(). This interface is still supported, and the relevant documentation can be found in Old-Style Classes.

A more recent and more flexible interface for creating objects was introduced with Jitter 1.0 and later included directly in Max 4.5. This newer API includes functions such as class_new() and class_addmethod(). Supporting attributes, user interface objects, and additional new features of Max requires the use of the newer interface for definiting classes documented on this page.

You may not mix these two styles of creating classes within an object.

Define Documentation

#define CLASS_BOX   gensym("box")

The namespace for all Max object classes which can be instantiated in a box, i.e.

in a patcher.

Enumeration Type Documentation

enum e_max_class_flags

Class flags.

If not box or polyglot, class is only accessible in C via known interface

Enumerator:
CLASS_FLAG_BOX 

for use in a patcher

CLASS_FLAG_POLYGLOT 

for use by any text language (c/js/java/etc)

CLASS_FLAG_NEWDICTIONARY 

dictionary based constructor

CLASS_FLAG_REGISTERED 

for backward compatible messlist implementation (once reg'd can't grow)

CLASS_FLAG_UIOBJECT 

for objects that don't go inside a newobj box.

CLASS_FLAG_ALIAS 

for classes that are just copies of some other class (i.e. del is a copy of delay)

CLASS_FLAG_SCHED_PURGE 

for classes that have called clock_new() or qelem_new() (don't need to set this yourself)

CLASS_FLAG_DO_NOT_PARSE_ATTR_ARGS 

override dictionary based constructor attr arg parsing

CLASS_FLAG_NOATTRIBUTES 

for efficiency

CLASS_FLAG_OWNATTRIBUTES 

for classes which support a custom attr interface (e.g. jitter)

Function Documentation

t_max_err class_addattr ( t_class *  c,
t_object *  attr 
)

Adds an attribute to a previously defined object class.

Parameters:
c The class pointer
attr The attribute to add. The attribute will be a pointer returned by attribute_new(), attr_offset_new() or attr_offset_array_new().
Returns:
This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined in e_max_errorcodes if unsuccessful.
t_max_err class_addmethod ( t_class *  c,
C74_CONST method  m,
C74_CONST char *  name,
  ... 
)

Adds a method to a previously defined object class.

Parameters:
c The class pointer
m Function to be called when the method is invoked
name C-string defining the message (message selector)
... One or more integers specifying the arguments to the message, in the standard Max type list format (see Chapter 3 of the Writing Externals in Max document for more information).
Returns:
This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined in e_max_errorcodes if unsuccessful.
Remarks:
The class_addmethod() function works essentially like the traditional addmess() function, adding the function pointed to by m, to respond to the message string name in the leftmost inlet of the object.
t_max_err class_alias ( t_class *  c,
t_symbol *  aliasname 
)

Registers an alias for a previously defined object class.

Parameters:
c The class pointer
aliasname A symbol who's name will become an alias for the given class
Returns:
This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined in e_max_errorcodes if unsuccessful.
t_max_err class_dumpout_wrap ( t_class *  c  ) 

Wraps user gettable attributes with a method that gets the values and sends out dumpout outlet.

Parameters:
c The class pointer
Returns:
This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined in e_max_errorcodes if unsuccessful.
t_class* class_findbyname ( t_symbol *  name_space,
t_symbol *  classname 
)

Finds the class pointer for a class, given the class's namespace and name.

Parameters:
name_space The desired class's name space. Typically, either the constant CLASS_BOX, for obex classes which can instantiate inside of a Max patcher (e.g. boxes, UI objects, etc.), or the constant CLASS_NOBOX, for classes which will only be used internally. Developers can define their own name spaces as well, but this functionality is currently undocumented.
classname The name of the class to be looked up
Returns:
If successful, this function returns the class's data pointer. Otherwise, it returns NULL.
t_class* class_findbyname_casefree ( t_symbol *  name_space,
t_symbol *  classname 
)

Finds the class pointer for a class, given the class's namespace and name.

Parameters:
name_space The desired class's name space. Typically, either the constant CLASS_BOX, for obex classes which can instantiate inside of a Max patcher (e.g. boxes, UI objects, etc.), or the constant CLASS_NOBOX, for classes which will only be used internally. Developers can define their own name spaces as well, but this functionality is currently undocumented.
classname The name of the class to be looked up (case free)
Returns:
If successful, this function returns the class's data pointer. Otherwise, it returns NULL.
t_max_err class_free ( t_class *  c  ) 

Frees a previously defined object class.

This function is not typically used by external developers.

Parameters:
c The class pointer
Returns:
This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined in e_max_errorcodes if unsuccessful.
long class_is_ui ( t_class *  c  ) 

Determine if a class is a user interface object.

Parameters:
c The class pointer.
Returns:
True is the class defines a user interface object, otherwise false.
t_symbol* class_nameget ( t_class *  c  ) 

Retrieves the name of a class, given the class's pointer.

Parameters:
c The class pointer
Returns:
If successful, this function returns the name of the class as a t_symbol *.
t_class* class_new ( C74_CONST char *  name,
C74_CONST method  mnew,
C74_CONST method  mfree,
long  size,
C74_CONST method  mmenu,
short  type,
  ... 
)

Initializes a class by informing Max of its name, instance creation and free functions, size and argument types.

Developers wishing to use obex class features (attributes, etc.) must use class_new() instead of the traditional setup() function.

Parameters:
name The class's name, as a C-string
mnew The instance creation function
mfree The instance free function
size The size of the object's data structure in bytes. Usually you use the C sizeof operator here.
mmenu The function called when the user creates a new object of the class from the Patch window's palette (UI objects only). Pass 0L if you're not defining a UI object.
type A standard Max type list as explained in Chapter 3 of the Writing Externals in Max document (in the Max SDK). The final argument of the type list should be a 0. Generally, obex objects have a single type argument, A_GIMME, followed by a 0.
Returns:
This function returns the class pointer for the new object class. This pointer is used by numerous other functions and should be stored in a global or static variable.
long class_obexoffset_get ( t_class *  c  ) 

Retrieves the byte-offset of the obex member of the class's data structure.

Parameters:
c The class pointer
Returns:
This function returns the byte-offset of the obex member of the class's data structure.
void class_obexoffset_set ( t_class *  c,
long  offset 
)

Registers the byte-offset of the obex member of the class's data structure with the previously defined object class.

Use of this function is required for obex-class objects. It must be called from main().

Parameters:
c The class pointer
offset The byte-offset to the obex member of the object's data structure. Conventionally, the macro calcoffset is used to calculate the offset.
t_max_err class_register ( t_symbol *  name_space,
t_class *  c 
)

Registers a previously defined object class.

This function is required, and should be called at the end of main().

Parameters:
name_space The desired class's name space. Typically, either the constant CLASS_BOX, for obex classes which can instantiate inside of a Max patcher (e.g. boxes, UI objects, etc.), or the constant CLASS_NOBOX, for classes which will only be used internally. Developers can define their own name spaces as well, but this functionality is currently undocumented.
c The class pointer
Returns:
This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined in e_max_errorcodes if unsuccessful.

Copyright © 2008, Cycling '74