Miscellaneous

Collaboration diagram for 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.
	Event and File Serial Numbers
	If you call outlet_int(), outlet_float(), outlet_list(), or outlet_anything() inside a Qelem or during some idle or interrupt time, you should increment Max’s Event Serial Number beforehand.
	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
Defines
#define	InRange(v, lo, hi) ((v)<=(hi)&&(v)>=(lo))
	If a value is within the specified range, then return true.
#define	MAX(a, b) ((a)>(b)?(a):(b))
	Return the higher of two values.
#define	MIN(a, b) ((a)<(b)?(a):(b))
	Return the lower of two values.
#define	CLIP(a, lo, hi) ( (a)>(lo)?( (a)<(hi)?(a):(hi) ):(lo) )
	Limit values to within a specified range.
#define	calcoffset(x, y) ((long)(&(((x *)0L)->y)))
	Find byte offset of a named member of a struct, relative to the beginning of that struct.
#define	BEGIN_USING_C_LINKAGE
	Ensure that any definitions following this macro use a C-linkage, not a C++ linkage.
#define	END_USING_C_LINKAGE
	Close a definition section that was opened using BEGIN_USING_C_LINKAGE.
Enumerations
enum	e_max_errorcodes { MAX_ERR_NONE = 0, MAX_ERR_GENERIC = -1, MAX_ERR_INVALID_PTR = -2, MAX_ERR_DUPLICATE = -3, MAX_ERR_OUT_OF_MEM = -4 }
	Standard values returned by function calls with a return type of t_max_err. More...
enum	e_max_wind_advise_result { aaYes = 1, aaNo, aaCancel }
	Returned values from wind_advise(). More...
Functions
void *	globalsymbol_reference (t_object x, char name, char *classname)
	Get a reference to an object that is bound to a t_symbol.
void	globalsymbol_dereference (t_object x, char name, char *classname)
	Stop referencing an object that is bound to a t_symbol, previously referenced using globalsymbol_reference().
t_max_err	globalsymbol_bind (t_object x, char name, long flags)
	Bind an object to a t_symbol.
void	globalsymbol_unbind (t_object x, char name, long flags)
	Remove an object from being bound to a t_symbol.
long	method_true (void *x)
	A method that always returns true.
long	method_false (void *x)
	A method that always returns false.
t_symbol *	symbol_unique ()
	Generates a unique t_symbol *.
void	error_sym (void x, t_symbol s)
	Posts an error message to the Max window.
void	post_sym (void x, t_symbol s)
	Posts a message to the Max window.
t_max_err	symbolarray_sort (long ac, t_symbol **av)
	Performs an ASCII sort on an array of t_symbol *s.
void	object_obex_quickref (void x, long numitems, t_symbol **items)
	Developers do not need to directly use the object_obex_quickref() function.
void	error_subscribe (t_object *x)
	Receive messages from the error handler.
void	error_unsubscribe (t_object *x)
	Remove an object as an error message recipient.
void	quittask_install (method m, void *a)
	Register a function that will be called when Max exits.
void	quittask_remove (method m)
	Unregister a function previously registered with quittask_install().
short	maxversion (void)
	Determine version information about the current Max environment.
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().
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().
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().
short	wind_advise (t_object w, char s,...)
	Throw a dialog which may have text and up to three buttons.
void	wind_setcursor (short which)
	Change the cursor.

Define Documentation

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

Definition at line 29 of file ext_prefix.h.

#define calcoffset	(	x,
		y		)	((long)(&(((x *)0L)->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 long integer representing the number of bytes into the struct where the member begins.

Definition at line 89 of file ext_obex.h.

Referenced by jit_ob3d_setup().

#define CLIP	(	a,
		lo,
		hi	)	( (a)>(lo)?( (a)<(hi)?(a):(hi) ):(lo) )

Limit values to within a specified range.

Parameters:

	a	The value to constrain.
	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.

Definition at line 53 of file ext_common.h.

Referenced by jit_atom_getcharfix(), jit_matrix_fromgworld(), jit_matrix_setall(), jit_matrix_togworld(), and jit_mop_io_restrict_planecount().

#define InRange	(	v,
		lo,
		hi	)	((v)<=(hi)&&(v)>=(lo))

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.

Definition at line 15 of file ext_common.h.

#define MAX	(	a,
		b		)	((a)>(b)?(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.

Definition at line 27 of file ext_common.h.

Referenced by jit_matrix_frommatrix(), jit_mop_io_restrict_dim(), and jit_qt_movie_matrix_calc().

#define MIN	(	a,
		b		)	((a)<(b)?(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.

Definition at line 40 of file ext_common.h.

Referenced by jit_gl_texcoord1f(), jit_gl_texcoord1fv(), jit_gl_texcoord2f(), jit_gl_texcoord2fv(), jit_gl_texcoord3f(), jit_gl_texcoord3fv(), jit_matrix_fromgworld(), jit_matrix_togworld(), and jit_qt_utils_str2type().

Enumeration Type Documentation

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.

Definition at line 52 of file ext_obex.h.

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.

Definition at line 15 of file ext_wind.h.

Function Documentation

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);

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

void error_unsubscribe ( t_object * x )

Remove an object as an error message recipient.

Parameters:

x

The object to unsubscribe.

t_max_err globalsymbol_bind	(	t_object *	x,
		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.

void globalsymbol_dereference	(	t_object *	x,
		char *	name,
		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()

void* globalsymbol_reference	(	t_object *	x,
		char *	name,
		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 referenceing another buffer, we should not longer reference it.
            globalsymbol_dereference((t_object *)x, x->buffer_name->s_name, "buffer~");
            
            x->buffer_name = s;
        }       
    }

void globalsymbol_unbind	(	t_object *	x,
		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.

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.

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.

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

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.

void quittask_remove ( method m )

Unregister a function previously registered with quittask_install().

Parameters:

m

Function to be removed as a shutdown method.

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.

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.

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.

Referenced by db_open(), and db_query_table_new().

t_symbol* symbol_unique ( )

Generates a unique t_symbol *.

The symbol will be formatted somewhat like "u123456789".

Returns:: This function returns a unique t_symbol *.

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(), jit_qt_codec_getcodeclist_audio(), jit_qt_codec_getcodeclist_gfx(), and jit_qt_codec_getcodeclist_video().

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.

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.

Miscellaneous

Modules

Defines

Enumerations

Functions

Define Documentation

Enumeration Type Documentation

Function Documentation