Max 5 API Reference

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

#define calcoffset ( x,
 )     ((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.
#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.
#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.
#define MAX ( a,
 )     ((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.
#define MIN ( a,
 )     ((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.

Enumeration Type Documentation

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.

Returned values from wind_advise().

Enumerator:
aaYes 

Yes button was choosen.

aaNo 

No button was choosen.

aaCancel 

Cancel button was choosen.


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

Copyright © 2008, Cycling '74