Max API
8.0.2
|
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... | |
#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, | |
y | |||
) |
Find byte offset of a named member of a struct, relative to the beginning of that struct.
x | The name of the struct |
y | The name of the member |
Referenced by ext_main().
#define CLAMP | ( | a, | |
lo, | |||
hi | |||
) |
Limit values to within a specified range.
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. |
#define INRANGE | ( | v, | |
lo, | |||
hi | |||
) |
If a value is within the specified range, then return true.
Otherwise return false.
v | The value to test. |
lo | The low bound for the range. |
hi | The high bound for the range. |
#define MAX | ( | a, | |
b | |||
) |
Return the higher of two values.
a | The first value to compare. |
b | The second value to compare. |
Referenced by jit_matrix_frommatrix(), and jit_mop_io_restrict_dim().
#define MIN | ( | a, | |
b | |||
) |
Return the lower of two values.
a | The first value to compare. |
b | The second value to compare. |
#define structmembersize | ( | structname, | |
membername | |||
) |
Find size of a named member of a struct.
structname | The name of the struct |
membername | The name of the member |
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. |
Returned values from wind_advise()
Enumerator | |
---|---|
aaYes | Yes button was choosen. |
aaNo | No button was choosen. |
aaCancel | Cancel button was choosen. |
void classname_openrefpage_ext | ( | t_symbol * | classnamespace, |
char * | classname | ||
) |
Show the refpage for a given class.
classnamespace | The namespace for the class, e.g. "box". |
classname | The name of the class. |
void error_subscribe | ( | t_object * | x | ) |
Receive messages from the error handler.
x | The object to be subscribed to the error handler. |
Prior to calling error_subscribe(), you should bind the error message to an internal error handling routine:
Your error handling routine should be declared as follows:
void error_sym | ( | void * | x, |
t_symbol * | s | ||
) |
Posts an error message to the Max window.
This function is interrupt safe.
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.
x | The object to unsubscribe. |
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().
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. |
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.
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. |
void globalsymbol_unbind | ( | t_object * | x, |
C74_CONST char * | name, | ||
long | flags | ||
) |
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.
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().
void post_sym | ( | void * | x, |
t_symbol * | s | ||
) |
Posts a message to the Max window.
This function is interrupt safe.
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.
m | A function that will be called on Max exit. |
a | Argument to be used with method m. |
void quittask_remove | ( | method | m | ) |
Unregister a function previously registered with quittask_install().
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.
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.
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. |
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.
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. |
Strip quotes from the beginning and end of a symbol if they are present.
s | The symbol to be stipped. |
t_symbol* symbol_unique | ( | void | ) |
Performs an ASCII sort on an array of t_symbol *s.
Referenced by jit_object_exportattrs().
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..."
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. |
void wind_setcursor | ( | short | which | ) |
Change the cursor.
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 |
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.