Miscellaneous

Modules
	Console
	Byte Ordering
	Utilities for swapping the order of bytes to match the Endianness of the required platform.
	Extending expr
	If you want to use C-like variable expressions that are entered by a user of your object, you can use the "guts" of Max’s expr object in your object.
	Table Access
	You can use these functions to access named table objects.
	Text Editor Windows
	Max has a simple built-in text editor object that can display and edit text in conjunction with your object.
	Presets
	Max contains a preset object that has the ability to send preset messages to some or all of the objects (clients) in a Patcher window.
	Loading Max Files
	Several high-level functions permit you to load patcher files.
	Monitors and Displays
	Functions for finding our information about the environment.
	Windows
	Mouse and Keyboard

Macros
#define	INRANGE(v, lo, hi)
	If a value is within the specified range, then return true. More...
#define	MAX(a, b)
	Return the higher of two values. More...
#define	MIN(a, b)
	Return the lower of two values. More...
#define	CLAMP(a, lo, hi)
	Limit values to within a specified range. More...
#define	BEGIN_USING_C_LINKAGE
	Ensure that any definitions following this macro use a C-linkage, not a C++ linkage. More...
#define	END_USING_C_LINKAGE
	Close a definition section that was opened using BEGIN_USING_C_LINKAGE.
#define	calcoffset(x, y)
	Find byte offset of a named member of a struct, relative to the beginning of that struct. More...
#define	structmembersize(structname, membername)
	Find size of a named member of a struct. More...

Typedefs
typedef unsigned int	t_uint
	an unsigned int as defined by the architecture / platform
typedef char	t_int8
	a 1-byte int
typedef unsigned char	t_uint8
	an unsigned 1-byte int
typedef short	t_int16
	a 2-byte int
typedef unsigned short	t_uint16
	an unsigned 2-byte int
typedef int	t_int32
	a 4-byte int
typedef unsigned int	t_uint32
	an unsigned 4-byte int
typedef long long	t_int64
	an 8-byte int
typedef unsigned long long	t_uint64
	an unsigned 8-byte int
typedef t_uint32	t_fourcc
	an integer of suitable size to hold a four char code / identifier
typedef unsigned long	t_ptr_uint
	an unsigned pointer-sized int
typedef long	t_ptr_int
	a pointer-sized int
typedef float	t_atom_float
	the type that is an A_FLOAT in a t_atom
typedef short	t_getbytes_size
	like size_t but for getbytes()
typedef t_ptr_int	t_int
	an integer
typedef t_ptr_uint	t_ptr_size
	unsigned pointer-sized value for counting (like size_t)
typedef t_ptr_int	t_atom_long
	the type that is an A_LONG in a t_atom
typedef t_atom_long	t_max_err
	an integer value suitable to be returned as an error code
typedef char **	t_handle
	a handle (address of a pointer)
typedef char *	t_ptr
	a pointer
typedef t_uint8	t_bool
	a true/false variable
typedef t_int16	t_filepath
	i.e. path/vol in file APIs identifying a folder

Enumerations
enum	e_max_errorcodes {   MAX_ERR_NONE, MAX_ERR_GENERIC, MAX_ERR_INVALID_PTR, MAX_ERR_DUPLICATE,   MAX_ERR_OUT_OF_MEM }
	Standard values returned by function calls with a return type of t_max_err. More...
enum	e_max_wind_advise_result { aaYes, aaNo, aaCancel }
	Returned values from wind_advise() More...

Functions
BEGIN_USING_C_LINKAGE void *	globalsymbol_reference (t_object *x, C74_CONST char *name, C74_CONST char *classname)
	Get a reference to an object that is bound to a t_symbol. More...
void	globalsymbol_dereference (t_object *x, C74_CONST char *name, C74_CONST char *classname)
	Stop referencing an object that is bound to a t_symbol, previously referenced using globalsymbol_reference(). More...
t_max_err	globalsymbol_bind (t_object *x, C74_CONST char *name, long flags)
	Bind an object to a t_symbol. More...
void	globalsymbol_unbind (t_object *x, C74_CONST char *name, long flags)
	Remove an object from being bound to a t_symbol. More...
t_atom_long	method_true (void *x)
	A method that always returns true.
t_atom_long	method_false (void *x)
	A method that always returns false.
t_symbol *	symbol_unique (void)
	Generates a unique t_symbol *. More...
t_symbol *	symbol_stripquotes (t_symbol *s)
	Strip quotes from the beginning and end of a symbol if they are present. More...
void	error_sym (void *x, t_symbol *s)
	Posts an error message to the Max window. More...
void	post_sym (void *x, t_symbol *s)
	Posts a message to the Max window. More...
t_max_err	symbolarray_sort (long ac, t_symbol **av)
	Performs an ASCII sort on an array of t_symbol *s. More...
void	object_obex_quickref (void *x, long *numitems, t_symbol **items)
	Developers do not need to directly use the object_obex_quickref() function. More...
void	error_subscribe (t_object *x)
	Receive messages from the error handler. More...
void	error_unsubscribe (t_object *x)
	Remove an object as an error message recipient. More...
void	quittask_install (method m, void *a)
	Register a function that will be called when Max exits. More...
void	quittask_remove (method m)
	Unregister a function previously registered with quittask_install(). More...
short	maxversion (void)
	Determine version information about the current Max environment. More...
BEGIN_USING_C_LINKAGE char *	strncpy_zero (char *dst, const char *src, long size)
	Copy the contents of one string to another, in a manner safer than the standard strcpy() or strncpy(). More...
char *	strncat_zero (char *dst, const char *src, long size)
	Concatenate the contents of one string onto the end of another, in a manner safer than the standard strcat() or strncat(). More...
int	snprintf_zero (char *buffer, size_t count, const char *format,...)
	Copy the contents of a string together with value substitutions, in a manner safer than the standard sprintf() or snprintf(). More...
short	wind_advise (t_object *w, char *s,...)
	Throw a dialog which may have text and up to three buttons. More...
void	wind_setcursor (short which)
	Change the cursor. More...
void	classname_openrefpage_ext (t_symbol *classnamespace, char *classname)
	Show the refpage for a given class. More...

Detailed Description

Macro Definition Documentation

BEGIN_USING_C_LINKAGE

#define BEGIN_USING_C_LINKAGE

Ensure that any definitions following this macro use a C-linkage, not a C++ linkage.

The Max API uses C-linkage. This is important for objects written in C++ or that use a C++ compiler. This macro must be balanced with the END_USING_C_LINKAGE macro.

calcoffset

#define calcoffset	(		x,
			y
	)

Find byte offset of a named member of a struct, relative to the beginning of that struct.

Parameters

x	The name of the struct
y	The name of the member

Returns

A pointer-sized integer representing the number of bytes into the struct where the member begins.

Referenced by ext_main().

CLAMP

#define CLAMP	(		a,
			lo,
			hi
	)

Limit values to within a specified range.

Parameters

a	The value to constrain. NB: CLIP_ASSIGN modifies param 'a' but CLAMP only returns limited value
lo	The low bound for the range.
hi	The high bound for the range.

Returns

Returns the value a constrained to the range specified by lo and hi.

INRANGE

#define INRANGE	(		v,
			lo,
			hi
	)

If a value is within the specified range, then return true.

Otherwise return false.

Parameters

v	The value to test.
lo	The low bound for the range.
hi	The high bound for the range.

Returns

Returns true if within range, otherwise false.

MAX

#define MAX	(		a,
			b
	)

Return the higher of two values.

Parameters

a	The first value to compare.
b	The second value to compare.

Returns

Returns the higher of a or b.

Referenced by jit_matrix_frommatrix(), and jit_mop_io_restrict_dim().

MIN

#define MIN	(		a,
			b
	)

Return the lower of two values.

Parameters

a	The first value to compare.
b	The second value to compare.

Returns

Returns the lower of a or b.

structmembersize

#define structmembersize	(		structname,
			membername
	)

Find size of a named member of a struct.

Parameters

structname	The name of the struct
membername	The name of the member

Returns

The size of the member of the struct.

Enumeration Type Documentation

e_max_errorcodes

enum e_max_errorcodes

Standard values returned by function calls with a return type of t_max_err.

Enumerator
MAX_ERR_NONE	No error.
MAX_ERR_GENERIC	Generic error.
MAX_ERR_INVALID_PTR	Invalid Pointer.
MAX_ERR_DUPLICATE	Duplicate.
MAX_ERR_OUT_OF_MEM	Out of memory.

e_max_wind_advise_result

enum e_max_wind_advise_result

Returned values from wind_advise()

Enumerator
aaYes	Yes button was choosen.
aaNo	No button was choosen.
aaCancel	Cancel button was choosen.

Function Documentation

classname_openrefpage_ext()

void classname_openrefpage_ext	(	t_symbol *	classnamespace,
		char *	classname
	)

Show the refpage for a given class.

Parameters

classnamespace	The namespace for the class, e.g. "box".
classname	The name of the class.

error_subscribe()

void error_subscribe

(

t_object *

x

)

Receive messages from the error handler.

Parameters

x	The object to be subscribed to the error handler.

Remarks

error_subscribe() enables your object to receive a message (error), followed by the list of atoms in the error message posted to the Max window.

Prior to calling error_subscribe(), you should bind the error message to an internal error handling routine:

addmess((method)myobject_error, "error", A_GIMME, 0);

Your error handling routine should be declared as follows:

void myobject_error(t_myobject *x, t_symbol *s, short argc, t_atom *argv);

error_sym()

void error_sym	(	void *	x,
		t_symbol *	s
	)

Posts an error message to the Max window.

This function is interrupt safe.

Parameters

x	The object's pointer
s	Symbol to be posted as an error in the Max window

error_unsubscribe()

void error_unsubscribe

(

t_object *

x

)

Remove an object as an error message recipient.

Parameters

x	The object to unsubscribe.

globalsymbol_bind()

t_max_err globalsymbol_bind	(	t_object *	x,
		C74_CONST char *	name,
		long	flags
	)

Bind an object to a t_symbol.

Parameters

x	The object to bind to the t_symbol.
name	The name of the t_symbol to which the object will be bound.
flags	Pass 0.

Returns

A Max error code.

globalsymbol_dereference()

void globalsymbol_dereference	(	t_object *	x,
		C74_CONST char *	name,
		C74_CONST char *	classname
	)

Stop referencing an object that is bound to a t_symbol, previously referenced using globalsymbol_reference().

Parameters

x	The object that is getting the reference to the symbol.
name	The name of the symbol to reference.
classname	The name of the class of which the object we are referencing should be an instance.

See also

globalsymbol_reference()

globalsymbol_reference()

BEGIN_USING_C_LINKAGE void* globalsymbol_reference	(	t_object *	x,
		C74_CONST char *	name,
		C74_CONST char *	classname
	)

Get a reference to an object that is bound to a t_symbol.

Parameters

x	The object that is getting the reference to the symbol.
name	The name of the symbol to reference.
classname	The name of the class of which the object we are referencing should be an instance.

Returns

The s_thing of the t_symbol.

Remarks

An example of real-world use is to get the buffer~ object associated with a symbol.

// the struct of our object
typedef struct _myobject {
    t_object    obj;
    t_symbol    *buffer_name;
    t_buffer    *buffer_object;
} t_myobject;

void myobject_setbuffer(t_myobject *x, t_symbol *s, long argc, t_atom *argv)
{       
    if(s != x->buffer_name){
        // Reference the buffer associated with the incoming name
        x->buffer_object = (t_buffer *)globalsymbol_reference((t_object *)x, s->s_name, "buffer~");
        
        // If we were previously referencing another buffer, we should not longer reference it.
        globalsymbol_dereference((t_object *)x, x->buffer_name->s_name, "buffer~");
        
        x->buffer_name = s;
    }       
}

globalsymbol_unbind()

void globalsymbol_unbind	(	t_object *	x,
		C74_CONST char *	name,
		long	flags
	)

Remove an object from being bound to a t_symbol.

Parameters

x	The object from which to unbind the t_symbol.
name	The name of the t_symbol from which the object will be unbound.
flags	Pass 0.

maxversion()

short maxversion

(

void

)

Determine version information about the current Max environment.

This function returns the version number of Max. In Max versions 2.1.4 and later, this number is the version number of the Max kernel application in binary-coded decimal. Thus, 2.1.4 would return 214 hex or 532 decimal. Version 3.0 returns 300 hex.

Use this to check for the existence of particular function macros that are only present in more recent Max versions. Versions before 2.1.4 returned 1, except for versions 2.1.1 - 2.1.3 which returned 2.

Bit 14 (counting from left) will be set if Max is running as a standalone application, so you should mask the lower 12 bits to get the version number.

Returns

The Max environment's version number.

object_obex_quickref()

void object_obex_quickref	(	void *	x,
		long *	numitems,
		t_symbol **	items
	)

Developers do not need to directly use the object_obex_quickref() function.

It was used in Max 4 to add support for attributes to the quickref, but this is automatic in Max 5.

Referenced by ext_main().

post_sym()

void post_sym	(	void *	x,
		t_symbol *	s
	)

Posts a message to the Max window.

This function is interrupt safe.

Parameters

x	The object's pointer
s	Symbol to be posted in the Max window

quittask_install()

void quittask_install	(	method	m,
		void *	a
	)

Register a function that will be called when Max exits.

Parameters

m	A function that will be called on Max exit.
a	Argument to be used with method m.

Remarks

quittask_install() provides a mechanism for your external to register a routine to be called prior to Max shutdown. This is useful for objects that need to provide disk-based persistance outside the standard Max storage mechanisms, or need to shut down hardware or their connection to system software and cannot do so in the termination routine of a code fragment.

quittask_remove()

void quittask_remove

(

method

m

)

Unregister a function previously registered with quittask_install().

Parameters

m	Function to be removed as a shutdown method.

snprintf_zero()

int snprintf_zero	(	char *	buffer,
		size_t	count,
		const char *	format,
			...
	)

Copy the contents of a string together with value substitutions, in a manner safer than the standard sprintf() or snprintf().

This is the prefered function to use for this operation in Max.

Parameters

buffer	The destination string (already allocated) for the copy.
count	The number of chars allocated to the buffer string.
format	The source string that will be copied, which may include sprintf() formatting codes for substitutions.
...	An array of arguments to be substituted into the format string.

strncat_zero()

char* strncat_zero	(	char *	dst,
		const char *	src,
		long	size
	)

Concatenate the contents of one string onto the end of another, in a manner safer than the standard strcat() or strncat().

This is the prefered function to use for this operation in Max.

Parameters

dst	The destination string onto whose end the src string will be appended.
src	The source string that will be copied.
size	The number of chars allocated to the dst string.

strncpy_zero()

BEGIN_USING_C_LINKAGE char* strncpy_zero	(	char *	dst,
		const char *	src,
		long	size
	)

Copy the contents of one string to another, in a manner safer than the standard strcpy() or strncpy().

This is the prefered function to use for this operation in Max.

Parameters

dst	The destination string (already allocated) for the copy.
src	The source string that will be copied.
size	The number of chars allocated to the dst string.

symbol_stripquotes()

t_symbol* symbol_stripquotes

(

t_symbol *

s

)

Strip quotes from the beginning and end of a symbol if they are present.

Parameters

s	The symbol to be stipped.

Returns

Symbol with any leading/trailing quote pairs removed.

symbol_unique()

t_symbol* symbol_unique

(

void

)

Generates a unique t_symbol *.

The symbol will be formatted somewhat like "u123456789".

Returns

This function returns a unique t_symbol *.

symbolarray_sort()

t_max_err symbolarray_sort	(	long	ac,
		t_symbol **	av
	)

Performs an ASCII sort on an array of t_symbol *s.

Parameters

ac	The count of t_symbol *s in av
av	An array of t_symbol *s to be sorted

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_object_exportattrs().

wind_advise()

short wind_advise	(	t_object *	w,
		char *	s,
			...
	)

Throw a dialog which may have text and up to three buttons.

For example, this can be used to ask "Save changes before..."

Parameters

w	The window with which this dialog is associated.
s	A string with any sprintf()-like formatting to be displayed.
...	Any variables that should be substituted in the string defined by s.

Returns

One of the values defined in e_max_wind_advise_result, depending on what the user selected.

wind_setcursor()

void wind_setcursor

(

short

which

)

Change the cursor.

Parameters

which

One of the following predefined cursors: #define C_ARROW 1 #define C_WATCH 2 #define C_IBEAM 3 #define C_HAND 4 #define C_CROSS 5 #define C_PENCIL 6 #define C_GROW 8

Remarks

wind_setcursor() keeps track of what the cursor was previously set to, so if something else has changed the cursor, you may not see a new cursor if you set it to the previous argument to wind_setcursor().

The solution is to call wind_setcursor(0) before calling it with the desired cursor constant. Use wind_setcursor(-1) to tell Max you’ll set the cursor to your own cursor directly.