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 (char *name, method mnew, method mfree, long size, 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, method m, 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.

Definition at line 19 of file ext_obex.h.

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)

Definition at line 176 of file ext_mess.h.

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.

Referenced by jit_class_addattr().

t_max_err class_addmethod	(	t_class *	c,
		method	m,
		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.

Referenced by jit_class_addmethod(), and jit_class_new().

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.

Referenced by jit_class_findbyname().

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.

Referenced by jit_class_free().

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 *.

Referenced by jit_class_nameget().

t_class* class_new	(	char *	name,
		method	mnew,
		method	mfree,
		long	size,
		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.

Referenced by jit_class_new().

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.

Referenced by jit_class_register().

Classes

Data Structures

Modules

Defines

Enumerations

Functions

Detailed Description

Define Documentation

Enumeration Type Documentation

Function Documentation