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_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.
t_object *	newobject_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_symbol *	object_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_class *	object_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_dictionary *	object_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.

Definition at line 101 of file ext_mess.h.

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

Referenced by jit_object_attach().

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.

Referenced by jit_object_class(), and max_jit_obex_new().

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.

Referenced by jit_object_classname().

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.

Referenced by jit_object_detach().

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.

Referenced by jit_object_findregistered().

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.

Referenced by jit_object_findregisteredbyptr().

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.

Referenced by db_close(), db_open(), and jit_object_free().

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.

Referenced by jit_object_getmethod().

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.

Referenced by max_jit_obex_gimmeback_dumpout().

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

Referenced by db_query(), db_query_getlastinsertid(), db_result_clear(), db_result_fieldname(), db_result_float(), db_result_long(), db_result_nextrecord(), db_result_numfields(), db_result_numrecords(), db_result_reset(), db_result_string(), db_transaction_end(), db_transaction_flush(), db_transaction_start(), db_view_create(), db_view_getresult(), db_view_remove(), jit_attr_symcompare(), and jit_object_method().

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.

Referenced by jit_object_method_typed(), max_jit_attr_args(), max_jit_obex_gimmeback(), and max_jit_obex_gimmeback_dumpout().

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.

Referenced by jit_object_new(), and jit_qt_movie_read_typed().

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.

Referenced by db_open().

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.

Referenced by jit_object_notify(), max_jit_attr_set(), and max_jit_obex_attr_set().

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

Referenced by jit_object_register().

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.

Referenced by jit_object_unregister().

Objects

Data Structures

Defines

Functions

Detailed Description

Define Documentation

Function Documentation