Max 5 API Reference

Objects

More information for this section can be gleaned from the pattrsdk.pdf in the Max 4.5.5 SDK. More...

Data Structures

struct  t_messlist
 A list of symbols and their corresponding methods, complete with typechecking information. More...
struct  t_tinyobject
 The tiny object structure sits at the head of any object to which you may pass messages (and which you may feed to freeobject()). More...
struct  t_object
 The structure for the head of any object which wants to have inlets or outlets, or support attributes. More...

Defines

#define MAGIC   1758379419L
 Magic number used to determine if memory pointed to by a t_object* is valid.
#define NOGOOD(x)   (((struct object *)x)->o_magic != MAGIC)
 Returns true if a pointer is not a valid object.
#define MAXARG   7
 Maximum number of arguments that can be passed as a typed-list rather than using A_GIMME.

Functions

t_objectnewobject_sprintf (t_object *patcher, char *fmt,...)
 Create a new object in a specified patcher with values using a combination of attribute and sprintf syntax.
t_objectnewobject_fromdictionary (t_object *patcher, t_dictionary *d)
 Place a new object into a patcher.
long object_classname_compare (void *x, t_symbol *name)
 Determines if a particular object is an instance of a given class.
void * object_alloc (t_class *c)
 Allocates the memory for an instance of an object class and initialize its object header.
void * object_new (t_symbol *name_space, t_symbol *classname,...)
 Allocates the memory for an instance of an object class and initialize its object header internal to Max.
void * object_new_typed (t_symbol *name_space, t_symbol *classname, long ac, t_atom *av)
 Allocates the memory for an instance of an object class and initialize its object header internal to Max.
t_max_err object_free (void *x)
 Call the free function and release the memory for an instance of an internal object class previously instantiated using object_new(), object_new_typed() or other new-style object constructor functions (e.g.
void * object_method (void *x, t_symbol *s,...)
 Sends an untyped message to an object.
t_max_err object_method_typed (void *x, t_symbol *s, long ac, t_atom *av, t_atom *rv)
 Sends a type-checked message to an object.
t_max_err object_method_typedfun (void *x, t_messlist *mp, t_symbol *s, long ac, t_atom *av, t_atom *rv)
 Currently undocumented.
method object_getmethod (void *x, t_symbol *s)
 Retrieves an object's method for a particular message selector.
t_symbolobject_classname (void *x)
 Retrieves an object instance's class name.
void * object_register (t_symbol *name_space, t_symbol *s, void *x)
 Registers an object in a namespace.
void * object_findregistered (t_symbol *name_space, t_symbol *s)
 Determines a registered object's pointer, given its namespace and name.
t_max_err object_findregisteredbyptr (t_symbol **name_space, t_symbol **s, void *x)
 Determines the namespace and/or name of a registered object, given the object's pointer.
void * object_attach (t_symbol *name_space, t_symbol *s, void *x)
 Attaches a client to a registered object.
t_max_err object_detach (t_symbol *name_space, t_symbol *s, void *x)
 Detach a client from a registered object.
t_max_err object_attach_byptr (void *x, void *registeredobject)
 Attaches a client to a registered object.
t_max_err object_attach_byptr_register (void *x, void *object_to_attach, t_symbol *reg_name_space)
 A convenience function wrapping object_register() and object_attach_byptr().
t_max_err object_detach_byptr (void *x, void *registeredobject)
 Detach a client from a registered object.
t_max_err object_unregister (void *x)
 Removes a registered object from a namespace.
t_max_err object_notify (void *x, t_symbol *s, void *data)
 Broadcast a message (with an optional argument) from a registered object to any attached client objects.
t_classobject_class (void *x)
 Determines the class of a given object.
t_max_err object_getvalueof (void *x, long *ac, t_atom **av)
 Retrieves the value of an object which supports the getvalueof/setvalueof interface.
t_max_err object_setvalueof (void *x, long ac, t_atom *av)
 Sets the value of an object which supports the getvalueof/setvalueof interface.
t_max_err object_obex_lookup (void *x, t_symbol *key, t_object **val)
 Retrieves the value of a data stored in the obex.
t_max_err object_obex_store (void *x, t_symbol *key, t_object *val)
 Stores data in the object's obex.
void object_obex_dumpout (void *x, t_symbol *s, long argc, t_atom *argv)
 Sends data from the object's dumpout outlet.
t_dictionaryobject_dictionaryarg (long ac, t_atom *av)
 Retrieve a pointer to a dictionary passed in as an atom argument.
t_max_err object_method_parse (t_object *x, t_symbol *s, char *parsestr, t_atom *rv)
 Convenience wrapper for object_method_typed() that uses atom_setparse() to define the arguments.
t_max_err object_method_format (t_object *x, t_symbol *s, t_atom *rv, char *fmt,...)
 Convenience wrapper for object_method_typed() that uses atom_setformat() to define the arguments.
t_max_err object_method_char (t_object *x, t_symbol *s, unsigned char v, t_atom *rv)
 Convenience wrapper for object_method_typed() that passes a single char as an argument.
t_max_err object_method_long (t_object *x, t_symbol *s, long v, t_atom *rv)
 Convenience wrapper for object_method_typed() that passes a single long integer as an argument.
t_max_err object_method_float (t_object *x, t_symbol *s, float v, t_atom *rv)
 Convenience wrapper for object_method_typed() that passes a single 32bit float as an argument.
t_max_err object_method_double (t_object *x, t_symbol *s, double v, t_atom *rv)
 Convenience wrapper for object_method_typed() that passes a single 64bit float as an argument.
t_max_err object_method_sym (t_object *x, t_symbol *s, t_symbol *v, t_atom *rv)
 Convenience wrapper for object_method_typed() that passes a single t_symbol* as an argument.
t_max_err object_method_obj (t_object *x, t_symbol *s, t_object *v, t_atom *rv)
 Convenience wrapper for object_method_typed() that passes a single t_object* as an argument.
t_max_err object_method_char_array (t_object *x, t_symbol *s, long ac, unsigned char *av, t_atom *rv)
 Convenience wrapper for object_method_typed() that passes an array of char values as an argument.
t_max_err object_method_long_array (t_object *x, t_symbol *s, long ac, long *av, t_atom *rv)
 Convenience wrapper for object_method_typed() that passes an array of long integers values as an argument.
t_max_err object_method_float_array (t_object *x, t_symbol *s, long ac, float *av, t_atom *rv)
 Convenience wrapper for object_method_typed() that passes an array of 32bit floats values as an argument.
t_max_err object_method_double_array (t_object *x, t_symbol *s, long ac, double *av, t_atom *rv)
 Convenience wrapper for object_method_typed() that passes an array of 64bit float values as an argument.
t_max_err object_method_sym_array (t_object *x, t_symbol *s, long ac, t_symbol **av, t_atom *rv)
 Convenience wrapper for object_method_typed() that passes an array of t_symbol* values as an argument.
t_max_err object_method_obj_array (t_object *x, t_symbol *s, long ac, t_object **av, t_atom *rv)
 Convenience wrapper for object_method_typed() that passes an array of t_object* values as an argument.
void object_openhelp (t_object *x)
 Open the help patcher for a given instance of an object.
void object_openrefpage (t_object *x)
 Open the reference page for a given instance of an object.
void object_openquery (t_object *x)
 Open a search in the file browser for files with the name of the given object.
void classname_openhelp (char *classname)
 Open the help patcher for a given object class name.
void classname_openrefpage (char *classname)
 Open the reference page for a given object class name.
void classname_openquery (char *classname)
 Open a search in the file browser for files with the name of the given class.

Detailed Description

More information for this section can be gleaned from the pattrsdk.pdf in the Max 4.5.5 SDK.

See also:
http://www.cycling74.com/twiki/bin/view/ProductDocumentation/JitterSdkObjectModel
http://www.cycling74.com/twiki/bin/view/ProductDocumentation/JitterSdkRegNotify

Define Documentation

#define MAXARG   7

Maximum number of arguments that can be passed as a typed-list rather than using A_GIMME.

It is generally recommended to use A_GIMME.


Function Documentation

void classname_openhelp ( char *  classname  ) 

Open the help patcher for a given object class name.

Parameters:
classname The class name for which to open the help patcher.
void classname_openquery ( char *  classname  ) 

Open a search in the file browser for files with the name of the given class.

Parameters:
classname The class name for which to query.
void classname_openrefpage ( char *  classname  ) 

Open the reference page for a given object class name.

Parameters:
classname The class name for which to open the reference page.
t_object* newobject_fromdictionary ( t_object patcher,
t_dictionary d 
)

Place a new object into a patcher.

The new object will be created based on a specification contained in a Dictionary.

Create a new dictionary populated with values using a combination of attribute and sprintf syntax.

Parameters:
patcher An instance of a patcher object.
d A dictionary containing an object specification.
Returns:
A pointer to the newly created object instance, or NULL if creation of the object fails.
Remarks:
Max attribute syntax is used to define key-value pairs. For example,
    "@key1 value @key2 another_value"
The example below creates a new object that in a patcher whose object pointer is stored in a variable called "aPatcher".
    t_dictionary *d;
    t_object *o;
    char text[4];
    
    strncpy_zero(text, "foo", 4);

    d = dictionary_sprintf("@maxclass comment @varname _name \
        @text \"%s\" @patching_rect %.2f %.2f %.2f %.2f \
        @fontsize %f @textcolor %f %f %f 1.0 \
        @fontname %s @bgcolor 0.001 0.001 0.001 0.",
        text, 20.0, 20.0, 200.0, 24.0,
        18, 0.9, 0.9, 0.9, "Arial");
    
    o = newobject_fromdictionary(aPatcher, d);
See also:
newobject_sprintf()
newobject_fromdictionary()
atom_setparse()
t_object* newobject_sprintf ( t_object patcher,
char *  fmt,
  ... 
)

Create a new object in a specified patcher with values using a combination of attribute and sprintf syntax.

Parameters:
patcher An instance of a patcher object.
fmt An sprintf-style format string specifying key-value pairs with attribute nomenclature.
... One or more arguments which are to be substituted into the format string.
Returns:
A pointer to the newly created object instance, or NULL if creation of the object fails.
Remarks:
Max attribute syntax is used to define key-value pairs. For example,
    "@key1 value @key2 another_value"
The example below creates a new object that in a patcher whose object pointer is stored in a variable called "aPatcher".
    t_object *my_comment;
    char text[4];
    
    strncpy_zero(text, "foo", 4);

    my_comment = newobject_sprintf(aPatcher, "@maxclass comment @varname _name \
        @text \"%s\" @patching_rect %.2f %.2f %.2f %.2f \
        @fontsize %f @textcolor %f %f %f 1.0 \
        @fontname %s @bgcolor 0.001 0.001 0.001 0.",
        text, 20.0, 20.0, 200.0, 24.0,
        18, 0.9, 0.9, 0.9, "Arial");
See also:
dictionary_sprintf()
newobject_fromdictionary()
atom_setparse()
void* object_alloc ( t_class c  ) 

Allocates the memory for an instance of an object class and initialize its object header.

It is used like the traditional function newobject, inside of an object's new method, but its use is required with obex-class objects.

Parameters:
c The class pointer, returned by class_new()
Returns:
This function returns a new instance of an object class if successful, or NULL if unsuccessful.
void* object_attach ( t_symbol name_space,
t_symbol s,
void *  x 
)

Attaches a client to a registered object.

Once attached, the object will receive notifications sent from the registered object (via the object_notify() function), if it has a notify method defined and implemented.

Parameters:
name_space The namespace of the registered object. This should be the same value used in object_register() to register the object. If you don't know the registered object's namespace, the object_findregisteredbyptr() function can be used to determine it.
s The name of the registered object in the namespace. If you don't know the name of the registered object, the object_findregisteredbyptr() function can be used to determine it.
x The client object to attach. Generally, this is the pointer to your Max object.
Returns:
This function returns a pointer to the registered object (to the object referred to by the combination of name_space and s arguments) if successful, or NULL if unsuccessful.
Remarks:
You should not attach an object to itself if the object is a UI object. UI objects automatically register and attach to themselves in jbox_new().
See also:
object_notify()
object_detach()
object_attach_byptr()
object_register()
t_max_err object_attach_byptr ( void *  x,
void *  registeredobject 
)

Attaches a client to a registered object.

Unlike object_attach(), the client is specified by providing a pointer to that object rather than the registered name of that object.

Once attached, the object will receive notifications sent from the registered object (via the object_notify() function), if it has a notify method defined and implemented.

Parameters:
x The attaching client object. Generally, this is the pointer to your Max object.
registeredobject A pointer to the registered object to which you wish to attach.
Returns:
A Max error code.
Remarks:
You should not attach an object to itself if the object is a UI object. UI objects automatically register and attach to themselves in jbox_new().
See also:
object_notify()
object_detach()
object_attach()
object_register()
object_attach_byptr_register()
t_max_err object_attach_byptr_register ( void *  x,
void *  object_to_attach,
t_symbol reg_name_space 
)

A convenience function wrapping object_register() and object_attach_byptr().

Parameters:
x The attaching client object. Generally, this is the pointer to your Max object.
object_to_attach A pointer to the object to which you wish to registered and then to which to attach.
reg_name_space The namespace in which to register the object_to_attach.
Returns:
A Max error code.
See also:
object_register()
object_attach_byptr()
t_class* object_class ( void *  x  ) 

Determines the class of a given object.

Parameters:
x The object to test
Returns:
This function returns the t_class * of the object's class, if successful, or NULL, if unsuccessful.
t_symbol* object_classname ( void *  x  ) 

Retrieves an object instance's class name.

Parameters:
x The object instance whose class name is being queried
Returns:
The classname, or NULL if unsuccessful.
long object_classname_compare ( void *  x,
t_symbol name 
)

Determines if a particular object is an instance of a given class.

Parameters:
x The object to test
name The name of the class to test this object against
Returns:
This function returns 1 if the object is an instance of the named class. Otherwise, 0 is returned.
Remarks:
For instance, to determine whether an unknown object pointer is a pointer to a print object, one would call:
    long isprint = object_classname_compare(x, gensym("print"));
t_max_err object_detach ( t_symbol name_space,
t_symbol s,
void *  x 
)

Detach a client from a registered object.

Parameters:
name_space The namespace of the registered object. This should be the same value used in object_register() to register the object. If you don't know the registered object's namespace, the object_findregisteredbyptr() function can be used to determine it.
s The name of the registered object in the namespace. If you don't know the name of the registered object, the object_findregisteredbyptr() function can be used to determine it.
x The client object to attach. Generally, this is the pointer to your Max object.
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 object_detach_byptr ( void *  x,
void *  registeredobject 
)

Detach a client from a registered object.

Parameters:
x The attaching client object. Generally, this is the pointer to your Max object.
registeredobject The object from which to detach.
Returns:
A Max error code.
See also:
object_detach()
object_attach_byptr()
t_dictionary* object_dictionaryarg ( long  ac,
t_atom av 
)

Retrieve a pointer to a dictionary passed in as an atom argument.

Use this function when working with classes that have dictionary constructors to fetch the dictionary.

Parameters:
ac The number of atoms.
av A pointer to the first atom in the array.
Returns:
The dictionary retrieved from the atoms.
See also:
attr_dictionary_process()
void* object_findregistered ( t_symbol name_space,
t_symbol s 
)

Determines a registered object's pointer, given its namespace and name.

Parameters:
name_space The namespace of the registered object
s The name of the registered object in the namespace
Returns:
This function returns the pointer of the registered object, if successful, or NULL, if unsuccessful.
t_max_err object_findregisteredbyptr ( t_symbol **  name_space,
t_symbol **  s,
void *  x 
)

Determines the namespace and/or name of a registered object, given the object's pointer.

Parameters:
name_space Pointer to a t_symbol *, to receive the namespace of the registered object
s Pointer to a t_symbol *, to receive the name of the registered object within the namespace
x Pointer to the registered object
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 object_free ( void *  x  ) 

Call the free function and release the memory for an instance of an internal object class previously instantiated using object_new(), object_new_typed() or other new-style object constructor functions (e.g.

hashtab_new()). It is, at the time of this writing, a wrapper for the traditional function freeobject(), but its use is suggested with obex-class objects.

Parameters:
x The pointer to the object to be freed.
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.
method object_getmethod ( void *  x,
t_symbol s 
)

Retrieves an object's method for a particular message selector.

Parameters:
x The object whose method is being queried
s The message selector
Returns:
This function returns the method if successful, or 0 if unsuccessful.
t_max_err object_getvalueof ( void *  x,
long *  ac,
t_atom **  av 
)

Retrieves the value of an object which supports the getvalueof/setvalueof interface.

See part 2 of the pattr SDK for more information on this interface.

Parameters:
x The object whose value is of interest
ac Pointer to a long variable to receive the count of arguments in av. The long variable itself should be set to 0 previous to calling this function.
av Pointer to a t_atom *, to receive object data. The t_atom * itself should be set to NULL previous to calling this function.
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:
Calling the object_getvalueof() function allocates memory for any data it returns. It is the developer's responsibility to free it, using the freebytes() function.
Developers wishing to design objects which will support this function being called on them must define and implement a special method, getvalueof, like so:
    class_addmethod(c, (method)myobject_getvalueof, "getvalueof", A_CANT, 0);
The getvalueof method should be prototyped as:
    t_max_err myobject_getvalueof(t_myobject *x, long *ac, t_atom **av);
And implemented, generally, as:
    t_max_err myobj_getvalueof(t_myobj *x, long *ac, t_atom **av) 
    {
        if (ac && av) {
            if (*ac && *av) {
                // memory has been passed in; use it.
            } else {
                // allocate enough memory for your data
                *av = (t_atom *)getbytes(sizeof(t_atom));
            }
            *ac = 1; // our data is a single floating point value
            atom_setfloat(*av, x->objvalue);
        }
        return MAX_ERR_NONE;
    }

    @remark         By convention, and to permit the interoperability of objects using the obex API, 
                    developers should allocate memory in their <tt>getvalueof</tt> methods using the getbytes() function. 
void* object_method ( void *  x,
t_symbol s,
  ... 
)

Sends an untyped message to an object.

Parameters:
x The object that will receive the message
s The message selector
... Any arguments to the message
Returns:
If the receiver object can respond to the message, object_method() returns the result. Otherwise, the function will return 0.
Remarks:
Example: To send the message bang to the object bang_me:
    void *bang_result;
    bang_result = object_method(bang_me, gensym("bang"));
t_max_err object_method_char ( t_object x,
t_symbol s,
unsigned char  v,
t_atom rv 
)

Convenience wrapper for object_method_typed() that passes a single char as an argument.

Parameters:
x The object to which the message will be sent.
s The name of the method to call on the object.
v An argument to pass to the method.
rv The address of an atom to hold a return value.
Returns:
A Max error code.
See also:
object_method_typed()
t_max_err object_method_char_array ( t_object x,
t_symbol s,
long  ac,
unsigned char *  av,
t_atom rv 
)

Convenience wrapper for object_method_typed() that passes an array of char values as an argument.

Parameters:
x The object to which the message will be sent.
s The name of the method to call on the object.
ac The number of arguments to pass to the method.
av The address of the first of the array of arguments to pass to the method.
rv The address of an atom to hold a return value.
Returns:
A Max error code.
See also:
object_method_typed()
t_max_err object_method_double ( t_object x,
t_symbol s,
double  v,
t_atom rv 
)

Convenience wrapper for object_method_typed() that passes a single 64bit float as an argument.

Parameters:
x The object to which the message will be sent.
s The name of the method to call on the object.
v An argument to pass to the method.
rv The address of an atom to hold a return value.
Returns:
A Max error code.
See also:
object_method_typed()
t_max_err object_method_double_array ( t_object x,
t_symbol s,
long  ac,
double *  av,
t_atom rv 
)

Convenience wrapper for object_method_typed() that passes an array of 64bit float values as an argument.

Parameters:
x The object to which the message will be sent.
s The name of the method to call on the object.
ac The number of arguments to pass to the method.
av The address of the first of the array of arguments to pass to the method.
rv The address of an atom to hold a return value.
Returns:
A Max error code.
See also:
object_method_typed()
t_max_err object_method_float ( t_object x,
t_symbol s,
float  v,
t_atom rv 
)

Convenience wrapper for object_method_typed() that passes a single 32bit float as an argument.

Parameters:
x The object to which the message will be sent.
s The name of the method to call on the object.
v An argument to pass to the method.
rv The address of an atom to hold a return value.
Returns:
A Max error code.
See also:
object_method_typed()
t_max_err object_method_float_array ( t_object x,
t_symbol s,
long  ac,
float *  av,
t_atom rv 
)

Convenience wrapper for object_method_typed() that passes an array of 32bit floats values as an argument.

Parameters:
x The object to which the message will be sent.
s The name of the method to call on the object.
ac The number of arguments to pass to the method.
av The address of the first of the array of arguments to pass to the method.
rv The address of an atom to hold a return value.
Returns:
A Max error code.
See also:
object_method_typed()
t_max_err object_method_format ( t_object x,
t_symbol s,
t_atom rv,
char *  fmt,
  ... 
)

Convenience wrapper for object_method_typed() that uses atom_setformat() to define the arguments.

Parameters:
x The object to which the message will be sent.
s The name of the method to call on the object.
rv The address of an atom to hold a return value.
fmt An sprintf-style format string specifying values for the atoms.
... One or more arguments which are to be substituted into the format string.
Returns:
A Max error code.
See also:
object_method_typed()
atom_setformat()
t_max_err object_method_long ( t_object x,
t_symbol s,
long  v,
t_atom rv 
)

Convenience wrapper for object_method_typed() that passes a single long integer as an argument.

Parameters:
x The object to which the message will be sent.
s The name of the method to call on the object.
v An argument to pass to the method.
rv The address of an atom to hold a return value.
Returns:
A Max error code.
See also:
object_method_typed()
t_max_err object_method_long_array ( t_object x,
t_symbol s,
long  ac,
long *  av,
t_atom rv 
)

Convenience wrapper for object_method_typed() that passes an array of long integers values as an argument.

Parameters:
x The object to which the message will be sent.
s The name of the method to call on the object.
ac The number of arguments to pass to the method.
av The address of the first of the array of arguments to pass to the method.
rv The address of an atom to hold a return value.
Returns:
A Max error code.
See also:
object_method_typed()
t_max_err object_method_obj ( t_object x,
t_symbol s,
t_object v,
t_atom rv 
)

Convenience wrapper for object_method_typed() that passes a single t_object* as an argument.

Parameters:
x The object to which the message will be sent.
s The name of the method to call on the object.
v An argument to pass to the method.
rv The address of an atom to hold a return value.
Returns:
A Max error code.
See also:
object_method_typed()
t_max_err object_method_obj_array ( t_object x,
t_symbol s,
long  ac,
t_object **  av,
t_atom rv 
)

Convenience wrapper for object_method_typed() that passes an array of t_object* values as an argument.

Parameters:
x The object to which the message will be sent.
s The name of the method to call on the object.
ac The number of arguments to pass to the method.
av The address of the first of the array of arguments to pass to the method.
rv The address of an atom to hold a return value.
Returns:
A Max error code.
See also:
object_method_typed()
t_max_err object_method_parse ( t_object x,
t_symbol s,
char *  parsestr,
t_atom rv 
)

Convenience wrapper for object_method_typed() that uses atom_setparse() to define the arguments.

Parameters:
x The object to which the message will be sent.
s The name of the method to call on the object.
parsestr A C-string to parse into an array of atoms to pass to the method.
rv The address of an atom to hold a return value.
Returns:
A Max error code.
See also:
object_method_typed()
atom_setparse()
t_max_err object_method_sym ( t_object x,
t_symbol s,
t_symbol v,
t_atom rv 
)

Convenience wrapper for object_method_typed() that passes a single t_symbol* as an argument.

Parameters:
x The object to which the message will be sent.
s The name of the method to call on the object.
v An argument to pass to the method.
rv The address of an atom to hold a return value.
Returns:
A Max error code.
See also:
object_method_typed()
t_max_err object_method_sym_array ( t_object x,
t_symbol s,
long  ac,
t_symbol **  av,
t_atom rv 
)

Convenience wrapper for object_method_typed() that passes an array of t_symbol* values as an argument.

Parameters:
x The object to which the message will be sent.
s The name of the method to call on the object.
ac The number of arguments to pass to the method.
av The address of the first of the array of arguments to pass to the method.
rv The address of an atom to hold a return value.
Returns:
A Max error code.
See also:
object_method_typed()
t_max_err object_method_typed ( void *  x,
t_symbol s,
long  ac,
t_atom av,
t_atom rv 
)

Sends a type-checked message to an object.

Parameters:
x The object that will receive the message
s The message selector
ac Count of message arguments in av
av Array of t_atoms; the message arguments
rv Return value of function, if available
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:
If the receiver object can respond to the message, object_method_typed() returns the result in rv. Otherwise, rv will contain an A_NOTHING atom.
t_max_err object_method_typedfun ( void *  x,
t_messlist mp,
t_symbol s,
long  ac,
t_atom av,
t_atom rv 
)

Currently undocumented.

Parameters:
x The object that will receive the message
mp Undocumented
s The message selector
ac Count of message arguments in av
av Array of t_atoms; the message arguments
rv Return value of function, if available
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:
If the receiver object can respond to the message, object_method_typedfun() returns the result in rv. Otherwise, rv will contain an A_NOTHING atom.
void* object_new ( t_symbol name_space,
t_symbol classname,
  ... 
)

Allocates the memory for an instance of an object class and initialize its object header internal to Max.

It is used similarly to the traditional function newinstance(), but its use is required with obex-class objects.

Parameters:
name_space The desired object'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 of the object to be created
... Any arguments expected by the object class being instantiated
Returns:
This function returns a new instance of the object class if successful, or NULL if unsuccessful.
void* object_new_typed ( t_symbol name_space,
t_symbol classname,
long  ac,
t_atom av 
)

Allocates the memory for an instance of an object class and initialize its object header internal to Max.

It is used similarly to the traditional function newinstance(), but its use is required with obex-class objects. The object_new_typed() function differs from object_new() by its use of an atom list for object arguments—in this way, it more resembles the effect of typing something into an object box from the Max interface.

Parameters:
name_space The desired object'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 of the object to be created
ac Count of arguments in av
av Array of t_atoms; arguments to the class's instance creation function.
Returns:
This function returns a new instance of the object class if successful, or NULL if unsuccessful.
t_max_err object_notify ( void *  x,
t_symbol s,
void *  data 
)

Broadcast a message (with an optional argument) from a registered object to any attached client objects.

Parameters:
x Pointer to the registered object
s The message to send
data An optional argument which will be passed with the message. Sets this argument to NULL if it will be unused.
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:
In order for client objects to receive notifications, they must define and implement a special method, notify, like so:
    class_addmethod(c, (method)myobject_notify, "notify", A_CANT, 0);
The notify method should be prototyped as:
    void myobject_notify(t_myobject *x, t_symbol *s, t_symbol *msg, void *sender, void *data);
where x is the pointer to the receiving object, s is the name of the sending (registered) object in its namespace, msg is the sent message, sender is the pointer to the sending object, and data is an optional argument sent with the message. This value corresponds to the data argument in the object_notify() method.
void object_obex_dumpout ( void *  x,
t_symbol s,
long  argc,
t_atom argv 
)

Sends data from the object's dumpout outlet.

The dumpout outlet is stored in the obex using the object_obex_store() function (see above). It is used approximately like outlet_anything().

Parameters:
x The object pointer. This function should only be called on instantiated objects (i.e. in the new method or later), not directly on classes (i.e. in main()).
s The message selector t_symbol *
argc Number of elements in the argument list in argv
argv t_atoms constituting the message arguments
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 object_obex_lookup ( void *  x,
t_symbol key,
t_object **  val 
)

Retrieves the value of a data stored in the obex.

Parameters:
x The object pointer. This function should only be called on instantiated objects (i.e. in the new method or later), not directly on classes (i.e. in main()).
key The symbolic name for the data to be retrieved
val A pointer to a t_object *, to be filled with the data retrieved from the obex.
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:
By default, pointers to the object's containing patcher and box objects are stored in the obex, under the keys 'P' and 'B', respectively. To retrieve them, the developer could do something like the following:
    void post_containers(t_obexobj *x)
    {
        t_patcher *p;
        t_box *b;

        p = object_obex_lookup(x, gensym("#P"), (t_object **)&p);
        b = object_obex_lookup(x, gensym("#B"), (t_object **)&b);

        post("my patcher is located at 0x%X", p);
        post("my box is located at 0x%X", b);
    }
t_max_err object_obex_store ( void *  x,
t_symbol key,
t_object val 
)

Stores data in the object's obex.

Parameters:
x The object pointer. This function should only be called on instantiated objects (i.e. in the new method or later), not directly on classes (i.e. in main()).
key A symbolic name for the data to be stored
val A t_object *, to be stored in the obex, referenced under the key.
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:
Most developers will need to use this function for the specific purpose of storing the dumpout outlet in the obex (the dumpout outlet is used by attributes to report data in response to 'get' queries). For this, the developer should use something like the following in the object's new method:
    object_obex_store(x, _sym_dumpout, outlet_new(x, NULL));
void object_openhelp ( t_object x  ) 

Open the help patcher for a given instance of an object.

Parameters:
x The object instance for which to open the help patcher.
void object_openquery ( t_object x  ) 

Open a search in the file browser for files with the name of the given object.

Parameters:
x The object instance for which to query.
void object_openrefpage ( t_object x  ) 

Open the reference page for a given instance of an object.

Parameters:
x The object instance for which to open the reference page.
void* object_register ( t_symbol name_space,
t_symbol s,
void *  x 
)

Registers an object in a namespace.

Parameters:
name_space The namespace in which to register the object. The namespace can be any symbol. If the namespace does not already exist, it is created automatically.
s The name of the object in the namespace. This name will be used by other objects to attach and detach from the registered object.
x The object to register
Returns:
The function returns a pointer to the registered object. Under some circumstances, object_register will duplicate the object, and return a pointer to the duplicate—the developer should not assume that the pointer passed in is the same pointer that has been registered. To be safe, the returned pointer should be stored and used with the bject_unregister() function.
Remarks:
You should not register an object if the object is a UI object. UI objects automatically register and attach to themselves in jbox_new().
t_max_err object_setvalueof ( void *  x,
long  ac,
t_atom av 
)

Sets the value of an object which supports the getvalueof/setvalueof interface.

Parameters:
x The object whose value is of interest
ac The count of arguments in av
av Array of t_atoms; the new desired data for the object
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:
Developers wishing to design objects which will support this function being called on them must define and implement a special method, setvalueof, like so:
    class_addmethod(c, (method)myobject_setvalueof, "setvalueof", A_CANT, 0);
The setvalueof method should be prototyped as:
    t_max_err myobject_setvalueof(t_myobject *x, long *ac, t_atom **av);
And implemented, generally, as:
    t_max_err myobject_setvalueof(t_myobject *x, long ac, t_atom *av)
    {
        if (ac && av) {
            // simulate receipt of a float value
            myobject_float(x, atom_getfloat(av));
        }
        return MAX_ERR_NONE;
    }
t_max_err object_unregister ( void *  x  ) 

Removes a registered object from a namespace.

Parameters:
x The object to unregister. This should be the pointer returned from the object_register() function.
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.

Copyright © 2008, Cycling '74