Max 5 API Reference
00001 00002 #ifndef __OBEX_H__ 00003 #define __OBEX_H__ 00004 00005 #ifdef __cplusplus 00006 extern "C" { 00007 #endif // __cplusplus 00008 00009 00010 #ifndef TRUE 00011 #define TRUE 1 00012 #endif 00013 #ifndef FALSE 00014 #define FALSE 0 00015 #endif 00016 00017 /** The namespace for all Max object classes which can be instantiated in a box, i.e. in a patcher. 00018 @ingroup class */ 00019 #define CLASS_BOX gensym("box") 00020 00021 /** A namespace for creating hidden or internal object classes which are not a direct part of the user 00022 creating patcher. 00023 @ingroup class */ 00024 #define CLASS_NOBOX gensym("nobox") 00025 00026 00027 /** Attribute flags 00028 @ingroup attr 00029 00030 @remark To create a readonly attribute, for example, 00031 you should pass ATTR_SET_OPAQUE or ATTR_SET_OPAQUE_USER as a flag when you create your attribute. 00032 */ 00033 typedef enum { 00034 ATTR_FLAGS_NONE = 0x0000000, ///< No flags 00035 ATTR_GET_OPAQUE = 0x00000001, ///< The attribute cannot be queried by either max message when used inside of a CLASS_BOX object, nor from C code. 00036 ATTR_SET_OPAQUE = 0x00000002, ///< The attribute cannot be set by either max message when used inside of a CLASS_BOX object, nor from C code. 00037 ATTR_GET_OPAQUE_USER = 0x00000100, ///< The attribute cannot be queried by max message when used inside of a CLASS_BOX object, but <em>can</em> be queried from C code. 00038 ATTR_SET_OPAQUE_USER = 0x00000200, ///< The attribute cannot be set by max message when used inside of a CLASS_BOX object, but <em>can</em> be set from C code. 00039 ATTR_GET_DEFER = 0x00010000, ///< Any attribute queries will be called through a defer(). 00040 ATTR_GET_USURP = 0x00020000, ///< Any calls to query the attribute will be called through the equivalent of a defer(), repeated calls will be ignored until the getter is actually run. 00041 ATTR_GET_DEFER_LOW = 0x00040000, ///< Any attribute queries will be called through a defer_low(). 00042 ATTR_GET_USURP_LOW = 0x00080000, ///< Any calls to query the attribute will be called through the equivalent of a defer_low(), repeated calls will be ignored until the getter is actually run. 00043 ATTR_SET_DEFER = 0x01000000, ///< The attribute setter will be called through a defer(). 00044 ATTR_SET_USURP = 0x02000000, ///< Any calls to set the attribute will be called through the equivalent of a defer_low(), repeated calls will be ignored until the setter is actually run. 00045 ATTR_SET_DEFER_LOW = 0x04000000, ///< The attribute setter will be called through a defer_low(). 00046 ATTR_SET_USURP_LOW = 0x08000000 ///< Any calls to set the attribute will be called through the equivalent of a defer_low(), repeated calls will be ignored until the setter is actually run. 00047 } e_max_attrflags; 00048 00049 00050 /** Standard values returned by function calls with a return type of #t_max_err 00051 @ingroup misc */ 00052 typedef enum { 00053 MAX_ERR_NONE = 0, ///< No error 00054 MAX_ERR_GENERIC = -1, ///< Generic error 00055 MAX_ERR_INVALID_PTR = -2, ///< Invalid Pointer 00056 MAX_ERR_DUPLICATE = -3, ///< Duplicate 00057 MAX_ERR_OUT_OF_MEM = -4 ///< Out of memory 00058 } e_max_errorcodes; 00059 00060 00061 /** Flags used in linklist and hashtab objects 00062 @ingroup datastore */ 00063 typedef enum { 00064 OBJ_FLAG_OBJ = 0x00000000, ///< free using object_free() 00065 OBJ_FLAG_REF = 0x00000001, ///< don't free 00066 OBJ_FLAG_DATA = 0x00000002, ///< don't free data or call method 00067 OBJ_FLAG_MEMORY = 0x00000004, ///< don't call method, and when freeing use sysmem_freeptr() instead of freeobject 00068 OBJ_FLAG_SILENT = 0x00000100 ///< don't notify when modified 00069 } e_max_datastore_flags; 00070 00071 00072 #ifdef calcoffset //find better place for this? 00073 // The ifdefs for this macro have been set up like this so that Doxygen can document this macro on a Mac [TAP] 00074 #else 00075 #ifdef WIN_VERSION 00076 // rbs truncation of pointer to long is safe if the struct is smaller than 2^32 bytes. 00077 // this seems like a good assumption. 00078 // PtrToLong is defined in Basetsd.h (windows) and is described here http://msdn2.microsoft.com/En-US/library/aa384242.aspx 00079 #define calcoffset(x,y) (PtrToLong(&(((x *)0L)->y))) 00080 #else 00081 /** 00082 Find byte offset of a named member of a struct, relative to the beginning of that struct. 00083 @ingroup misc 00084 @param x The name of the struct 00085 @param y The name of the member 00086 @return A long integer representing the number of bytes into the struct where the member begins. 00087 */ 00088 #define calcoffset(x,y) ((long)(&(((x *)0L)->y))) 00089 #endif 00090 #endif 00091 00092 #ifndef __JIT_COMMON_H__ 00093 /** An unsigned long integer. 00094 @ingroup datatypes */ 00095 typedef unsigned long ulong; 00096 00097 /** An unsigned integer. 00098 @ingroup datatypes */ 00099 typedef unsigned int uint; 00100 00101 /** An unsigned short integer. 00102 @ingroup datatypes */ 00103 typedef unsigned short ushort; 00104 00105 /** An unsigned char. 00106 @ingroup datatypes */ 00107 typedef unsigned char uchar; 00108 #endif 00109 00110 00111 /** 00112 A Max error code. Common error codes are defined in #e_max_errorcodes. 00113 @ingroup datatypes 00114 */ 00115 typedef long t_max_err; 00116 00117 #include "commonsyms.h" 00118 #include "ext_linklist.h" 00119 #include "ext_hashtab.h" 00120 #include "ext_atomarray.h" 00121 00122 #if C74_PRAGMA_STRUCT_PACKPUSH 00123 #pragma pack(push, 2) 00124 #elif C74_PRAGMA_STRUCT_PACK 00125 #pragma pack(2) 00126 #endif 00127 00128 //for passing on the stack in method calls 00129 /* 00130 typedef struct _stack_splat 00131 { 00132 char b[64]; 00133 } t_stack_splat; 00134 */ 00135 00136 /** Common attr struct. This struct is provided for debugging convenience, 00137 but should be considered opaque and is subject to change without notice. 00138 00139 @ingroup attr 00140 */ 00141 typedef struct _attr 00142 { 00143 t_object ob; 00144 t_symbol *name; 00145 t_symbol *type; 00146 long flags; //public/private get/set methods 00147 method get; //override default get method 00148 method set; //override default set method 00149 void *filterget; //filterobject for get method 00150 void *filterset; //filterobject for set method 00151 void *reserved; //for future use 00152 } t_attr; 00153 00154 00155 /** 00156 A method that always returns true. 00157 @ingroup misc 00158 */ 00159 long method_true(void *x); 00160 00161 00162 /** 00163 A method that always returns false. 00164 @ingroup misc 00165 */ 00166 long method_false(void *x); 00167 00168 00169 /** 00170 Initializes a class by informing Max of its name, instance creation and free functions, size and argument types. 00171 Developers wishing to use obex class features (attributes, etc.) <em>must</em> use class_new() 00172 instead of the traditional setup() function. 00173 00174 @ingroup class 00175 00176 @param name The class's name, as a C-string 00177 @param mnew The instance creation function 00178 @param mfree The instance free function 00179 @param size The size of the object's data structure in bytes. 00180 Usually you use the C sizeof operator here. 00181 @param mmenu The function called when the user creates a new object of the 00182 class from the Patch window's palette (UI objects only). 00183 Pass 0L if you're not defining a UI object. 00184 @param type A standard Max <em>type list</em> as explained in Chapter 3 00185 of the Writing Externals in Max document (in the Max SDK). 00186 The final argument of the type list should be a 0. 00187 <em>Generally, obex objects have a single type argument</em>, 00188 #A_GIMME, followed by a 0. 00189 00190 @return This function returns the class pointer for the new object class. 00191 <em>This pointer is used by numerous other functions and should be 00192 stored in a global or static variable.</em> 00193 */ 00194 t_class *class_new(char *name, method mnew, method mfree, long size, method mmenu, short type, ...); 00195 00196 00197 /** 00198 Frees a previously defined object class. <em>This function is not typically used by external developers.</em> 00199 00200 @ingroup class 00201 @param c The class pointer 00202 @return This function returns the error code #MAX_ERR_NONE if successful, 00203 or one of the other error codes defined in #e_max_errorcodes if unsuccessful. 00204 */ 00205 t_max_err class_free(t_class *c); 00206 00207 00208 /** 00209 Registers a previously defined object class. This function is required, and should be called at the end of <tt>main()</tt>. 00210 00211 @ingroup class 00212 00213 @param name_space The desired class's name space. Typically, either the 00214 constant #CLASS_BOX, for obex classes which can 00215 instantiate inside of a Max patcher (e.g. boxes, UI objects, 00216 etc.), or the constant #CLASS_NOBOX, for classes 00217 which will only be used internally. Developers can define 00218 their own name spaces as well, but this functionality is 00219 currently undocumented. 00220 @param c The class pointer 00221 00222 @return This function returns the error code #MAX_ERR_NONE if successful, 00223 or one of the other error codes defined in #e_max_errorcodes if unsuccessful. 00224 */ 00225 t_max_err class_register(t_symbol *name_space, t_class *c); 00226 00227 00228 /** 00229 Registers an alias for a previously defined object class. 00230 00231 @ingroup class 00232 @param c The class pointer 00233 @param aliasname A symbol who's name will become an alias for the given class 00234 00235 @return This function returns the error code #MAX_ERR_NONE if successful, 00236 or one of the other error codes defined in #e_max_errorcodes if unsuccessful. 00237 */ 00238 t_max_err class_alias(t_class *c, t_symbol *aliasname); 00239 00240 00241 /** 00242 Adds a method to a previously defined object class. 00243 00244 @ingroup class 00245 00246 @param c The class pointer 00247 @param m Function to be called when the method is invoked 00248 @param name C-string defining the message (message selector) 00249 @param ... One or more integers specifying the arguments to the message, 00250 in the standard Max type list format (see Chapter 3 of the 00251 Writing Externals in Max document for more information). 00252 00253 @return This function returns the error code #MAX_ERR_NONE if successful, 00254 or one of the other error codes defined in #e_max_errorcodes if unsuccessful. 00255 00256 @remark The class_addmethod() function works essentially like the 00257 traditional addmess() function, adding the function pointed to 00258 by <tt>m</tt>, to respond to the message string <tt>name</tt> in the 00259 leftmost inlet of the object. 00260 */ 00261 t_max_err class_addmethod(t_class *c, method m, char *name, ...); 00262 00263 00264 /** 00265 Adds an attribute to a previously defined object class. 00266 00267 @ingroup class 00268 00269 @param c The class pointer 00270 @param attr The attribute to add. The attribute will be a pointer returned 00271 by attribute_new(), attr_offset_new() or 00272 attr_offset_array_new(). 00273 00274 @return This function returns the error code #MAX_ERR_NONE if successful, 00275 or one of the other error codes defined in #e_max_errorcodes if unsuccessful. 00276 */ 00277 t_max_err class_addattr(t_class *c,t_object *attr); 00278 00279 00280 // private 00281 t_max_err class_addadornment(t_class *c,t_object *o); 00282 00283 00284 // private 00285 void *class_adornment_get(t_class *c,t_symbol *classname); 00286 00287 00288 /** 00289 Retrieves the name of a class, given the class's pointer. 00290 00291 @ingroup class 00292 @param c The class pointer 00293 @return If successful, this function returns the name of the class as a t_symbol *. 00294 */ 00295 t_symbol *class_nameget(t_class *c); 00296 00297 00298 /** 00299 Finds the class pointer for a class, given the class's namespace and name. 00300 00301 @ingroup class 00302 00303 @param name_space The desired class's name space. Typically, either the 00304 constant #CLASS_BOX, for obex classes which can 00305 instantiate inside of a Max patcher (e.g. boxes, UI objects, 00306 etc.), or the constant #CLASS_NOBOX, for classes 00307 which will only be used internally. Developers can define 00308 their own name spaces as well, but this functionality is 00309 currently undocumented. 00310 @param classname The name of the class to be looked up 00311 00312 @return If successful, this function returns the class's data pointer. Otherwise, it returns NULL. 00313 */ 00314 t_class *class_findbyname(t_symbol *name_space, t_symbol *classname); 00315 00316 00317 /** 00318 Finds the class pointer for a class, given the class's namespace and name. 00319 00320 @ingroup class 00321 00322 @param name_space The desired class's name space. Typically, either the 00323 constant #CLASS_BOX, for obex classes which can 00324 instantiate inside of a Max patcher (e.g. boxes, UI objects, 00325 etc.), or the constant #CLASS_NOBOX, for classes 00326 which will only be used internally. Developers can define 00327 their own name spaces as well, but this functionality is 00328 currently undocumented. 00329 @param classname The name of the class to be looked up (case free) 00330 00331 @return If successful, this function returns the class's data pointer. Otherwise, it returns NULL. 00332 */ 00333 t_class *class_findbyname_casefree(t_symbol *name_space, t_symbol *classname); 00334 00335 00336 /** 00337 Wraps user gettable attributes with a method that gets the values and sends out dumpout outlet. 00338 00339 @ingroup class 00340 @param c The class pointer 00341 @return This function returns the error code #MAX_ERR_NONE if successful, 00342 or one of the other error codes defined in #e_max_errorcodes if unsuccessful. 00343 */ 00344 t_max_err class_dumpout_wrap(t_class *c); 00345 00346 t_class *class_getifloaded(t_symbol *name_space, t_symbol *classname); 00347 t_class *class_getifloaded_casefree(t_symbol *name_space, t_symbol *classname); 00348 00349 00350 /** 00351 Determines if a particular object is an instance of a given class. 00352 00353 @ingroup obj 00354 00355 @param x The object to test 00356 @param name The name of the class to test this object against 00357 @return This function returns 1 if the object is an instance of the named class. Otherwise, 0 is returned. 00358 @remark For instance, to determine whether an unknown object pointer is a pointer to a print object, one would call: 00359 00360 @code 00361 long isprint = object_classname_compare(x, gensym("print")); 00362 @endcode 00363 */ 00364 long object_classname_compare(void *x, t_symbol *name); 00365 00366 00367 t_hashtab *reg_object_namespace_lookup(t_symbol *name_space); 00368 method class_method(t_class *x, t_symbol *methodname); 00369 t_messlist *class_mess(t_class *x, t_symbol *methodname); 00370 method class_attr_method(t_class *x, t_symbol *methodname, void **attr, long *get); 00371 void *class_attr_get(t_class *x, t_symbol *attrname); 00372 t_max_err class_extra_store(t_class *x,t_symbol *s,t_object *o); 00373 t_max_err class_extra_storeflags(t_class *x,t_symbol *s,t_object *o,long flags); 00374 void *class_extra_lookup(t_class *x,t_symbol *s); 00375 t_max_err class_addtypedwrapper(t_class *x, method m, char *name, ...); 00376 t_messlist *class_typedwrapper_get(t_class *x, t_symbol *s); 00377 t_hashtab *class_namespace_fromsym(t_symbol *name_space); 00378 t_max_err class_namespace_getclassnames(t_symbol *name_space, long *kc, t_symbol ***kv); 00379 t_max_err class_setpath(t_class *x, short vol); 00380 short class_getpath(t_class *x); 00381 00382 00383 /** 00384 Allocates the memory for an instance of an object class and initialize its object header. 00385 It is used like the traditional function newobject, inside of an object's <tt>new</tt> method, but its use is required with obex-class objects. 00386 00387 @ingroup obj 00388 @param c The class pointer, returned by class_new() 00389 @return This function returns a new instance of an object class if successful, or NULL if unsuccessful. 00390 */ 00391 void *object_alloc(t_class *c); 00392 00393 00394 /** 00395 Allocates the memory for an instance of an object class and initialize its object header <em>internal to Max</em>. 00396 It is used similarly to the traditional function newinstance(), but its use is required with obex-class objects. 00397 00398 @ingroup obj 00399 00400 @param name_space The desired object's name space. Typically, either the 00401 constant #CLASS_BOX, for obex classes which can 00402 instantiate inside of a Max patcher (e.g. boxes, UI objects, 00403 etc.), or the constant #CLASS_NOBOX, for classes 00404 which will only be used internally. Developers can define 00405 their own name spaces as well, but this functionality is 00406 currently undocumented. 00407 @param classname The name of the class of the object to be created 00408 @param ... Any arguments expected by the object class being instantiated 00409 00410 @return This function returns a new instance of the object class if successful, or NULL if unsuccessful. 00411 */ 00412 void *object_new(t_symbol *name_space, t_symbol *classname, ...); 00413 00414 00415 /** 00416 Allocates the memory for an instance of an object class and initialize its object header <em>internal to Max</em>. 00417 It is used similarly to the traditional function newinstance(), but its use is required with obex-class objects. 00418 The object_new_typed() function differs from object_new() by its use of an atom list for object arguments—in this way, 00419 it more resembles the effect of typing something into an object box from the Max interface. 00420 00421 @ingroup obj 00422 00423 @param name_space The desired object's name space. Typically, either the 00424 constant #CLASS_BOX, for obex classes which can 00425 instantiate inside of a Max patcher (e.g. boxes, UI objects, 00426 etc.), or the constant #CLASS_NOBOX, for classes 00427 which will only be used internally. Developers can define 00428 their own name spaces as well, but this functionality is 00429 currently undocumented. 00430 @param classname The name of the class of the object to be created 00431 @param ac Count of arguments in <tt>av</tt> 00432 @param av Array of t_atoms; arguments to the class's instance creation function. 00433 00434 @return This function returns a new instance of the object class if successful, or NULL if unsuccessful. 00435 */ 00436 void *object_new_typed(t_symbol *name_space, t_symbol *classname, long ac, t_atom *av); 00437 00438 void *object_new_menufun(t_symbol *name_space, t_symbol *classname, void *p, long h, long v, long f); 00439 00440 00441 /** 00442 Call the free function and release the memory for an instance of an internal object class previously instantiated using object_new(), 00443 object_new_typed() or other new-style object constructor functions (e.g. hashtab_new()). 00444 It is, at the time of this writing, a wrapper for the traditional function freeobject(), but its use is suggested with obex-class objects. 00445 00446 @ingroup obj 00447 @param x The pointer to the object to be freed. 00448 @return This function returns the error code #MAX_ERR_NONE if successful, 00449 or one of the other error codes defined in #e_max_errorcodes if unsuccessful. 00450 */ 00451 t_max_err object_free(void *x); 00452 00453 00454 /** 00455 Sends an untyped message to an object. 00456 00457 @ingroup obj 00458 00459 @param x The object that will receive the message 00460 @param s The message selector 00461 @param ... Any arguments to the message 00462 00463 @return If the receiver object can respond to the message, object_method() returns the result. Otherwise, the function will return 0. 00464 00465 @remark Example: To send the message <tt>bang</tt> to the object <tt>bang_me</tt>: 00466 @code 00467 void *bang_result; 00468 bang_result = object_method(bang_me, gensym("bang")); 00469 @endcode 00470 */ 00471 void *object_method(void *x, t_symbol *s, ...); 00472 00473 00474 /** 00475 Sends a type-checked message to an object. 00476 00477 @ingroup obj 00478 00479 @param x The object that will receive the message 00480 @param s The message selector 00481 @param ac Count of message arguments in <tt>av</tt> 00482 @param av Array of t_atoms; the message arguments 00483 @param rv Return value of function, if available 00484 00485 @return This function returns the error code #MAX_ERR_NONE if successful, 00486 or one of the other error codes defined in #e_max_errorcodes if unsuccessful. 00487 00488 @remark If the receiver object can respond to the message, object_method_typed() returns the result in <tt>rv</tt>. Otherwise, <tt>rv</tt> will contain an #A_NOTHING atom. 00489 */ 00490 t_max_err object_method_typed(void *x, t_symbol *s, long ac, t_atom *av, t_atom *rv); 00491 00492 00493 /** 00494 Currently undocumented. 00495 00496 @ingroup obj 00497 00498 @param x The object that will receive the message 00499 @param mp Undocumented 00500 @param s The message selector 00501 @param ac Count of message arguments in <tt>av</tt> 00502 @param av Array of t_atoms; the message arguments 00503 @param rv Return value of function, if available 00504 00505 @return This function returns the error code #MAX_ERR_NONE if successful, 00506 or one of the other error codes defined in #e_max_errorcodes if unsuccessful. 00507 00508 @remark If the receiver object can respond to the message, object_method_typedfun() returns the result in <tt>rv</tt>. Otherwise, <tt>rv</tt> will contain an #A_NOTHING atom. 00509 */ 00510 t_max_err object_method_typedfun(void *x, t_messlist *mp, t_symbol *s, long ac, t_atom *av, t_atom *rv); 00511 00512 00513 /** 00514 Retrieves an object's #method for a particular message selector. 00515 00516 @ingroup obj 00517 @param x The object whose method is being queried 00518 @param s The message selector 00519 @return This function returns the #method if successful, or 0 if unsuccessful. 00520 */ 00521 method object_getmethod(void *x, t_symbol *s); 00522 00523 00524 /** 00525 Retrieves an object instance's class name 00526 00527 @ingroup obj 00528 @param x The object instance whose class name is being queried 00529 @return The classname, or NULL if unsuccessful. 00530 */ 00531 t_symbol *object_classname(void *x); 00532 00533 00534 t_symbol *object_namespace(t_object *x); // return the namespace this object's class is part of 00535 00536 00537 t_symbol *class_namespace(t_class *c); // return the namespace the class is part of 00538 00539 00540 /** 00541 Registers an object in a namespace. 00542 00543 @ingroup obj 00544 00545 @param name_space The namespace in which to register the object. The namespace can be any symbol. 00546 If the namespace does not already exist, it is created automatically. 00547 @param s The name of the object in the namespace. This name will be 00548 used by other objects to attach and detach from the registered object. 00549 @param x The object to register 00550 00551 @return The function returns a pointer to the registered object. Under some 00552 circumstances, object_register will <em>duplicate</em> the object, 00553 and return a pointer to the duplicate—the developer should not assume 00554 that the pointer passed in is the same pointer that has been registered. 00555 To be safe, the returned pointer should be stored and used with the 00556 bject_unregister() function. 00557 00558 @remark You should not register an object if the object is a UI object. 00559 UI objects automatically register and attach to themselves in jbox_new(). 00560 */ 00561 void *object_register(t_symbol *name_space, t_symbol *s, void *x); 00562 00563 00564 t_symbol *object_register_unique(t_symbol *name_space, t_symbol *s, void *x); 00565 00566 00567 /** 00568 Determines a registered object's pointer, given its namespace and name. 00569 00570 @ingroup obj 00571 00572 @param name_space The namespace of the registered object 00573 @param s The name of the registered object in the namespace 00574 00575 @return This function returns the pointer of the registered object, 00576 if successful, or NULL, if unsuccessful. 00577 */ 00578 void *object_findregistered(t_symbol *name_space, t_symbol *s); 00579 00580 00581 /** 00582 Determines the namespace and/or name of a registered object, given the object's pointer. 00583 00584 @ingroup obj 00585 00586 @param name_space Pointer to a t_symbol *, to receive the namespace of the registered object 00587 @param s Pointer to a t_symbol *, to receive the name of the registered object within the namespace 00588 @param x Pointer to the registered object 00589 00590 @return This function returns the error code #MAX_ERR_NONE if successful, 00591 or one of the other error codes defined in #e_max_errorcodes if unsuccessful. 00592 */ 00593 t_max_err object_findregisteredbyptr(t_symbol **name_space, t_symbol **s, void *x); 00594 00595 00596 /** 00597 Attaches a client to a registered object. 00598 Once attached, the object will receive notifications sent from the registered object (via the object_notify() function), 00599 if it has a <tt>notify</tt> method defined and implemented. 00600 00601 @ingroup obj 00602 00603 @param name_space The namespace of the registered object. 00604 This should be the same value used in object_register() to register the object. 00605 If you don't know the registered object's namespace, the object_findregisteredbyptr() function can be used to determine it. 00606 @param s The name of the registered object in the namespace. 00607 If you don't know the name of the registered object, the object_findregisteredbyptr() function can be used to determine it. 00608 @param x The client object to attach. Generally, this is the pointer to your Max object. 00609 00610 @return This function returns a pointer to the registered object (to the object 00611 referred to by the combination of <tt>name_space</tt> and <tt>s</tt> 00612 arguments) if successful, or NULL if unsuccessful. 00613 00614 @remark You should not attach an object to itself if the object is a UI object. 00615 UI objects automatically register and attach to themselves in jbox_new(). 00616 00617 @see object_notify() 00618 @see object_detach() 00619 @see object_attach_byptr() 00620 @see object_register() 00621 */ 00622 void *object_attach(t_symbol *name_space, t_symbol *s, void *x); 00623 00624 00625 /** 00626 Detach a client from a registered object. 00627 00628 @ingroup obj 00629 00630 @param name_space The namespace of the registered object. 00631 This should be the same value used in object_register() to register the object. 00632 If you don't know the registered object's namespace, the object_findregisteredbyptr() function can be used to determine it. 00633 @param s The name of the registered object in the namespace. 00634 If you don't know the name of the registered object, the object_findregisteredbyptr() function can be used to determine it. 00635 @param x The client object to attach. Generally, this is the pointer to your Max object. 00636 00637 @return This function returns the error code #MAX_ERR_NONE if successful, 00638 or one of the other error codes defined in #e_max_errorcodes if unsuccessful. 00639 */ 00640 t_max_err object_detach(t_symbol *name_space, t_symbol *s, void *x); 00641 00642 00643 /** 00644 Attaches a client to a registered object. 00645 Unlike object_attach(), the client is specified by providing a pointer to that object 00646 rather than the registered name of that object. 00647 00648 Once attached, the object will receive notifications sent from the registered object (via the object_notify() function), 00649 if it has a <tt>notify</tt> method defined and implemented. 00650 00651 @ingroup obj 00652 @param x The attaching client object. Generally, this is the pointer to your Max object. 00653 @param registeredobject A pointer to the registered object to which you wish to attach. 00654 @return A Max error code. 00655 00656 @remark You should not attach an object to itself if the object is a UI object. 00657 UI objects automatically register and attach to themselves in jbox_new(). 00658 00659 @see object_notify() 00660 @see object_detach() 00661 @see object_attach() 00662 @see object_register() 00663 @see object_attach_byptr_register() 00664 */ 00665 t_max_err object_attach_byptr(void *x, void *registeredobject); 00666 00667 00668 /** 00669 A convenience function wrapping object_register() and object_attach_byptr(). 00670 00671 @ingroup obj 00672 00673 @param x The attaching client object. Generally, this is the pointer to your Max object. 00674 @param object_to_attach A pointer to the object to which you wish to registered and then to which to attach. 00675 @param reg_name_space The namespace in which to register the object_to_attach. 00676 @return A Max error code. 00677 00678 @see object_register() 00679 @see object_attach_byptr() 00680 */ 00681 t_max_err object_attach_byptr_register(void *x, void *object_to_attach, t_symbol *reg_name_space); 00682 00683 00684 /** 00685 Detach a client from a registered object. 00686 00687 @ingroup obj 00688 @param x The attaching client object. Generally, this is the pointer to your Max object. 00689 @param registeredobject The object from which to detach. 00690 @return A Max error code. 00691 00692 @see object_detach() 00693 @see object_attach_byptr() 00694 */ 00695 t_max_err object_detach_byptr(void *x, void *registeredobject); 00696 00697 00698 /** 00699 Removes a registered object from a namespace. 00700 00701 @ingroup obj 00702 @param x The object to unregister. This should be the pointer returned from the object_register() function. 00703 @return This function returns the error code #MAX_ERR_NONE if successful, 00704 or one of the other error codes defined in #e_max_errorcodes if unsuccessful. 00705 */ 00706 t_max_err object_unregister(void *x); 00707 00708 00709 /** 00710 Broadcast a message (with an optional argument) from a registered object to any attached client objects. 00711 00712 @ingroup obj 00713 00714 @param x Pointer to the registered object 00715 @param s The message to send 00716 @param data An optional argument which will be passed with the message. 00717 Sets this argument to NULL if it will be unused. 00718 00719 @return This function returns the error code #MAX_ERR_NONE if successful, 00720 or one of the other error codes defined in #e_max_errorcodes if unsuccessful. 00721 00722 @remark In order for client objects to receive notifications, they must define and implement a special method, <tt>notify</tt>, like so: 00723 @code 00724 class_addmethod(c, (method)myobject_notify, "notify", A_CANT, 0); 00725 @endcode 00726 00727 @remark The <tt>notify</tt> method should be prototyped as: 00728 @code 00729 void myobject_notify(t_myobject *x, t_symbol *s, t_symbol *msg, void *sender, void *data); 00730 @endcode 00731 where 00732 <tt>x</tt> is the pointer to the receiving object, 00733 <tt>s</tt> is the name of the sending (registered) object in its namespace, 00734 <tt>msg</tt> is the sent message, 00735 <tt>sender</tt> is the pointer to the sending object, and 00736 <tt>data</tt> is an optional argument sent with the message. 00737 This value corresponds to the data argument in the object_notify() method. 00738 */ 00739 t_max_err object_notify(void *x, t_symbol *s, void *data); 00740 00741 00742 /** 00743 Determines the class of a given object. 00744 00745 @ingroup obj 00746 @param x The object to test 00747 @return This function returns the t_class * of the object's class, if successful, or NULL, if unsuccessful. 00748 */ 00749 t_class *object_class(void *x); 00750 00751 00752 /** 00753 Retrieves the value of an object which supports the <tt>getvalueof/setvalueof</tt> interface. See part 2 of the pattr SDK for more information on this interface. 00754 00755 @ingroup obj 00756 00757 @param x The object whose value is of interest 00758 @param ac Pointer to a long variable to receive the count of arguments in <tt>av</tt>. The long variable itself should be set to 0 previous to calling this function. 00759 @param av Pointer to a t_atom *, to receive object data. The t_atom * itself should be set to NULL previous to calling this function. 00760 00761 @return This function returns the error code #MAX_ERR_NONE if successful, 00762 or one of the other error codes defined in #e_max_errorcodes if unsuccessful. 00763 00764 @remark Calling the object_getvalueof() function allocates memory for any data it returns. 00765 It is the developer's responsibility to free it, using the freebytes() function. 00766 00767 @remark Developers wishing to design objects which will support this function being called on them must define and implement a special method, <tt>getvalueof</tt>, like so: 00768 @code 00769 class_addmethod(c, (method)myobject_getvalueof, "getvalueof", A_CANT, 0); 00770 @endcode 00771 00772 @remark The <tt>getvalueof</tt> method should be prototyped as: 00773 @code 00774 t_max_err myobject_getvalueof(t_myobject *x, long *ac, t_atom **av); 00775 @endcode 00776 00777 @remark And implemented, generally, as: 00778 @code 00779 t_max_err myobj_getvalueof(t_myobj *x, long *ac, t_atom **av) 00780 { 00781 if (ac && av) { 00782 if (*ac && *av) { 00783 // memory has been passed in; use it. 00784 } else { 00785 // allocate enough memory for your data 00786 *av = (t_atom *)getbytes(sizeof(t_atom)); 00787 } 00788 *ac = 1; // our data is a single floating point value 00789 atom_setfloat(*av, x->objvalue); 00790 } 00791 return MAX_ERR_NONE; 00792 } 00793 00794 @remark By convention, and to permit the interoperability of objects using the obex API, 00795 developers should allocate memory in their <tt>getvalueof</tt> methods using the getbytes() function. 00796 @endcode 00797 */ 00798 t_max_err object_getvalueof(void *x, long *ac, t_atom **av); 00799 00800 00801 /** 00802 Sets the value of an object which supports the <tt>getvalueof/setvalueof</tt> interface. 00803 00804 @ingroup obj 00805 00806 @param x The object whose value is of interest 00807 @param ac The count of arguments in <tt>av</tt> 00808 @param av Array of t_atoms; the new desired data for the object 00809 00810 @return This function returns the error code #MAX_ERR_NONE if successful, 00811 or one of the other error codes defined in #e_max_errorcodes if unsuccessful. 00812 00813 @remark Developers wishing to design objects which will support this function being called on them must define and implement a special method, <tt>setvalueof</tt>, like so: 00814 @code 00815 class_addmethod(c, (method)myobject_setvalueof, "setvalueof", A_CANT, 0); 00816 @endcode 00817 00818 @remark The <tt>setvalueof</tt> method should be prototyped as: 00819 @code 00820 t_max_err myobject_setvalueof(t_myobject *x, long *ac, t_atom **av); 00821 @endcode 00822 00823 @remark And implemented, generally, as: 00824 @code 00825 t_max_err myobject_setvalueof(t_myobject *x, long ac, t_atom *av) 00826 { 00827 if (ac && av) { 00828 // simulate receipt of a float value 00829 myobject_float(x, atom_getfloat(av)); 00830 } 00831 return MAX_ERR_NONE; 00832 } 00833 @endcode 00834 */ 00835 t_max_err object_setvalueof(void *x, long ac, t_atom *av); 00836 00837 00838 00839 t_max_err object_attr_getnames(void *x, long *argc, t_symbol ***argv); 00840 00841 00842 /** 00843 Returns the pointer to an attribute, given its name. 00844 00845 @ingroup attr 00846 00847 @param x Pointer to the object whose attribute is of interest 00848 @param attrname The attribute's name 00849 00850 @return This function returns a pointer to the attribute, if successful, or NULL, if unsuccessful. 00851 */ 00852 void *object_attr_get(void *x, t_symbol *attrname); 00853 00854 00855 /** 00856 Returns the method of an attribute's <tt>get</tt> or <tt>set</tt> function, as well as a pointer to the attribute itself, from a message name. 00857 00858 @ingroup attr 00859 00860 @param x Pointer to the object whose attribute is of interest 00861 @param methodname The Max message used to call the attribute's <tt>get</tt> or <tt>set</tt> function. For example, <tt>gensym("mode")</tt> or <tt>gensym("getthresh")</tt>. 00862 @param attr A pointer to a void *, which will be set to the attribute pointer upon successful completion of the function 00863 @param get A pointer to a long variable, which will be set to 1 upon successful completion of the function, 00864 if the queried method corresponds to the <tt>get</tt> function of the attribute. 00865 00866 @return This function returns the requested method, if successful, or NULL, if unsuccessful. 00867 */ 00868 method object_attr_method(void *x, t_symbol *methodname, void **attr, long *get); 00869 00870 00871 /** 00872 Determines if an object's attribute can be set from the Max interface (i.e. if its #ATTR_SET_OPAQUE_USER flag is set). 00873 00874 @ingroup attr 00875 00876 @param x Pointer to the object whose attribute is of interest 00877 @param s The attribute's name 00878 00879 @return This function returns 1 if the attribute can be set from the Max interface. Otherwise, it returns 0. 00880 */ 00881 long object_attr_usercanset(void *x,t_symbol *s); 00882 00883 00884 /** 00885 Determines if the value of an object's attribute can be queried from the Max interface (i.e. if its #ATTR_GET_OPAQUE_USER flag is set). 00886 00887 @ingroup attr 00888 00889 @param x Pointer to the object whose attribute is of interest 00890 @param s The attribute's name 00891 00892 @return This function returns 1 if the value of the attribute can be queried from the Max interface. Otherwise, it returns 0. 00893 */ 00894 long object_attr_usercanget(void *x,t_symbol *s); 00895 00896 00897 /** 00898 Forces a specified object's attribute to send its value from the object's dumpout outlet in the Max interface. 00899 00900 @ingroup attr 00901 00902 @param x Pointer to the object whose attribute is of interest 00903 @param s The attribute's name 00904 @param argc Unused 00905 @param argv Unused 00906 */ 00907 void object_attr_getdump(void *x, t_symbol *s, long argc, t_atom *argv); 00908 00909 00910 t_max_err object_attr_getvalueof(void *x, t_symbol *s, long *argc, t_atom **argv); 00911 00912 00913 /** 00914 Sets the value of an object's attribute. 00915 00916 @ingroup attr 00917 00918 @param x Pointer to the object whose attribute is of interest 00919 @param s The attribute's name 00920 @param argc The count of arguments in <tt>argv</tt> 00921 @param argv Array of t_atoms; the new desired data for the attribute 00922 00923 @return This function returns the error code #MAX_ERR_NONE if successful, 00924 or one of the other error codes defined in #e_max_errorcodes if unsuccessful. 00925 */ 00926 t_max_err object_attr_setvalueof(void *x, t_symbol *s, long argc, t_atom *argv); 00927 00928 00929 //object specific attributes(dynamically add/delete) 00930 00931 /** 00932 Attaches an attribute directly to an object. 00933 00934 @ingroup attr 00935 00936 @param x An object to which the attribute should be attached 00937 @param attr The attribute's pointer—this should be a pointer returned from attribute_new(), attr_offset_new() or attr_offset_array_new(). 00938 00939 @return This function returns the error code #MAX_ERR_NONE if successful, 00940 or one of the other error codes defined in #e_max_errorcodes if unsuccessful. 00941 */ 00942 t_max_err object_addattr(void *x, t_object *attr); 00943 00944 00945 /** 00946 Detach an attribute from an object that was previously attached with object_addattr(). 00947 The function will also free all memory associated with the attribute. 00948 If you only wish to detach the attribute, without freeing it, see the object_chuckattr() function. 00949 00950 @ingroup attr 00951 00952 @param x The object to which the attribute is attached 00953 @param attrsym The attribute's name 00954 00955 @return This function returns the error code #MAX_ERR_NONE if successful, 00956 or one of the other error codes defined in #e_max_errorcodes if unsuccessful. 00957 */ 00958 t_max_err object_deleteattr(void *x, t_symbol *attrsym); 00959 00960 00961 /** 00962 Detach an attribute from an object that was previously attached with object_addattr(). 00963 This function will <em>not</em> free the attribute (use object_free() to do this manually). 00964 00965 @ingroup attr 00966 00967 @param x The object to which the attribute is attached 00968 @param attrsym The attribute's name 00969 00970 @return This function returns the error code #MAX_ERR_NONE if successful, 00971 or one of the other error codes defined in #e_max_errorcodes if unsuccessful. 00972 */ 00973 t_max_err object_chuckattr(void *x, t_symbol *attrsym); 00974 00975 00976 // obex 00977 00978 /** 00979 Registers the byte-offset of the obex member of the class's data structure with the previously defined object class. 00980 Use of this function is required for obex-class objects. It must be called from <tt>main()</tt>. 00981 00982 @ingroup class 00983 00984 @param c The class pointer 00985 @param offset The byte-offset to the obex member of the object's data structure. 00986 Conventionally, the macro #calcoffset is used to calculate the offset. 00987 */ 00988 void class_obexoffset_set(t_class *c, long offset); 00989 00990 00991 /** 00992 Retrieves the byte-offset of the obex member of the class's data structure. 00993 00994 @ingroup class 00995 @param c The class pointer 00996 @return This function returns the byte-offset of the obex member of the class's data structure. 00997 */ 00998 long class_obexoffset_get(t_class *c); 00999 01000 01001 /** 01002 Retrieves the value of a data stored in the obex. 01003 01004 @ingroup obj 01005 01006 @param x The object pointer. This function should only be called on instantiated objects (i.e. in the <tt>new</tt> method or later), not directly on classes (i.e. in <tt>main()</tt>). 01007 @param key The symbolic name for the data to be retrieved 01008 @param val A pointer to a #t_object *, to be filled with the data retrieved from the obex. 01009 01010 @return This function returns the error code #MAX_ERR_NONE if successful, 01011 or one of the other error codes defined in #e_max_errorcodes if unsuccessful. 01012 01013 @remark By default, pointers to the object's containing patcher and box objects are stored in the obex, under the keys '#P' and '#B', respectively. 01014 To retrieve them, the developer could do something like the following: 01015 @code 01016 void post_containers(t_obexobj *x) 01017 { 01018 t_patcher *p; 01019 t_box *b; 01020 01021 p = object_obex_lookup(x, gensym("#P"), (t_object **)&p); 01022 b = object_obex_lookup(x, gensym("#B"), (t_object **)&b); 01023 01024 post("my patcher is located at 0x%X", p); 01025 post("my box is located at 0x%X", b); 01026 } 01027 @endcode 01028 */ 01029 t_max_err object_obex_lookup(void *x, t_symbol *key, t_object **val); 01030 01031 01032 /** 01033 Stores data in the object's obex. 01034 01035 @ingroup obj 01036 01037 @param x The object pointer. This function should only be called on instantiated objects (i.e. in the <tt>new</tt> method or later), not directly on classes (i.e. in <tt>main()</tt>). 01038 @param key A symbolic name for the data to be stored 01039 @param val A #t_object *, to be stored in the obex, referenced under the <tt>key</tt>. 01040 01041 @return This function returns the error code #MAX_ERR_NONE if successful, 01042 or one of the other error codes defined in #e_max_errorcodes if unsuccessful. 01043 01044 @remark Most developers will need to use this function for the specific purpose of storing the dumpout outlet in the obex 01045 (the dumpout outlet is used by attributes to report data in response to 'get' queries). 01046 For this, the developer should use something like the following in the object's <tt>new</tt> method: 01047 @code 01048 object_obex_store(x, _sym_dumpout, outlet_new(x, NULL)); 01049 @endcode 01050 */ 01051 t_max_err object_obex_store(void *x,t_symbol *key, t_object *val); 01052 t_max_err object_obex_storeflags(void *x,t_symbol *key, t_object *val, long flags); 01053 01054 01055 // private 01056 t_max_err object_obex_set(void *x, t_hashtab *obex); 01057 01058 01059 // private 01060 t_hashtab *object_obex_get(void *x); 01061 01062 01063 // private 01064 t_hashtab *object_obex_enforce(void *x); 01065 01066 01067 /** 01068 Sends data from the object's dumpout outlet. 01069 The dumpout outlet is stored in the obex using the object_obex_store() function (see above). 01070 It is used approximately like outlet_anything(). 01071 01072 @ingroup obj 01073 01074 @param x The object pointer. 01075 This function should only be called on instantiated objects (i.e. in the <tt>new</tt> method or later), not directly on classes (i.e. in <tt>main()</tt>). 01076 @param s The message selector #t_symbol * 01077 @param argc Number of elements in the argument list in argv 01078 @param argv t_atoms constituting the message arguments 01079 01080 @return This function returns the error code #MAX_ERR_NONE if successful, 01081 or one of the other error codes defined in #e_max_errorcodes if unsuccessful. 01082 */ 01083 void object_obex_dumpout(void *x, t_symbol *s, long argc, t_atom *argv); 01084 01085 01086 void object_obex_free(void *x); 01087 01088 01089 //atom functions 01090 01091 /** 01092 Inserts an integer into a #t_atom and change the t_atom's type to #A_LONG. 01093 01094 @ingroup atom 01095 01096 @param a Pointer to a #t_atom whose value and type will be modified 01097 @param b Integer value to copy into the #t_atom 01098 01099 @return This function returns the error code #MAX_ERR_NONE if successful, 01100 or one of the other error codes defined in #e_max_errorcodes if unsuccessful. 01101 */ 01102 t_max_err atom_setlong(t_atom *a, long b); 01103 01104 01105 /** 01106 Inserts a floating point number into a #t_atom and change the t_atom's type to #A_FLOAT. 01107 01108 @ingroup atom 01109 01110 @param a Pointer to a #t_atom whose value and type will be modified 01111 @param b Floating point value to copy into the #t_atom 01112 01113 @return This function returns the error code #MAX_ERR_NONE if successful, 01114 or one of the other error codes defined in #e_max_errorcodes if unsuccessful. 01115 */ 01116 t_max_err atom_setfloat(t_atom *a, double b); 01117 01118 01119 /** 01120 Inserts a #t_symbol * into a #t_atom and change the t_atom's type to #A_SYM. 01121 01122 @ingroup atom 01123 01124 @param a Pointer to a #t_atom whose value and type will be modified 01125 @param b Pointer to a #t_symbol to copy into the #t_atom 01126 01127 @return This function returns the error code #MAX_ERR_NONE if successful, 01128 or one of the other error codes defined in #e_max_errorcodes if unsuccessful. 01129 */ 01130 t_max_err atom_setsym(t_atom *a, t_symbol *b); 01131 01132 01133 /** 01134 Inserts a generic pointer value into a #t_atom and change the t_atom's type to #A_OBJ. 01135 01136 @ingroup atom 01137 01138 @param a Pointer to a #t_atom whose value and type will be modified 01139 @param b Pointer value to copy into the #t_atom 01140 01141 @return This function returns the error code #MAX_ERR_NONE if successful, 01142 or one of the other error codes defined in #e_max_errorcodes if unsuccessful. 01143 */ 01144 t_max_err atom_setobj(t_atom *a, void *b); 01145 01146 01147 /** 01148 Retrieves a long integer value from a #t_atom. 01149 01150 @ingroup atom 01151 01152 @param a Pointer to a #t_atom whose value is of interest 01153 @return This function returns the value of the specified #t_atom as an integer, if possible. Otherwise, it returns 0. 01154 @remark If the #t_atom is not of the type specified by the function, the function will attempt to coerce a valid value from the t_atom. 01155 For instance, if the t_atom <tt>at</tt> is set to type #A_FLOAT with a value of <tt>3.7</tt>, 01156 the atom_getlong() function will return the truncated integer value of <tt>at</tt>, or <tt>3</tt>. 01157 An attempt is also made to coerce #t_symbol data. 01158 */ 01159 long atom_getlong(t_atom *a); 01160 01161 01162 /** 01163 Retrieves a floating point value from a #t_atom. 01164 01165 @ingroup atom 01166 @param a Pointer to a #t_atom whose value is of interest 01167 @return This function returns the value of the specified #t_atom as a floating point number, if possible. Otherwise, it returns 0. 01168 01169 @remark If the #t_atom is not of the type specified by the function, the function will attempt to coerce a valid value from the t_atom. 01170 For instance, if the t_atom <tt>at</tt> is set to type #A_LONG with a value of <tt>5</tt>, 01171 the atom_getfloat() function will return the value of <tt>at</tt> as a float, or <tt>5.0</tt>. 01172 An attempt is also made to coerce #t_symbol data. 01173 */ 01174 float atom_getfloat(t_atom *a); 01175 01176 01177 /** 01178 Retrieves a t_symbol * value from a t_atom. 01179 01180 @ingroup atom 01181 @param a Pointer to a t_atom whose value is of interest 01182 @return This function returns the value of the specified #A_SYM-typed #t_atom, if possible. 01183 Otherwise, it returns an empty, but valid, #t_symbol *, equivalent to <tt>gensym("")</tt>, or <tt>_sym_nothing</tt>. 01184 01185 @remark No attempt is made to coerce non-matching data types. 01186 */ 01187 t_symbol *atom_getsym(t_atom *a); 01188 01189 01190 /** 01191 Retrieves a generic pointer value from a #t_atom. 01192 01193 @ingroup atom 01194 @param a Pointer to a #t_atom whose value is of interest 01195 @return This function returns the value of the specified #A_OBJ-typed t_atom, if possible. Otherwise, it returns NULL. 01196 */ 01197 void *atom_getobj(t_atom *a); 01198 01199 01200 /** 01201 Retrieves an unsigned integer value between 0 and 255 from a t_atom. 01202 01203 @ingroup atom 01204 @param a Pointer to a #t_atom whose value is of interest 01205 @return This function returns the value of the specified #t_atom as an integer between 0 and 255, if possible. Otherwise, it returns 0. 01206 01207 @remark If the #t_atom is typed #A_LONG, but the data falls outside of the range 0-255, the data is truncated to that range before output. 01208 01209 @remark If the t_atom is typed #A_FLOAT, the floating point value is multiplied by 255. and truncated to the range 0-255 before output. 01210 For example, the floating point value <tt>0.5</tt> would be output from atom_getcharfix as <tt>127</tt> (0.5 * 255. = 127.5). 01211 01212 @remark No attempt is also made to coerce #t_symbol data. 01213 */ 01214 long atom_getcharfix(t_atom *a); 01215 01216 01217 /** 01218 Retrieves type from a #t_atom. 01219 01220 @ingroup atom 01221 @param a Pointer to a #t_atom whose type is of interest 01222 @return This function returns the type of the specified t_atom as defined in #e_max_atomtypes 01223 */ 01224 long atom_gettype(t_atom *a); 01225 01226 01227 //the following are useful for setting the values _only_ if there is an arg 01228 //rather than setting it to 0 or _sym_nothing 01229 01230 /** 01231 Retrieves the integer value of a particular t_atom from an atom list, if the atom exists. 01232 01233 @ingroup atom 01234 01235 @param c Pointer to a long variable to receive the atom's data if the function is successful. 01236 @param idx Offset into the atom list of the atom of interest, starting from 0. 01237 For instance, if you want data from the 3rd atom in the atom list, <tt>idx</tt> should be set to 2. 01238 @param ac Count of av. 01239 @param av Pointer to the first t_atom of an atom list. 01240 01241 @return This function returns the error code #MAX_ERR_NONE if successful, 01242 or one of the other error codes defined in #e_max_errorcodes if unsuccessful. 01243 01244 @remark The atom_arg_getlong() function only changes the value of <tt>c</tt> if the function is successful. 01245 For instance, the following code snippet illustrates a simple, but typical use: 01246 @code 01247 void myobject_mymessage(t_myobject *x, t_symbol *s, long ac, t_atom *av) 01248 { 01249 long var = -1; 01250 01251 // here, we are expecting a value of 0 or greater 01252 atom_arg_getlong(&var, 0, ac, av); 01253 if (val == -1) // i.e. unchanged 01254 post("it is likely that the user did not provide a valid argument"); 01255 else { 01256 ... 01257 } 01258 } 01259 @endcode 01260 */ 01261 long atom_arg_getlong(long *c, long idx, long ac, t_atom *av); 01262 01263 01264 /** 01265 Retrieves the floating point value of a particular t_atom from an atom list, if the atom exists. 01266 01267 @ingroup atom 01268 01269 @param c Pointer to a float variable to receive the atom's data if the function is successful. Otherwise, the value is left unchanged. 01270 @param idx Offset into the atom list of the atom of interest, starting from 0. 01271 For instance, if you want data from the 3rd atom in the atom list, <tt>idx</tt> should be set to 2. 01272 @param ac Count of av. 01273 @param av Pointer to the first t_atom of an atom list. 01274 01275 @return This function returns the error code #MAX_ERR_NONE if successful, 01276 or one of the other error codes defined in #e_max_errorcodes if unsuccessful. 01277 */ 01278 long atom_arg_getfloat(float *c, long idx, long ac, t_atom *av); 01279 01280 01281 /** 01282 Retrieves the floating point value, as a double, of a particular t_atom from an atom list, if the atom exists. 01283 01284 @ingroup atom 01285 01286 @param c Pointer to a double variable to receive the atom's data if the function is successful. Otherwise the value is left unchanged. 01287 @param idx Offset into the atom list of the atom of interest, starting from 0. 01288 For instance, if you want data from the 3rd atom in the atom list, <tt>idx</tt> should be set to 2. 01289 @param ac Count of av. 01290 @param av Pointer to the first t_atom of an atom list. 01291 01292 @return This function returns the error code #MAX_ERR_NONE if successful, 01293 or one of the other error codes defined in #e_max_errorcodes if unsuccessful. 01294 */ 01295 long atom_arg_getdouble(double *c, long idx, long ac, t_atom *av); 01296 01297 01298 /** 01299 Retrieves the t_symbol * value of a particular t_atom from an atom list, if the atom exists. 01300 01301 @ingroup atom 01302 01303 @param c Pointer to a t_symbol * variable to receive the atom's data if the function is successful. Otherwise, the value is left unchanged. 01304 @param idx Offset into the atom list of the atom of interest, starting from 0. 01305 For instance, if you want data from the 3rd atom in the atom list, <tt>idx</tt> should be set to 2. 01306 @param ac Count of av. 01307 @param av Pointer to the first t_atom of an atom list. 01308 01309 @return This function returns the error code #MAX_ERR_NONE if successful, 01310 or one of the other error codes defined in #e_max_errorcodes if unsuccessful. 01311 01312 @remark The atom_arg_getsym() function only changes the value of <tt>c</tt> if the function is successful. 01313 For instance, the following code snippet illustrates a simple, but typical use: 01314 @code 01315 void myobject_open(t_myobject *x, t_symbol *s, long ac, t_atom *av) 01316 { 01317 t_symbol *filename = _sym_nothing; 01318 01319 // here, we are expecting a file name. 01320 // if we don't get it, open a dialog box 01321 atom_arg_getsym(&filename, 0, ac, av); 01322 if (filename == _sym_nothing) { // i.e. unchanged 01323 // open the file dialog box, 01324 // get a value for filename 01325 } 01326 // do something with the filename 01327 } 01328 @endcode 01329 */ 01330 long atom_arg_getsym(t_symbol **c, long idx, long ac, t_atom *av); 01331 01332 01333 //attr functions 01334 01335 /** 01336 Determines the point in an atom list where attribute arguments begin. 01337 Developers can use this function to assist in the manual processing of attribute arguments, when attr_args_process() 01338 doesn't provide the correct functionality for a particular purpose. 01339 01340 @ingroup attr 01341 01342 @param ac The count of t_atoms in <tt>av</tt> 01343 @param av An atom list 01344 01345 @return This function returns an offset into the atom list, where the first attribute argument occurs. 01346 For instance, the atom list <tt>foo bar 3.0 \@mode 6</tt> would cause <tt>attr_args_offset</tt> to return 3 01347 (the attribute <tt>mode</tt> appears at position 3 in the atom list). 01348 */ 01349 long attr_args_offset(short ac, t_atom *av); 01350 01351 01352 /** 01353 Takes an atom list and properly set any attributes described within. This function is typically used in an object's <tt>new</tt> method to conveniently process attribute arguments. 01354 01355 @ingroup attr 01356 01357 @param x The object whose attributes will be processed 01358 @param ac The count of t_atoms in <tt>av</tt> 01359 @param av An atom list 01360 01361 @remark Here is a typical example of usage: 01362 @code 01363 void *myobject_new(t_symbol *s, long ac, t_atom *av) 01364 { 01365 t_myobject *x = NULL; 01366 01367 if (x=(t_myobject *)object_alloc(myobject_class)) 01368 { 01369 // initialize any data before processing 01370 // attributes to avoid overwriting 01371 // attribute argument-set values 01372 x->data = 0; 01373 01374 // process attr args, if any 01375 attr_args_process(x, ac, av); 01376 } 01377 return x; 01378 } 01379 @endcode 01380 */ 01381 void attr_args_process(void *x, short ac, t_atom *av); 01382 01383 01384 //constructors 01385 01386 01387 /** 01388 Create a new attribute. The attribute will allocate memory and store its own data. Attributes created using attribute_new() can be assigned either to classes (using the class_addattr() function) or to objects (using the object_addattr() function). 01389 01390 @ingroup attr 01391 01392 @param name A name for the attribute, as a C-string 01393 @param type A t_symbol * representing a valid attribute type. 01394 At the time of this writing, the valid type-symbols are: 01395 <tt>_sym_char</tt> (char), 01396 <tt>_sym_long</tt> (long), 01397 <tt>_sym_float32</tt> (32-bit float), 01398 <tt>_sym_float64</tt> (64-bit float), 01399 <tt>_sym_atom</tt> (Max #t_atom pointer), 01400 <tt>_sym_symbol</tt> (Max #t_symbol pointer), 01401 <tt>_sym_pointer</tt> (generic pointer) and 01402 <tt>_sym_object</tt> (Max #t_object pointer). 01403 @param flags Any attribute flags, expressed as a bitfield. 01404 Attribute flags are used to determine if an attribute is accessible for setting or querying. 01405 The available accessor flags are defined in #e_max_attrflags. 01406 @param mget The method to use for the attribute's <tt>get</tt> functionality. If <tt>mget</tt> is NULL, the default method is used. 01407 @param mset The method to use for the attribute's <tt>set</tt> functionality. If <tt>mset</tt> is NULL, the default method is used. 01408 01409 @return This function returns the new attribute's object pointer if successful, or NULL if unsuccessful. 01410 01411 @remark Developers wishing to define custom methods for <tt>get</tt> or <tt>set</tt> functionality need to prototype them as: 01412 @code 01413 t_max_err myobject_myattr_get(t_myobject *x, void *attr, long *ac, t_atom **av); 01414 @endcode 01415 @code 01416 t_max_err myobject_myattr_set(t_myobject *x, void *attr, long ac, t_atom *av); 01417 @endcode 01418 01419 @remark Implementation will vary, of course, but need to follow the following basic models. 01420 Note that, as with custom <tt>getvalueof</tt> and <tt>setvalueof</tt> methods for the object, 01421 assumptions are made throughout Max that getbytes() has been used for memory allocation. 01422 Developers are strongly urged to do the same: 01423 @code 01424 t_max_err myobject_myattr_get(t_myobject *x, void *attr, long *ac, t_atom **av) 01425 { 01426 if (*ac && *av) 01427 // memory passed in; use it 01428 else { 01429 *ac = 1; // size of attr data 01430 *av = (t_atom *)getbytes(sizeof(t_atom) * (*ac)); 01431 if (!(*av)) { 01432 *ac = 0; 01433 return MAX_ERR_OUT_OF_MEM; 01434 } 01435 } 01436 atom_setlong(*av, x->some_value); 01437 return MAX_ERR_NONE; 01438 } 01439 01440 t_max_err myobject_myattr_set(t_myobject *x, void *attr, long ac, t_atom *av) 01441 { 01442 if (ac && av) { 01443 x->some_value = atom_getlong(av); 01444 } 01445 return MAX_ERR_NONE; 01446 } 01447 @endcode 01448 */ 01449 t_object *attribute_new(char *name, t_symbol *type, long flags, method mget, method mset); 01450 01451 01452 /** 01453 Create a new attribute. The attribute references memory stored outside of itself, in the object's data structure. Attributes created using attr_offset_new() can be assigned either to classes (using the class_addattr() function) or to objects (using the object_addattr() function). 01454 01455 @ingroup attr 01456 01457 @param name A name for the attribute, as a C-string 01458 @param type A t_symbol * representing a valid attribute type. 01459 At the time of this writing, the valid type-symbols are: 01460 <tt>_sym_char</tt> (char), 01461 <tt>_sym_long</tt> (long), 01462 <tt>_sym_float32</tt> (32-bit float), 01463 <tt>_sym_float64</tt> (64-bit float), 01464 <tt>_sym_atom</tt> (Max #t_atom pointer), 01465 <tt>_sym_symbol</tt> (Max #t_symbol pointer), 01466 <tt>_sym_pointer</tt> (generic pointer) and 01467 <tt>_sym_object</tt> (Max #t_object pointer). 01468 @param flags Any attribute flags, expressed as a bitfield. 01469 Attribute flags are used to determine if an attribute is accessible for setting or querying. 01470 The available accessor flags are defined in #e_max_attrflags. 01471 @param mget The method to use for the attribute's <tt>get</tt> functionality. 01472 If <tt>mget</tt> is NULL, the default method is used. See the discussion under attribute_new(), for more information. 01473 @param mset The method to use for the attribute's <tt>set</tt> functionality. 01474 If <tt>mset</tt> is NULL, the default method is used. See the discussion under attribute_new(), for more information. 01475 @param offset Byte offset into the class data structure of the object which will "own" the attribute. 01476 The offset should point to the data to be referenced by the attribute. 01477 Typically, the #calcoffset macro (described above) is used to calculate this offset. 01478 01479 @return This function returns the new attribute's object pointer if successful, or NULL if unsuccessful. 01480 01481 @remark For instance, to create a new attribute which references the value of a double variable (<tt>val</tt>) in an object class's data structure: 01482 @code 01483 t_object *attr = attr_offset_new("myattr", _sym_float64 / * matches data size * /, 0 / * no flags * /, (method)0L, (method)0L, calcoffset(t_myobject, val)); 01484 @endcode 01485 */ 01486 t_object *attr_offset_new(char *name, t_symbol *type, long flags, method mget, method mset, long offset); 01487 01488 01489 /** 01490 Create a new attribute. The attribute references an array of memory stored outside of itself, in the object's data structure. Attributes created using attr_offset_array_new() can be assigned either to classes (using the class_addattr() function) or to objects (using the object_addattr() function). 01491 01492 @ingroup attr 01493 01494 @param name A name for the attribute, as a C-string 01495 @param type A t_symbol * representing a valid attribute type. 01496 At the time of this writing, the valid type-symbols are: 01497 <tt>_sym_char</tt> (char), 01498 <tt>_sym_long</tt> (long), 01499 <tt>_sym_float32</tt> (32-bit float), 01500 <tt>_sym_float64</tt> (64-bit float), 01501 <tt>_sym_atom</tt> (Max #t_atom pointer), 01502 <tt>_sym_symbol</tt> (Max #t_symbol pointer), 01503 <tt>_sym_pointer</tt> (generic pointer) and 01504 <tt>_sym_object</tt> (Max #t_object pointer). 01505 @param size Maximum number of items that may be in the array. 01506 @param flags Any attribute flags, expressed as a bitfield. 01507 Attribute flags are used to determine if an attribute is accessible for setting or querying. 01508 The available accessor flags are defined in #e_max_attrflags. 01509 @param mget The method to use for the attribute's <tt>get</tt> functionality. 01510 If <tt>mget</tt> is NULL, the default method is used. See the discussion under attribute_new(), for more information. 01511 @param mset The method to use for the attribute's <tt>set</tt> functionality. 01512 If <tt>mset</tt> is NULL, the default method is used. See the discussion under attribute_new(), for more information. 01513 @param offsetcount Byte offset into the object class's data structure of a long variable describing how many array elements 01514 (up to <tt>size</tt>) comprise the data to be referenced by the attribute. 01515 Typically, the #calcoffset macro is used to calculate this offset. 01516 @param offset Byte offset into the class data structure of the object which will "own" the attribute. 01517 The offset should point to the data to be referenced by the attribute. 01518 Typically, the #calcoffset macro is used to calculate this offset. 01519 01520 @return This function returns the new attribute's object pointer if successful, or NULL if unsuccessful. 01521 01522 @remark For instance, to create a new attribute which references an array of 10 t_atoms (<tt>atm</tt>; 01523 the current number of "active" elements in the array is held in the variable <tt>atmcount</tt>) in an object class's data structure: 01524 @code 01525 t_object *attr = attr_offset_array_new("myattrarray", _sym_atom / * matches data size * /, 10 / * max * /, 0 / * no flags * /, (method)0L, (method)0L, calcoffset(t_myobject, atmcount) / * count * /, calcoffset(t_myobject, atm) / * data * /); 01526 @endcode 01527 */ 01528 t_object *attr_offset_array_new(char *name, t_symbol *type, long size, long flags, method mget, method mset, long offsetcount, long offset); 01529 01530 01531 t_object *attr_filter_clip_new(void); 01532 01533 01534 t_object *attr_filter_proc_new(method proc); 01535 01536 01537 //for easy access of simple attributes 01538 01539 /** 01540 Retrieves the value of an attribute, given its parent object and name. 01541 01542 @ingroup attr 01543 01544 @param x The attribute's parent object 01545 @param s The attribute's name 01546 01547 @return This function returns the value of the specified attribute, if successful, or 0, if unsuccessful. 01548 01549 @remark If the attribute is not of the type specified by the function, the 01550 function will attempt to coerce a valid value from the attribute. 01551 */ 01552 long object_attr_getlong(void *x, t_symbol *s); 01553 01554 01555 /** 01556 Sets the value of an attribute, given its parent object and name. The function will call the attribute's <tt>set</tt> method, using the data provided. 01557 01558 @ingroup attr 01559 01560 @param x The attribute's parent object 01561 @param s The attribute's name 01562 @param c An integer value; the new value for the attribute 01563 01564 @return This function returns the error code #MAX_ERR_NONE if successful, 01565 or one of the other error codes defined in #e_max_errorcodes if unsuccessful. 01566 */ 01567 t_max_err object_attr_setlong(void *x, t_symbol *s, long c); 01568 01569 01570 /** 01571 Retrieves the value of an attribute, given its parent object and name. 01572 01573 @ingroup attr 01574 01575 @param x The attribute's parent object 01576 @param s The attribute's name 01577 01578 @return This function returns the value of the specified attribute, if successful, or 0, if unsuccessful. 01579 01580 @remark If the attribute is not of the type specified by the function, the 01581 function will attempt to coerce a valid value from the attribute. 01582 */ 01583 float object_attr_getfloat(void *x, t_symbol *s); 01584 01585 01586 /** 01587 Sets the value of an attribute, given its parent object and name. The function will call the attribute's <tt>set</tt> method, using the data provided. 01588 01589 @ingroup attr 01590 01591 @param x The attribute's parent object 01592 @param s The attribute's name 01593 @param c An floating point value; the new value for the attribute 01594 01595 @return This function returns the error code #MAX_ERR_NONE if successful, 01596 or one of the other error codes defined in #e_max_errorcodes if unsuccessful. 01597 */ 01598 t_max_err object_attr_setfloat(void *x, t_symbol *s, float c); 01599 01600 01601 /** 01602 Retrieves the value of an attribute, given its parent object and name. 01603 01604 @ingroup attr 01605 01606 @param x The attribute's parent object 01607 @param s The attribute's name 01608 01609 @return This function returns the value of the specified attribute, if successful, or the empty symbol (equivalent to <tt>gensym("")</tt> or <tt>_sym_nothing</tt>), if unsuccessful. 01610 */ 01611 t_symbol *object_attr_getsym(void *x, t_symbol *s); 01612 01613 01614 /** 01615 Sets the value of an attribute, given its parent object and name. The function will call the attribute's <tt>set</tt> method, using the data provided. 01616 01617 @ingroup attr 01618 01619 @param x The attribute's parent object 01620 @param s The attribute's name 01621 @param c A t_symbol *; the new value for the attribute 01622 01623 @return This function returns the error code #MAX_ERR_NONE if successful, 01624 or one of the other error codes defined in #e_max_errorcodes if unsuccessful. 01625 */ 01626 t_max_err object_attr_setsym(void *x, t_symbol *s, t_symbol *c); 01627 01628 01629 char object_attr_getchar(void *x, t_symbol *s); 01630 t_max_err object_attr_setchar(void *x, t_symbol *s, char c); 01631 t_object* object_attr_getobj(void *x, t_symbol *s); 01632 t_max_err object_attr_setobj(void *x, t_symbol *s, t_object *o); 01633 01634 01635 /** 01636 Retrieves the value of an attribute, given its parent object and name. 01637 This function uses a developer-allocated array to copy data to. 01638 Developers wishing to retrieve the value of an attribute without pre-allocating memory should refer to the object_attr_getvalueof() function. 01639 01640 @ingroup attr 01641 01642 @param x The attribute's parent object 01643 @param s The attribute's name 01644 @param max The number of array elements in <tt>vals</tt>. The function will take care not to overwrite the bounds of the array. 01645 @param vals Pointer to the first element of a pre-allocated array of long data. 01646 01647 @return This function returns the number of elements copied into <tt>vals</tt>. 01648 01649 @remark If the attribute is not of the type specified by the function, the 01650 function will attempt to coerce a valid value from the attribute. 01651 */ 01652 long object_attr_getlong_array(void *x, t_symbol *s, long max, long *vals); 01653 01654 01655 /** 01656 Sets the value of an attribute, given its parent object and name. The function will call the attribute's <tt>set</tt> method, using the data provided. 01657 01658 @ingroup attr 01659 01660 @param x The attribute's parent object 01661 @param s The attribute's name 01662 @param count The number of array elements in vals 01663 @param vals Pointer to the first element of an array of long data 01664 01665 @return This function returns the error code #MAX_ERR_NONE if successful, 01666 or one of the other error codes defined in #e_max_errorcodes if unsuccessful. 01667 */ 01668 t_max_err object_attr_setlong_array(void *x, t_symbol *s, long count, long *vals); 01669 01670 01671 /** 01672 Retrieves the value of an attribute, given its parent object and name. 01673 This function uses a developer-allocated array to copy data to. 01674 Developers wishing to retrieve the value of an attribute without pre-allocating memory should refer to the object_attr_getvalueof() function. 01675 01676 @ingroup attr 01677 01678 @param x The attribute's parent object 01679 @param s The attribute's name 01680 @param max The number of array elements in <tt>vals</tt>. The function will take care not to overwrite the bounds of the array. 01681 @param vals Pointer to the first element of a pre-allocated array of unsigned char data. 01682 01683 @return This function returns the number of elements copied into <tt>vals</tt>. 01684 01685 @remark If the attribute is not of the type specified by the function, the 01686 function will attempt to coerce a valid value from the attribute. 01687 */ 01688 long object_attr_getchar_array(void *x, t_symbol *s, long max, uchar *vals); 01689 01690 01691 /** 01692 Sets the value of an attribute, given its parent object and name. The function will call the attribute's <tt>set</tt> method, using the data provided. 01693 01694 @ingroup attr 01695 01696 @param x The attribute's parent object 01697 @param s The attribute's name 01698 @param count The number of array elements in vals 01699 @param vals Pointer to the first element of an array of unsigned char data 01700 01701 @return This function returns the error code #MAX_ERR_NONE if successful, 01702 or one of the other error codes defined in #e_max_errorcodes if unsuccessful. 01703 */ 01704 t_max_err object_attr_setchar_array(void *x, t_symbol *s, long count, uchar *vals); 01705 01706 01707 /** 01708 Retrieves the value of an attribute, given its parent object and name. 01709 This function uses a developer-allocated array to copy data to. 01710 Developers wishing to retrieve the value of an attribute without pre-allocating memory should refer to the object_attr_getvalueof() function. 01711 01712 @ingroup attr 01713 01714 @param x The attribute's parent object 01715 @param s The attribute's name 01716 @param max The number of array elements in <tt>vals</tt>. The function will take care not to overwrite the bounds of the array. 01717 @param vals Pointer to the first element of a pre-allocated array of float data. 01718 01719 @return This function returns the number of elements copied into <tt>vals</tt>. 01720 01721 @remark If the attribute is not of the type specified by the function, the 01722 function will attempt to coerce a valid value from the attribute. 01723 */ 01724 long object_attr_getfloat_array(void *x, t_symbol *s, long max, float *vals); 01725 01726 01727 /** 01728 Sets the value of an attribute, given its parent object and name. The function will call the attribute's <tt>set</tt> method, using the data provided. 01729 01730 @ingroup attr 01731 01732 @param x The attribute's parent object 01733 @param s The attribute's name 01734 @param count The number of array elements in vals 01735 @param vals Pointer to the first element of an array of float data 01736 01737 @return This function returns the error code #MAX_ERR_NONE if successful, 01738 or one of the other error codes defined in #e_max_errorcodes if unsuccessful. 01739 */ 01740 t_max_err object_attr_setfloat_array(void *x, t_symbol *s, long count, float *vals); 01741 01742 01743 /** 01744 Retrieves the value of an attribute, given its parent object and name. 01745 This function uses a developer-allocated array to copy data to. 01746 Developers wishing to retrieve the value of an attribute without pre-allocating memory should refer to the object_attr_getvalueof() function. 01747 01748 @ingroup attr 01749 01750 @param x The attribute's parent object 01751 @param s The attribute's name 01752 @param max The number of array elements in <tt>vals</tt>. The function will take care not to overwrite the bounds of the array. 01753 @param vals Pointer to the first element of a pre-allocated array of double data. 01754 01755 @return This function returns the number of elements copied into <tt>vals</tt>. 01756 01757 @remark If the attribute is not of the type specified by the function, the 01758 function will attempt to coerce a valid value from the attribute. 01759 */ 01760 long object_attr_getdouble_array(void *x, t_symbol *s, long max, double *vals); 01761 01762 01763 /** 01764 Sets the value of an attribute, given its parent object and name. The function will call the attribute's <tt>set</tt> method, using the data provided. 01765 01766 @ingroup attr 01767 01768 @param x The attribute's parent object 01769 @param s The attribute's name 01770 @param count The number of array elements in vals 01771 @param vals Pointer to the first element of an array of double data 01772 01773 @return This function returns the error code #MAX_ERR_NONE if successful, 01774 or one of the other error codes defined in #e_max_errorcodes if unsuccessful. 01775 */ 01776 t_max_err object_attr_setdouble_array(void *x, t_symbol *s, long count, double *vals); 01777 01778 01779 /** 01780 Retrieves the value of an attribute, given its parent object and name. 01781 This function uses a developer-allocated array to copy data to. 01782 Developers wishing to retrieve the value of an attribute without pre-allocating memory should refer to the object_attr_getvalueof() function. 01783 01784 @ingroup attr 01785 01786 @param x The attribute's parent object 01787 @param s The attribute's name 01788 @param max The number of array elements in <tt>vals</tt>. The function will take care not to overwrite the bounds of the array. 01789 @param vals Pointer to the first element of a pre-allocated array of #t_symbol *s. 01790 01791 @return This function returns the number of elements copied into <tt>vals</tt>. 01792 */ 01793 long object_attr_getsym_array(void *x, t_symbol *s, long max, t_symbol **vals); 01794 01795 01796 /** 01797 Sets the value of an attribute, given its parent object and name. 01798 The function will call the attribute's <tt>set</tt> method, using the data provided. 01799 01800 @ingroup attr 01801 01802 @param x The attribute's parent object 01803 @param s The attribute's name 01804 @param count The number of array elements in vals 01805 @param vals Pointer to the first element of an array of #t_symbol *s 01806 01807 @return This function returns the error code #MAX_ERR_NONE if successful, 01808 or one of the other error codes defined in #e_max_errorcodes if unsuccessful. 01809 */ 01810 t_max_err object_attr_setsym_array(void *x, t_symbol *s, long count, t_symbol **vals); 01811 01812 01813 //attr filters util 01814 01815 /** 01816 Attaches a clip filter to an attribute. 01817 The filter will <em>only</em> clip values sent to the attribute using the attribute's <tt>set</tt> function. 01818 01819 @ingroup attr 01820 01821 @param x Pointer to the attribute to receive the filter 01822 @param min Minimum value for the clip filter 01823 @param max Maximum value for the clip filter 01824 @param usemin Sets this value to 0 if the minimum clip value should <em>not</em> be used. Otherwise, set the value to non-zero. 01825 @param usemax Sets this value to 0 if the minimum clip value should <em>not</em> be used. Otherwise, set the value to non-zero. 01826 01827 @return This function returns the error code #MAX_ERR_NONE if successful, 01828 or one of the other error codes defined in #e_max_errorcodes if unsuccessful. 01829 */ 01830 t_max_err attr_addfilterset_clip(void *x, double min, double max, long usemin, long usemax); 01831 01832 01833 /** 01834 Attaches a clip/scale filter to an attribute. 01835 The filter will <em>only</em> clip and scale values sent to the attribute using the attribute's <tt>set</tt> function. 01836 01837 @ingroup attr 01838 01839 @param x Pointer to the attribute to receive the filter 01840 @param scale Scale value. Data sent to the attribute will be scaled by this amount. <em>Scaling occurs previous to clipping</em>. 01841 @param min Minimum value for the clip filter 01842 @param max Maximum value for the clip filter 01843 @param usemin Sets this value to 0 if the minimum clip value should <em>not</em> be used. Otherwise, set the value to non-zero. 01844 @param usemax Sets this value to 0 if the minimum clip value should <em>not</em> be used. Otherwise, set the value to non-zero. 01845 01846 @return This function returns the error code #MAX_ERR_NONE if successful, 01847 or one of the other error codes defined in #e_max_errorcodes if unsuccessful. 01848 */ 01849 t_max_err attr_addfilterset_clip_scale(void *x, double scale, double min, double max, long usemin, long usemax); 01850 01851 01852 /** 01853 Attaches a clip filter to an attribute. 01854 The filter will <em>only</em> clip values retrieved from the attribute using the attribute's <tt>get</tt> function. 01855 01856 @ingroup attr 01857 01858 @param x Pointer to the attribute to receive the filter 01859 @param min Minimum value for the clip filter 01860 @param max Maximum value for the clip filter 01861 @param usemin Sets this value to 0 if the minimum clip value should <em>not</em> be used. Otherwise, set the value to non-zero. 01862 @param usemax Sets this value to 0 if the minimum clip value should <em>not</em> be used. Otherwise, set the value to non-zero. 01863 01864 @return This function returns the error code #MAX_ERR_NONE if successful, 01865 or one of the other error codes defined in #e_max_errorcodes if unsuccessful. 01866 */ 01867 t_max_err attr_addfilterget_clip(void *x, double min, double max, long usemin, long usemax); 01868 01869 01870 /** 01871 Attaches a clip/scale filter to an attribute. 01872 The filter will <em>only</em> clip and scale values retrieved from the attribute using the attribute's <tt>get</tt> function. 01873 01874 @ingroup attr 01875 01876 @param x Pointer to the attribute to receive the filter 01877 @param scale Scale value. Data retrieved from the attribute will be scaled by this amount. <em>Scaling occurs previous to clipping</em>. 01878 @param min Minimum value for the clip filter 01879 @param max Maximum value for the clip filter 01880 @param usemin Sets this value to 0 if the minimum clip value should <em>not</em> be used. Otherwise, set the value to non-zero. 01881 @param usemax Sets this value to 0 if the minimum clip value should <em>not</em> be used. Otherwise, set the value to non-zero. 01882 01883 @return This function returns the error code #MAX_ERR_NONE if successful, 01884 or one of the other error codes defined in #e_max_errorcodes if unsuccessful. 01885 */ 01886 t_max_err attr_addfilterget_clip_scale(void *x, double scale, double min, double max, long usemin, long usemax); 01887 01888 01889 /** 01890 Attaches a clip filter to an attribute. 01891 The filter will clip any values sent to or retrieved from the attribute using the attribute's <tt>get</tt> and <tt>set</tt> functions. 01892 01893 @ingroup attr 01894 01895 @param x Pointer to the attribute to receive the filter 01896 @param min Minimum value for the clip filter 01897 @param max Maximum value for the clip filter 01898 @param usemin Sets this value to 0 if the minimum clip value should <em>not</em> be used. Otherwise, set the value to non-zero. 01899 @param usemax Sets this value to 0 if the minimum clip value should <em>not</em> be used. Otherwise, set the value to non-zero. 01900 01901 @return This function returns the error code #MAX_ERR_NONE if successful, 01902 or one of the other error codes defined in #e_max_errorcodes if unsuccessful. 01903 */ 01904 t_max_err attr_addfilter_clip(void *x, double min, double max, long usemin, long usemax); 01905 01906 01907 /** 01908 Attaches a clip/scale filter to an attribute. 01909 The filter will clip and scale any values sent to or retrieved from the attribute using the attribute's <tt>get</tt> and <tt>set</tt> functions. 01910 01911 @ingroup attr 01912 01913 @param x Pointer to the attribute to receive the filter 01914 @param scale Scale value. Data sent to the attribute will be scaled by this amount. Data retrieved from the attribute will be scaled by its reciprocal. 01915 <em>Scaling occurs previous to clipping</em>. 01916 @param min Minimum value for the clip filter 01917 @param max Maximum value for the clip filter 01918 @param usemin Sets this value to 0 if the minimum clip value should <em>not</em> be used. Otherwise, set the value to non-zero. 01919 @param usemax Sets this value to 0 if the minimum clip value should <em>not</em> be used. Otherwise, set the value to non-zero. 01920 01921 @return This function returns the error code #MAX_ERR_NONE if successful, 01922 or one of the other error codes defined in #e_max_errorcodes if unsuccessful. 01923 */ 01924 t_max_err attr_addfilter_clip_scale(void *x, double scale, double min, double max, long usemin, long usemax); 01925 01926 01927 /** 01928 Attaches a custom filter method to an attribute. 01929 The filter will <em>only</em> be called for values retrieved from the attribute using the attribute's <tt>set</tt> function. 01930 01931 @ingroup attr 01932 01933 @param x Pointer to the attribute to receive the filter 01934 @param proc A filter method 01935 01936 @return This function returns the error code #MAX_ERR_NONE if successful, 01937 or one of the other error codes defined in #e_max_errorcodes if unsuccessful. 01938 01939 @remark The filter method should be prototyped and implemented as follows: 01940 @code 01941 t_max_err myfiltermethod(void *parent, void *attr, long ac, t_atom *av); 01942 01943 t_max_err myfiltermethod(void *parent, void *attr, long ac, t_atom *av) 01944 { 01945 long i; 01946 float temp, 01947 01948 // this filter rounds off all values 01949 // assumes that the data is float 01950 for (i = 0; i < ac; i++) { 01951 temp = atom_getfloat(av + i); 01952 temp = (float)((long)(temp + 0.5)); 01953 atom_setfloat(av + i, temp); 01954 } 01955 return MAX_ERR_NONE; 01956 } 01957 @endcode 01958 */ 01959 t_max_err attr_addfilterset_proc(void *x, method proc); 01960 01961 01962 /** 01963 Attaches a custom filter method to an attribute. The filter will <em>only</em> be called for values retrieved from the attribute using the attribute's <tt>get</tt> function. 01964 01965 @ingroup attr 01966 01967 @param x Pointer to the attribute to receive the filter 01968 @param proc A filter method 01969 01970 @return This function returns the error code #MAX_ERR_NONE if successful, 01971 or one of the other error codes defined in #e_max_errorcodes if unsuccessful. 01972 01973 @remark The filter method should be prototyped and implemented as described above for the attr_addfilterset_proc() function. 01974 */ 01975 t_max_err attr_addfilterget_proc(void *x, method proc); 01976 01977 01978 //more util functions 01979 01980 /** 01981 Generates a unique #t_symbol *. The symbol will be formatted somewhat like "u123456789". 01982 01983 @ingroup misc 01984 @return This function returns a unique #t_symbol *. 01985 */ 01986 t_symbol *symbol_unique(); 01987 01988 01989 void error_code(void *x,t_max_err v); //interrupt safe 01990 01991 01992 /** 01993 Posts an error message to the Max window. This function is interrupt safe. 01994 01995 @ingroup misc 01996 01997 @param x The object's pointer 01998 @param s Symbol to be posted as an error in the Max window 01999 */ 02000 void error_sym(void *x,t_symbol *s); //interrupt safe 02001 02002 02003 /** 02004 Posts a message to the Max window. This function is interrupt safe. 02005 02006 @ingroup misc 02007 @param x The object's pointer 02008 @param s Symbol to be posted in the Max window 02009 */ 02010 void post_sym(void *x,t_symbol *s); //interrupt safe 02011 02012 02013 /** 02014 Performs an ASCII sort on an array of #t_symbol *s. 02015 02016 @ingroup misc 02017 02018 @param ac The count of #t_symbol *s in <tt>av</tt> 02019 @param av An array of #t_symbol *s to be sorted 02020 02021 @return This function returns the error code #MAX_ERR_NONE if successful, 02022 or one of the other error codes defined in #e_max_errorcodes if unsuccessful. 02023 */ 02024 t_max_err symbolarray_sort(long ac, t_symbol **av); 02025 02026 02027 /** 02028 Developers do not need to directly use the object_obex_quickref() function. 02029 It was used in Max 4 to add support for attributes to the quickref, but this is automatic in Max 5. 02030 02031 @ingroup misc 02032 */ 02033 void object_obex_quickref(void *x, long *numitems, t_symbol **items); 02034 02035 02036 method class_menufun_get(t_class *c); 02037 02038 02039 // new for Max 5 (some headers might change) 02040 #include "ext_obex_util.h" 02041 #include "ext_dictionary.h" 02042 #include "ext_obstring.h" 02043 02044 long class_clonable(t_class *x); 02045 long object_clonable(t_object *x); 02046 t_max_err class_buildprototype(t_class *x); 02047 t_dictionary *class_cloneprototype(t_class *x); 02048 02049 02050 /** 02051 Create a dictionary of attribute-name, attribute-value pairs 02052 from an array of atoms containing an attribute definition list. 02053 02054 @ingroup attr 02055 @param x A dictionary instance pointer. 02056 @param ac The number of atoms to parse in av. 02057 @param av A pointer to the first of the array of atoms containing the attribute values. 02058 02059 @remark The code example below shows the creation of a list of atoms using atom_setparse(), 02060 and then uses that list of atoms to fill the dictionary with attr_args_dictionary(). 02061 @code 02062 long ac = 0; 02063 t_atom *av = NULL; 02064 char parsebuf[4096]; 02065 t_dictionary *d = dictionary_new(); 02066 t_atom a; 02067 02068 sprintf(parsebuf,"@defrect %.6f %.6f %.6f %.6f @title Untitled @presentation 0 ", r->x, r->y, r->width, r->height); 02069 atom_setparse(&ac, &av, parsebuf); 02070 attr_args_dictionary(d, ac, av); 02071 atom_setobj(&a, d); 02072 @endcode 02073 */ 02074 void attr_args_dictionary(t_dictionary *x, short ac, t_atom *av); 02075 02076 02077 /** 02078 Set attributes for an object that are defined in a dictionary. 02079 Objects with dictionary constructors, such as UI objects, 02080 should call this method to set their attributes when an object is created. 02081 02082 @ingroup attr 02083 @param x The object instance pointer. 02084 @param d The dictionary containing the attributes. 02085 @see attr_args_process() 02086 */ 02087 void attr_dictionary_process(void *x, t_dictionary *d); 02088 02089 02090 /** 02091 Retrieve a pointer to a dictionary passed in as an atom argument. 02092 Use this function when working with classes that have dictionary constructors 02093 to fetch the dictionary. 02094 02095 @ingroup obj 02096 @param ac The number of atoms. 02097 @param av A pointer to the first atom in the array. 02098 @return The dictionary retrieved from the atoms. 02099 @see attr_dictionary_process() 02100 */ 02101 t_dictionary *object_dictionaryarg(long ac, t_atom *av); 02102 02103 02104 // use the macros for these in ext_obex_util.h 02105 t_max_err class_sticky(t_class *x, t_symbol *stickyname, t_symbol *s, t_object *o); 02106 t_max_err class_sticky_clear(t_class *x, t_symbol *stickyname, t_symbol *s); 02107 02108 02109 // private -- internal use only (and perhaps not exported?) 02110 t_max_err object_retain(t_object *x); 02111 t_max_err object_release(t_object *x); 02112 02113 typedef struct _method_object 02114 { 02115 t_object ob; 02116 t_messlist messlist_entry; 02117 } t_method_object; 02118 02119 t_method_object *method_object_new(method m, char *name, ...); 02120 t_method_object *method_object_new_messlist(t_messlist *m); 02121 void method_object_free(t_method_object *x); 02122 t_symbol *method_object_getname(t_method_object *x); 02123 void method_object_setname(t_method_object *x, t_symbol *s); 02124 method method_object_getmethod(t_method_object *x); 02125 void method_object_setmethod(t_method_object *x, method m); 02126 t_messlist *method_object_getmesslist(t_method_object *x); 02127 void method_object_setmesslist(t_method_object *x, t_messlist *m); 02128 02129 t_method_object *class_getmethod_object(t_class *x, t_symbol *methodname); 02130 02131 // these methods are private -- instance methods are not actually fully implemented at this time 02132 t_method_object *object_getmethod_object(t_object *x, t_symbol *methodname); 02133 02134 t_max_err object_attrhash_apply(t_object *x, t_hashtab *attrhash); 02135 t_max_err object_sticky(t_object *x, t_symbol *stickyname, t_symbol *s, t_object *o); 02136 t_max_err object_sticky_clear(t_object *x, t_symbol *stickyname, t_symbol *s); 02137 02138 // these methods are private -- instance methods are not actually fully implemented at this time 02139 t_max_err object_addmethod(t_object *x, method m, char *name, ...); 02140 t_max_err object_addmethod_object(t_object *x, t_object *mo); 02141 t_max_err object_deletemethod(t_object *x, t_symbol *methodsym); 02142 t_max_err object_chuckmethod(t_object *x, t_symbol *methodsym); 02143 02144 t_max_err attr_typedfun_set(void *parent, t_object *x, long ac, t_atom *av); 02145 02146 02147 /** 02148 Allocate a single atom. 02149 If ac and av are both zero then memory is allocated. 02150 Otherwise it is presumed that memory is already allocated and nothing will happen. 02151 02152 @ingroup atom 02153 @param ac The address of a variable that will contain the number of atoms allocated (1). 02154 @param av The address of a pointer that will be set with the new allocated memory for the atom. 02155 @param alloc Address of a variable that will be set true is memory is allocated, otherwise false. 02156 @return A Max error code. 02157 */ 02158 t_max_err atom_alloc(long *ac, t_atom **av, char *alloc); 02159 02160 02161 /** 02162 Allocate an array of atoms. 02163 If ac and av are both zero then memory is allocated. 02164 Otherwise it is presumed that memory is already allocated and nothing will happen. 02165 02166 @ingroup atom 02167 @param minsize The minimum number of atoms that this array will need to contain. 02168 This determines the amount of memory allocated. 02169 @param ac The address of a variable that will contain the number of atoms allocated. 02170 @param av The address of a pointer that will be set with the new allocated memory for the atoms. 02171 @param alloc Address of a variable that will be set true is memory is allocated, otherwise false. 02172 @return A Max error code. 02173 */ 02174 t_max_err atom_alloc_array(long minsize, long *ac, t_atom **av, char *alloc); 02175 02176 02177 02178 // private? 02179 long class_is_box(t_class *c); 02180 02181 02182 /** 02183 Determine if a class is a user interface object. 02184 02185 @ingroup class 02186 @param c The class pointer. 02187 @return True is the class defines a user interface object, otherwise false. 02188 */ 02189 long class_is_ui(t_class *c); 02190 02191 02192 #if C74_PRAGMA_STRUCT_PACKPUSH 02193 #pragma pack(pop) 02194 #elif C74_PRAGMA_STRUCT_PACK 02195 #pragma pack() 02196 #endif 02197 02198 #ifdef __cplusplus 02199 } 02200 #endif // __cplusplus 02201 02202 #endif // __OBEX_H__
Copyright © 2008, Cycling '74