Max 5 API Reference
00001 /* ext_proto.h -- prototypes for MAX external methods */ 00002 /* copyright 1996 Opcode/IRCAM */ 00003 #ifndef _EXT_PROTO_H_ 00004 #define _EXT_PROTO_H_ 00005 00006 #include "ext_types.h" 00007 #include "ext_maxtypes.h" // contains box, patcher, wind, atombuf 00008 #include "ext_sysmem.h" 00009 #include "ext_sysfile.h" 00010 #include "ext_systime.h" 00011 #include "ext_expr.h" 00012 #include "ext_path.h" 00013 #include "ext_qtimage.h" 00014 #include "ext_wind.h" 00015 #ifdef WIN_VERSION 00016 #include "ext_proto_win.h" 00017 #endif 00018 00019 #ifdef __cplusplus 00020 extern "C" { 00021 #endif 00022 00023 00024 // object/class functions 00025 00026 /** Use the setup() function to initialize your class by informing Max of its size, 00027 the name of your functions that create and destroy instances, 00028 and the types of arguments passed to the instance creation function. 00029 00030 @ingroup class_old 00031 00032 @param ident A global variable in your code that points to the initialized class. 00033 @param makefun Your instance creation function. 00034 @param freefun Your instance free function (see Chapter 7). 00035 @param size The size of your objects data structure in bytes. 00036 Usually you use the C sizeof operator here. 00037 @param menufun No longer used. You should pass NULL for this parameter. 00038 @param type The first of a list of arguments passed to makefun when an object is created. 00039 @param ... Any additional arguments passed to makefun when an object is created. 00040 Together with the type parameter, this creates a standard Max type list 00041 as enumerated in #e_max_atomtypes. 00042 The final argument of the type list should be a 0. 00043 @see @ref chapter_anatomy 00044 */ 00045 void setup(t_messlist **ident, method makefun, method freefun, short size, method menufun, short type, ...); 00046 00047 00048 /** Use addmess() to bind a function to a message other than the standard ones 00049 covered by addbang(), addint(), etc. 00050 00051 @ingroup class_old 00052 @param f Function you want to be the method. 00053 @param s C string defining the message. 00054 @param type The first of one or more integers from #e_max_atomtypes specifying the arguments to the message. 00055 @param ... Any additional types from #e_max_atomtypes for additonal arguments. 00056 @see @ref chapter_anatomy 00057 */ 00058 void addmess(method f, char *s, short type, ...); 00059 00060 00061 /** 00062 Used to bind a function to the common triggering message bang. 00063 00064 @ingroup class_old 00065 @param f Function to be the bang method. 00066 */ 00067 void addbang(method f); 00068 00069 00070 /** 00071 Use addint() to bind a function to the int message received in the leftmost inlet. 00072 @ingroup class_old 00073 @param f Function to be the int method. 00074 */ 00075 void addint(method f); 00076 00077 00078 /** 00079 Use addfloat() to bind a function to the float message received in the leftmost inlet. 00080 @ingroup class_old 00081 @param f Function to be the int method. 00082 */ 00083 void addfloat(method f); 00084 00085 00086 /** 00087 Use addinx() to bind a function to a int message that will be received in 00088 an inlet other than the leftmost one. 00089 00090 @ingroup class_old 00091 @param f Function to be the int method. 00092 @param n Number of the inlet connected to this method. 00093 1 is the first inlet to the right of the left inlet. 00094 00095 @remark This correspondence between inlet locations and messages is not 00096 automatic, but it is strongly suggested that you follow existing practice. 00097 You must set the correspondence up when creating an object of your 00098 class with proper use of intin and floatin in your instance creation 00099 function @ref chapter_anatomy_object_new. 00100 */ 00101 void addinx(method f, short n); 00102 00103 00104 /** 00105 Use addftx() to bind a function to a float message that will be received in 00106 an inlet other than the leftmost one. 00107 00108 @ingroup class_old 00109 @param f Function to be the float method. 00110 @param n Number of the inlet connected to this method. 00111 1 is the first inlet to the right of the left inlet. 00112 00113 @remark This correspondence between inlet locations and messages is not 00114 automatic, but it is strongly suggested that you follow existing practice. 00115 You must set the correspondence up when creating an object of your 00116 class with proper use of intin and floatin in your instance creation 00117 function @ref chapter_anatomy_object_new. 00118 */ 00119 void addftx(method f, short n); 00120 00121 00122 /** 00123 Use newobject to allocate the space for an instance of your class and 00124 initialize its object header. 00125 00126 @ingroup class_old 00127 @param maxclass The global class variable initialized in your main routine by the setup function. 00128 @return A pointer to the new instance. 00129 00130 @remark You call newobject() when creating an instance of your class in your 00131 creation function. newobject allocates the proper amount of memory 00132 for an object of your class and installs a pointer to your class in the 00133 object, so that it can respond with your class’s methods if it receives a 00134 message. 00135 */ 00136 void *newobject(void *maxclass); 00137 00138 00139 /** 00140 Release the memory used by a Max object. 00141 freeobject() calls an object’s free function, if any, then disposes the 00142 memory used by the object itself. freeobject() should be used on any 00143 instance of a standard Max object data structure, with the exception of 00144 Qelems and Atombufs. Clocks, Binbufs, Proxies, Exprs, etc. should be freed with freeobject(). 00145 00146 @ingroup class_old 00147 @param op The object instance pointer to free. 00148 00149 @remark This function can be replaced by the use of object_free(). 00150 Unlike freeobject(), object_free() checkes to make sure the pointer is 00151 not NULL before trying to free it. 00152 00153 @see newobject() 00154 @see object_free() 00155 */ 00156 void freeobject(t_object *op); 00157 00158 00159 /** Make a new instance of an existing Max class. 00160 @ingroup class_old 00161 00162 @param s className Symbol specifying the name of the class of the instance to be created. 00163 @param argc Count of arguments in argv. 00164 @param argv Array of t_atoms; arguments to the class’s instance creation function. 00165 00166 @return A pointer to the created object, or 0 if the class 00167 didn’t exist or there was another type of error in creating the instance. 00168 00169 @remark This function creates a new instance of the specified class. Using 00170 newinstance is equivalent to typing something in a New Object box 00171 when using Max. The difference is that no object box is created in any 00172 Patcher window, and you can send messages to the object directly 00173 without connecting any patch cords. The messages can either be type- 00174 checked (using typedmess) or non-type-checked (using the members 00175 of the getfn family). 00176 00177 This function is useful for taking advantage of other already-defined 00178 objects that you would like to use “privately” in your object, such as 00179 tables. See the source code for the coll object for an example of using a 00180 privately defined class. 00181 */ 00182 void *newinstance(t_symbol *s, short argc, t_atom *argv); 00183 00184 00185 /** 00186 @ingroup class_old 00187 */ 00188 void finder_addclass(char *category, char *classString); 00189 00190 00191 /** 00192 Use the alias function to allow users to refer to your object by a 00193 name other than that of your shared library. 00194 00195 @ingroup class_old 00196 @param name An alternative name for the user to use to make an object of your class. 00197 */ 00198 void alias(char *name); 00199 00200 00201 /** 00202 @ingroup class_old 00203 */ 00204 void class_noinlet(t_messlist *m); 00205 00206 00207 /** 00208 Use class_setname() to associate you object’s name with it’s filename 00209 on disk. 00210 00211 @ingroup class_old 00212 @param obname A character string with the name of your object class as it appears in Max. 00213 @param filename A character string with the name of your external’s file as it appears on disk. 00214 */ 00215 void class_setname(char *obname, char *filename); 00216 00217 00218 short force_install(char *classname); 00219 void loader_setpath(long type, short path); 00220 00221 00222 00223 // memory functions 00224 00225 /** 00226 Allocate small amounts of non-relocatable memory. 00227 As of Max 5 it is unified with sysmem_newptr(), which is the preferred method for allocating memory. 00228 @ingroup memory 00229 @param size The size to allocate in bytes (up to 32767 bytes). 00230 @return A pointer to the allocated memory. 00231 */ 00232 char *getbytes(short size); 00233 00234 00235 /** 00236 Free memory allocated with getbytes(). 00237 As of Max 5 it is unified with sysmem_newptr(), which is the preferred method for allocating memory. 00238 @ingroup memory 00239 @param b A pointer to the block of memory previously allocated that you want to free. 00240 @param size The size the block specified (as parameter b) in bytes. 00241 */ 00242 void freebytes(void *b, short size); 00243 00244 00245 /** 00246 Use getbytes16() to allocate small amounts of non-relocatable 00247 memory that is aligned on a 16-byte boundary for use with vector optimization. 00248 @ingroup memory 00249 @param size The size to allocate in bytes (up to 32767 bytes). 00250 @return A pointer to the allocated memory. 00251 00252 @remark getbytes16() is identical to getbytes except that it returns memory 00253 that is aligned to a 16-byte boundary. This allows you to allocate 00254 storage for vector-optimized memory at interrupt level. Note that any 00255 memory allocated with getbytes16() must be freed with 00256 freebytes16(), not freebytes(). 00257 */ 00258 char *getbytes16(short size); 00259 00260 00261 /** 00262 Free memory allocated with getbytes16(). 00263 As of Max 5 it is unified with sysmem_newptr(), which is the preferred method for allocating memory. 00264 @ingroup memory 00265 @param mem A pointer to the block of memory previously allocated that you want to free. 00266 @param size The size the block specified (as parameter b) in bytes. 00267 00268 @remark Note that freebytes16() will cause memory corruption if you pass it 00269 memory that was allocated with getbytes(). Use it only with memory 00270 allocated with getbytes16(). 00271 */ 00272 void freebytes16(char *mem, short size); 00273 00274 00275 /** 00276 Allocate relocatable memory. 00277 00278 @ingroup memory 00279 @param size The size to allocate in bytes. 00280 @return The allocated handle. 00281 @see sysmem_newhandle() 00282 */ 00283 char **newhandle(long size); 00284 00285 00286 /** 00287 Change the size of a handle. 00288 00289 @ingroup memory 00290 @param h The handle to resize. 00291 @param size The new size to allocate in bytes. 00292 @return Ignored. 00293 @see sysmem_resizehandle() 00294 */ 00295 short growhandle(void *h, long size); 00296 00297 00298 /** 00299 Free the memory used by a handle you no longer need. 00300 00301 @ingroup memory 00302 @param h The handle to dispose. 00303 @see sysmem_freehandle() 00304 */ 00305 void disposhandle(char **h); 00306 00307 00308 00309 #ifdef MM_UNIFIED // sysmem and getbytes are unified 00310 #define getbytes(size) ((char *)sysmem_newptr((long)(size))) 00311 #define freebytes(p,size) sysmem_freeptr((char *)(p)) 00312 #endif 00313 00314 // symbol/string/text/error functions 00315 00316 /** 00317 Given a C-string, fetch the matching #t_symbol pointer from the symbol table, 00318 generating the symbol if neccessary. 00319 00320 @ingroup symbol 00321 @param s A C-string to be looked up in Max’s symbol table. 00322 @return A pointer to the #t_symbol in the symbol table. 00323 */ 00324 t_symbol *gensym(char *s); 00325 00326 00327 /** 00328 Print text to the Max window. 00329 Max 5 introduced object_post(), which provides several enhancements to post() 00330 where a valid #t_object pointer is available. 00331 00332 post() is a printf() for the Max window. It even works from non-main threads, 00333 queuing up multiple lines of text to be printed when the main thread processing resumes. 00334 post() can be quite useful in debugging your external object. 00335 00336 @ingroup console 00337 @param fmt A C-string containing text and printf-like codes 00338 specifying the sizes and formatting of the additional arguments. 00339 @param ... Arguments of any type that correspond to the format codes in fmtString. 00340 00341 @remark Note that post only passes 16 bytes of arguments to sprintf, so if 00342 you want additional formatted items on a single line, use postatom(). 00343 00344 Example: 00345 @code 00346 short whatIsIt; 00347 00348 whatIsIt = 999; 00349 post ("the variable is %ld",(long)whatIsIt); 00350 @endcode 00351 00352 @remark The Max Window output when this code is executed. 00353 @code 00354 the variable is 999 00355 @endcode 00356 00357 @see object_post() 00358 @see error() 00359 @see cpost() 00360 */ 00361 void post(char *fmt, ...); 00362 00363 00364 /** 00365 Print text to the system console. 00366 On the Mac this post will be visible by launching Console.app in the /Applications/Utilities folder. 00367 On Windows this post will be visible by launching the dbgView.exe program, which is a free download 00368 as a part of Microsoft's SysInternals. 00369 00370 @ingroup console 00371 @param fmt A C-string containing text and printf-like codes 00372 specifying the sizes and formatting of the additional arguments. 00373 @param ... Arguments of any type that correspond to the format codes in fmtString. 00374 00375 @remark Particularly on MacOS 10.5, posting to Console.app can be a computationally expensive operation. 00376 Use with care. 00377 00378 @see post() 00379 @see object_post() 00380 */ 00381 void cpost(char *fmt, ...); 00382 00383 00384 /** 00385 Print an error to the Max window. 00386 Max 5 introduced object_error(), which provides several enhancements to error() 00387 where a valid #t_object pointer is available. 00388 00389 error() is very similar to post(), thought it offers two additional features: 00390 - the post to the Max window is highlighted (with a red background). 00391 - the post can be trapped with the error object in a patcher. 00392 00393 @ingroup console 00394 @param fmt A C-string containing text and printf-like codes 00395 specifying the sizes and formatting of the additional arguments. 00396 @param ... Arguments of any type that correspond to the format codes in fmtString. 00397 00398 @see object_post() 00399 @see post() 00400 @see cpost() 00401 */ 00402 void error(char *fmt, ...); 00403 00404 /** 00405 Put up an error or advisory alert box on the screen. 00406 00407 Don't use this function. Instead use error(), object_error(), or object_error_obtrusive(). 00408 00409 This function performs an sprintf() on fmtstring and items, then 00410 puts up an alert box. ouchstring() will queue the message to a lower 00411 priority level if it’s called in an interrupt and there is no alert box 00412 request already pending. 00413 00414 @ingroup console 00415 @param s A C-string containing text and printf-like codes 00416 specifying the sizes and formatting of the additional arguments. 00417 @param ... Arguments of any type that correspond to the format codes in fmtString. 00418 00419 @see error() 00420 @see object_error() 00421 @see object_error_obtrusive() 00422 */ 00423 void ouchstring(char *s, ...); 00424 short advise(char *s, ...); 00425 void t_cpytext(void); 00426 void drawstr(char *s); 00427 00428 /** 00429 Print multiple items in the same line of text in the Max window. 00430 This function prints a single #t_atom on a line in the Max window 00431 without a carriage return afterwards, as post() does. Each #t_atom printed 00432 is followed by a space character. 00433 00434 @ingroup console 00435 @param ap The address of a #t_atom to print. 00436 00437 @see object_post() 00438 @see post() 00439 @see cpost() 00440 00441 */ 00442 void postatom(t_atom *ap); 00443 00444 // tap -- this one doesn't do anything any more, right? at least on windows it doesn't.... 00445 //void assist_string(short id,long msg,long arg, short firstin, short firstout,char *dst,...); 00446 00447 void stdinletinfo(t_object *s, void *b, long a, char *t); 00448 00449 void debug_printf(char *,...); 00450 00451 00452 /** Receive messages from the error handler. 00453 @ingroup misc 00454 @param x The object to be subscribed to the error handler. 00455 00456 @remark error_subscribe() enables your object to receive a message (error), 00457 followed by the list of atoms in the error message posted to the Max 00458 window. 00459 00460 Prior to calling error_subscribe(), you should bind the error 00461 message to an internal error handling routine: 00462 @code 00463 addmess((method)myobject_error, "error", A_GIMME, 0); 00464 @endcode 00465 Your error handling routine should be declared as follows: 00466 @code 00467 void myobject_error(t_myobject *x, t_symbol *s, short argc, t_atom *argv); 00468 @endcode 00469 */ 00470 void error_subscribe(t_object *x); 00471 00472 00473 /** Remove an object as an error message recipient. 00474 @ingroup misc 00475 @param x The object to unsubscribe. 00476 */ 00477 void error_unsubscribe(t_object *x); 00478 00479 00480 void xsetpost(); 00481 void post_getpos(short *row, short *col); 00482 void poststring(char *s); 00483 // not sure where to put these... 00484 00485 enum { 00486 POSTROW_POST = 0, 00487 POSTROW_ERROR = 1, 00488 POSTROW_WARNING = 2, 00489 POSTROW_BUG = 3 00490 }; 00491 00492 enum { 00493 JMAXWINDOW_ADVANCE = 1, 00494 JMAXWINDOW_APPEND = 2, 00495 JMAXWINDOW_WRITE = 4, 00496 JMAXWINDOW_UNIQUE = 8 00497 }; 00498 00499 00500 /** 00501 Print text to the Max window, linked to an instance of your object. 00502 00503 Max window rows which are generated using object_post() or object_error() can be 00504 double-clicked by the user to have Max assist with locating the object in a patcher. 00505 Rows created with object_post() and object_error() will also automatically provide 00506 the name of the object's class in the correct column in the Max window. 00507 00508 @ingroup console 00509 @param x A pointer to your object. 00510 @param s A C-string containing text and printf-like codes 00511 specifying the sizes and formatting of the additional arguments. 00512 @param ... Arguments of any type that correspond to the format codes in fmtString. 00513 00514 @remark Example: 00515 @code 00516 void myMethod(myObject *x, long someArgument) 00517 { 00518 object_post((t_object*)x, "This is my argument: %ld", someArgument); 00519 } 00520 @endcode 00521 00522 @see object_error() 00523 */ 00524 void object_post(t_object *x, char *s, ...); 00525 00526 00527 /** 00528 Print text to the Max window, linked to an instance of your object, 00529 and flagged as an error (highlighted with a red background). 00530 00531 Max window rows which are generated using object_post() or object_error() can be 00532 double-clicked by the user to have Max assist with locating the object in a patcher. 00533 Rows created with object_post() and object_error() will also automatically provide 00534 the name of the object's class in the correct column in the Max window. 00535 00536 @ingroup console 00537 @param x A pointer to your object. 00538 @param s A C-string containing text and printf-like codes 00539 specifying the sizes and formatting of the additional arguments. 00540 @param ... Arguments of any type that correspond to the format codes in fmtString. 00541 00542 @see object_post() 00543 @see object_warn() 00544 */ 00545 void object_error(t_object *x, char *s, ...); 00546 00547 00548 /** 00549 Print text to the Max window, linked to an instance of your object, 00550 and flagged as a warning (highlighted with a yellow background). 00551 00552 Max window rows which are generated using object_post(), object_error(), or object_warn can be 00553 double-clicked by the user to have Max assist with locating the object in a patcher. 00554 Rows created with object_post(), object_error(), or object_warn() will also automatically provide 00555 the name of the object's class in the correct column in the Max window. 00556 00557 @ingroup console 00558 @param x A pointer to your object. 00559 @param s A C-string containing text and printf-like codes 00560 specifying the sizes and formatting of the additional arguments. 00561 @param ... Arguments of any type that correspond to the format codes in fmtString. 00562 00563 @see object_post() 00564 @see object_error() 00565 */ 00566 void object_warn(t_object *x, char *s, ...); 00567 00568 // ? 00569 void object_bug(t_object *x, char *s, ...); 00570 00571 // private? 00572 void object_poststring(t_object *ob, long kind, long flags, char *text); 00573 00574 00575 /** 00576 Print text to the Max window, linked to an instance of your object, 00577 and flagged as an error (highlighted with a red background), 00578 and grab the user's attention by displaying a banner in the patcher window. 00579 00580 This function should be used exceedingly sparingly, with preference given to 00581 object_error() when a problem occurs. 00582 00583 @ingroup console 00584 @param x A pointer to your object. 00585 @param s A C-string containing text and printf-like codes 00586 specifying the sizes and formatting of the additional arguments. 00587 @param ... Arguments of any type that correspond to the format codes in fmtString. 00588 00589 @see object_post() 00590 @see object_error() 00591 */ 00592 void object_error_obtrusive(t_object *x, char *s, ...); 00593 00594 00595 long jdialog_showtext(char *prompt, char *deftext, long flags, char **text); 00596 00597 00598 #ifndef WIN_VERSION 00599 int sprintf(char *, const char *, ...); 00600 int sscanf(const char *, const char *, ...); 00601 #endif //WIN_VERSION 00602 00603 00604 // inlet/outlet functions 00605 00606 /** 00607 Use inlet_new() to create an inlet that can receive a specific message or any message. 00608 00609 @ingroup inout 00610 @param x Your object. 00611 @param s Character string of the message, or NULL to receive any message. 00612 @return A pointer to the new inlet. 00613 00614 @remark inlet_new() ceates a general purpose inlet. 00615 You can use it in circumstances where you would like special messages to be received in 00616 inlets other than the leftmost one. 00617 To create an inlet that receives a particular message, pass the message’s 00618 character string. For example, to create an inlet that receives only bang 00619 messages, do the following 00620 @code 00621 inlet_new (myObject,"bang"); 00622 @endcode 00623 00624 @remark To create an inlet that can receive any message, pass NULL for msg 00625 @code 00626 inlet_new (myObject, NULL); 00627 @endcode 00628 00629 @remark Proxies are an alternative method for general-purpose inlets that have 00630 a number of advantages. If you create multiple inlets as shown above, 00631 there would be no way to figure out which inlet received a message. See 00632 the discussion in @ref chapter_inout_proxies. 00633 */ 00634 void *inlet_new(void *x, char *s); 00635 00636 /** 00637 Use intin() to create an inlet typed to receive only integers. 00638 00639 @ingroup inout 00640 @param x Your object. 00641 @param n Location of the inlet from 1 to 9. 1 is immediately to the right of the leftmost inlet. 00642 @return A pointer to the new inlet. 00643 00644 @remark intin creates integer inlets. 00645 It takes a pointer to your newly created object and an integer n, from 1 to 9. 00646 The number specifies the message 00647 type you’ll get, so you can distinguish one inlet from another. For 00648 example, an integer sent in inlet 1 will be of message type in1 and a 00649 floating point number sent in inlet 4 will be of type ft4. You use 00650 addinx() and addftx() to add methods to respond to these messages. 00651 00652 The order you create additional inlets is important. If you want the 00653 rightmost inlet to be the have the highest number in- or ft- message 00654 (which is usually the case), you should create the highest number 00655 message inlet first. 00656 */ 00657 void *intin(void *x, short n); 00658 00659 00660 /** 00661 Use floatin() to create an inlet typed to receive only floats. 00662 00663 @ingroup inout 00664 @param x Your object. 00665 @param n Location of the inlet from 1 to 9. 1 is immediately to the right of the leftmost inlet. 00666 @return A pointer to the new inlet. 00667 */ 00668 void *floatin(void *x, short n); 00669 00670 00671 /** 00672 Use outlet_new() to create an outlet that can send a specific non-standard message, or any message. 00673 00674 @ingroup inout 00675 @param x Your object. 00676 @param s A C-string specifying the message that will be sent out this outlet, 00677 or NULL to indicate the outlet will be used to send various messages. 00678 The advantage of this kind of outlet’s flexibility is balanced by the fact that 00679 Max must perform a message-lookup in real-time for every message sent through it, 00680 rather than when a patch is being constructed, as is true for other types of outlets. 00681 Patchers execute faster when outlets are typed, since the message 00682 lookup can be done before the program executes. 00683 @return A pointer to the new outlet. 00684 */ 00685 void *outlet_new(void *x, char *s); 00686 00687 00688 /** 00689 Use bangout() to create an outlet that will always send the bang message. 00690 00691 @ingroup inout 00692 @param x Your object. 00693 @return A pointer to the new outlet. 00694 00695 @remark You can send a bang message out a general purpose outlet, but creating 00696 an outlet using bangout() allows Max to type-check the connection a 00697 user might make and refuse to connect the outlet to any object that 00698 cannot receive a bang message. bangout() returns the created outlet. 00699 */ 00700 void *bangout(void *x); 00701 00702 00703 /** 00704 Use intout() to create an outlet that will always send the int message. 00705 00706 @ingroup inout 00707 @param x Your object. 00708 @return A pointer to the new outlet. 00709 00710 @remark You can send a bang message out a general purpose outlet, but creating 00711 an outlet using bangout() allows Max to type-check the connection a 00712 user might make and refuse to connect the outlet to any object that 00713 cannot receive a bang message. bangout() returns the created outlet. 00714 */ 00715 void *intout(void *x); 00716 00717 00718 /** 00719 Use floatout() to create an outlet that will always send the float message. 00720 00721 @ingroup inout 00722 @param x Your object. 00723 @return A pointer to the new outlet. 00724 */ 00725 void *floatout(void *x); 00726 00727 00728 /** 00729 Use listout() to create an outlet that will always send the list message. 00730 @ingroup inout 00731 @param x Your object. 00732 @return A pointer to the new outlet. 00733 */ 00734 void *listout(void *x); 00735 00736 00737 /** 00738 Use outlet_bang() to send a bang message out an outlet. 00739 00740 @ingroup inout 00741 @param o Outlet that will send the message. 00742 @return Returns 0 if a stack overflow occurred, otherwise returns 1. 00743 */ 00744 void *outlet_bang(void *o); 00745 00746 00747 /** 00748 Use outlet_int() to send a float message out an outlet. 00749 00750 @ingroup inout 00751 @param o Outlet that will send the message. 00752 @param n Integer value to send. 00753 @return Returns 0 if a stack overflow occurred, otherwise returns 1. 00754 */ 00755 void *outlet_int(void *o, long n); 00756 00757 00758 /** 00759 Use outlet_float() to send an int message out an outlet. 00760 00761 @ingroup inout 00762 @param o Outlet that will send the message. 00763 @param f Float value to send. 00764 @return Returns 0 if a stack overflow occurred, otherwise returns 1. 00765 */ 00766 void *outlet_float(void *o, double f); 00767 00768 00769 /** 00770 Use outlet_list() to send a list message out an outlet. 00771 00772 @ingroup inout 00773 @param o Outlet that will send the message. 00774 @param s Should be NULL, but can be the _sym_list. 00775 @param ac Number of elements in the list in argv. 00776 @param av Atoms constituting the list. 00777 @return Returns 0 if a stack overflow occurred, otherwise returns 1. 00778 00779 @remark outlet_list() sends the list specified by argv and argc out the 00780 specified outlet. The outlet must have been created with listout or 00781 outlet_new in your object creation function (see above). You create 00782 the list as an array of Atoms, but the first item in the list must be an 00783 integer or float. 00784 00785 Here’s an example of sending a list of three numbers. 00786 @code 00787 t_atom myList[3]; 00788 long theNumbers[3]; 00789 short i; 00790 00791 theNumbers[0] = 23; 00792 theNumbers[1] = 12; 00793 theNumbers[2] = 5; 00794 for (i=0; i < 3; i++) { 00795 atom_setlong(myList+i,theNumbers[i]); 00796 } 00797 outlet_list(myOutlet,0L,3,&myList); 00798 @endcode 00799 00800 @remark It’s not a good idea to pass large lists to outlet_list that are 00801 comprised of local (automatic) variables. If the list is small, as in the 00802 above example, there’s no problem. If your object will regularly send 00803 lists, it might make sense to keep an array of t_atoms inside your 00804 object’s data structure. 00805 */ 00806 void *outlet_list(void *o, t_symbol *s, short ac, t_atom *av); 00807 00808 00809 /** 00810 Use outlet_anything() to send any message out an outlet. 00811 00812 @ingroup inout 00813 @param o Outlet that will send the message. 00814 @param s The message selector #t_symbol*. 00815 @param ac Number of elements in the list in argv. 00816 @param av Atoms constituting the list. 00817 @return Returns 0 if a stack overflow occurred, otherwise returns 1. 00818 00819 @remark This function lets you send an arbitrary message out an outlet. 00820 Here are a couple of examples of its use. 00821 00822 First, here’s a hard way to send the bang message (see outlet_bang() for an easier way): 00823 @code 00824 outlet_anything(myOutlet, gensym("bang"), 0, NIL); 00825 @endcode 00826 00827 @remark And here’s an even harder way to send a single integer (instead of using outlet_int()). 00828 @code 00829 t_atom myNumber; 00830 00831 atom_setlong(&myNumber, 432); 00832 outlet_anything(myOutlet, gensym("int"), 1, &myNumber); 00833 @endcode 00834 00835 @remark Notice that outlet_anything() expects the message argument as a 00836 #t_symbol*, so you must use gensym() on a character string. 00837 00838 If you’ll be sending the same message a lot, you might call gensym() on the message string at 00839 initialization time and store the result in a global variable to save the 00840 (significant) overhead of calling gensym() every time you want to send a 00841 message. 00842 00843 Also, do not send lists using outlet_anything() with list as 00844 the selector argument. Use the outlet_list() function instead. 00845 */ 00846 void *outlet_anything(void *o, t_symbol *s, short ac, t_atom *av); 00847 00848 00849 void *inlet4(void *x, void *w, char *s, char *s1); 00850 00851 00852 void inlet_to(void *x, void *w); 00853 00854 00855 short outlet_add(void *x, void *ip); 00856 00857 00858 void outlet_rm(void *x, void *ip); 00859 00860 00861 void outlet_atoms(void *out, short argc, t_atom *argv); 00862 00863 00864 00865 00866 // clock functions 00867 00868 /** 00869 Create a new Clock object. 00870 Normally, clock_new() is called in your instance creation 00871 function—and it cannot be called from a thread other than the main thread. 00872 To get rid of a clock object you created, use freeobject(). 00873 00874 @ingroup clocks 00875 @param obj Argument that will be passed to clock function fn when it is called. 00876 This will almost always be a pointer to your object. 00877 @param fn Function to be called when the clock goes off, 00878 declared to take a single argument as shown in @ref clocks_using_clocks. 00879 @return A pointer to a newly created Clock object. 00880 */ 00881 void *clock_new(void *obj, method fn); 00882 00883 00884 void clock_set(void *obj,long when); 00885 00886 00887 /** 00888 Schedule the execution of a Clock. 00889 clock_delay() sets a clock to go off at a certain number of 00890 milliseconds from the current logical time. 00891 00892 @ingroup clocks 00893 @param x Clock to schedule. 00894 @param n Delay, in milliseconds, before the Clock will execute. 00895 @see clock_fdelay() 00896 */ 00897 void clock_delay(void *x, long n); 00898 00899 00900 /** 00901 Cancel the scheduled execution of a Clock. 00902 clock_unset() will do nothing (and not complain) if the Clock passed 00903 to it has not been set. 00904 00905 @ingroup clocks 00906 @param x Clock to cancel. 00907 */ 00908 void clock_unset(void *x); 00909 void clock_xdelay(void *x, long n); 00910 void clock_xset(void *x, long n); 00911 void clock_xunset(void *x); 00912 short clock_getextfmt(void); 00913 00914 00915 /** 00916 Schedule the execution of a Clock using a floating-point argument. 00917 clock_delay() sets a clock to go off at a certain number of 00918 milliseconds from the current logical time. 00919 00920 @ingroup clocks 00921 @param c Clock to schedule. 00922 @param time Delay, in milliseconds, before the Clock will execute. 00923 @see clock_delay() 00924 */ 00925 void clock_fdelay(void *c, double time); 00926 void clock_fset(void *x, double when); 00927 void clock_fset2(void *x, double when, double offset); 00928 void clock_fdelay(void *x, double f); 00929 void clock_fdelay2(void *x, double delay, double offset); 00930 00931 00932 /** 00933 Find out the current logical time of the scheduler in milliseconds 00934 as a floating-point number. 00935 00936 @ingroup clocks 00937 @param time Returns the current time. 00938 @see gettime() 00939 @see setclock_getftime() 00940 @see setclock_gettime() 00941 */ 00942 void clock_getftime(double *time); 00943 00944 00945 /** Schedule a Clock on a scheduler. 00946 Schedules the Clock c to execute at time units after the current 00947 time. If scheduler x is 0 or does not point to a setclock object, the 00948 internal millisecond scheduler is used. Otherwise c is scheduled on 00949 the setclock object’s list of Clocks. The Clock should be created with 00950 clock_new(), the same as for a Clock passed to clock_delay(). 00951 00952 @ingroup clocks 00953 @param x A setclock object to be used for scheduling this clock. 00954 @param c Clock object containing the function to be executed. 00955 @param time Time delay (in the units of the Setclock) from the 00956 current time when the Clock will be executed. 00957 @see @ref setclock 00958 @see setclock_fdelay() 00959 */ 00960 void setclock_delay(t_object *x, void *c, long time); 00961 00962 00963 /** Remove a Clock from a scheduler. 00964 This function unschedules the Clock c in the list of Clocks in the 00965 setclock object x, or the internal millisecond scheduler if scheduler is 0. 00966 00967 @ingroup clocks 00968 @param x The setclock object that was used to schedule this clock. 00969 If 0, the clock is unscheduled from the internal millisecond scheduler. 00970 @param c Clock object to be removed from the scheduler. 00971 @see @ref setclock 00972 */ 00973 void setclock_unset(t_object *x, void *c); 00974 00975 00976 /** Find out the current time value of a setclock object. 00977 @ingroup clocks 00978 @param x A setclock object. 00979 @return Returns the current time value of the setclock object scheduler. 00980 If scheduler is 0, setclock_gettime is equivalent to the function 00981 gettime that returns the current value of the internal millisecond clock. 00982 @see @ref setclock 00983 @see setclock_getftime() 00984 */ 00985 long setclock_gettime(t_object *x); 00986 00987 00988 /** Schedule a Clock on a scheduler, using a floating-point time argument. 00989 @ingroup clocks 00990 @param s A setclock object to be used for scheduling this clock. 00991 @param c Clock object containing the function to be executed. 00992 @param time Time delay (in the units of the Setclock) from the 00993 current time when the Clock will be executed. 00994 @see @ref setclock 00995 @see setclock_delay() 00996 */ 00997 void setclock_fdelay(t_object *s, void *c, double time); 00998 00999 01000 /** Find out the current time value of a setclock object in floating-point milliseconds. 01001 @ingroup clocks 01002 @param s A setclock object. 01003 @param time The current time in milliseconds. 01004 @see @ref setclock 01005 @see setclock_gettime() 01006 */ 01007 void setclock_getftime(t_object *s, double *time); 01008 01009 01010 01011 // real-time 01012 01013 /** 01014 While most Max/MSP timing references "logical" time derived from Max's millisecond scheduler, 01015 time values produced by the systimer_gettime() are referenced from the CPU clock and can be used 01016 to time real world events with microsecond precision. 01017 01018 The standard 'cpuclock' external in Max is a simple wrapper around this function. 01019 01020 @ingroup clocks 01021 @return Returns the current real-world time. 01022 */ 01023 double systimer_gettime(void); 01024 01025 01026 // scheduler functions 01027 01028 /** 01029 Find out the current logical time of the scheduler in milliseconds. 01030 01031 @ingroup clocks 01032 @return Returns the current time. 01033 @see clock_getftime() 01034 */ 01035 long gettime(void); 01036 long getschedtime(void); 01037 long getexttime(void); 01038 void sched_suspend(void); 01039 void sched_resume(void); 01040 01041 01042 /** 01043 Cause a function to be executed at the timer level at some time in the future. 01044 01045 @ingroup threading 01046 @param ob First argument passed to the function fun when it executes. 01047 @param fun Function to be called, see below for how it should be declared. 01048 @param when The logical time that the function fun will be executed. 01049 @param sym Second argument passed to the function fun when it executes. 01050 @param argc Count of arguments in argv. argc is also the third argument passed to the function fun when it executes. 01051 @param argv Array containing a variable number of #t_atom function arguments. 01052 If this argument is non-zero, defer allocates memory to make a copy of the arguments 01053 (according to the size passed in argc) 01054 and passes the copied array to the function fun when it executes as the fourth argument. 01055 01056 @remark schedule() calls a function at some time in the future. Unlike defer(), 01057 the function is called in the scheduling loop when logical time is equal 01058 to the specified value when. This means that the function could be 01059 called at interrupt level, so it should follow the usual restrictions on 01060 interrupt-level conduct. The function fun passed to schedule should 01061 be declared as follows: 01062 01063 @code 01064 void myobject_do (myObject *client, t_symbol *s, short argc, t_atom *argv); 01065 @endcode 01066 01067 @remark One use of schedule() is as an alternative to using the lockout flag. 01068 01069 @see defer() 01070 */ 01071 void schedule(void *ob, method fun, long when, t_symbol *sym, short argc, Atom *argv); 01072 void schedulef(void *ob, method fun, double when, t_symbol *sym, short argc, Atom *argv); 01073 01074 01075 01076 01077 /** Create a new local scheduler. 01078 @ingroup clocks 01079 @return A pointer to the newly created scheduler. 01080 @see @ref creating_schedulers 01081 */ 01082 void *scheduler_new(void); 01083 01084 01085 /** Make a scheduler current, so that future related calls (such as 01086 clock_delay()) will affect the appropriate scheduler. 01087 01088 @ingroup clocks 01089 @param x The scheduler to make current. 01090 @return This routine returns a pointer to the previously current scheduler, 01091 wsaved and restored when local scheduling is complete. 01092 @see @ref creating_schedulers 01093 */ 01094 void *scheduler_set(void *x); 01095 01096 01097 /** Run scheduler events to a selected time. 01098 @ingroup clocks 01099 @param x The scheduler to advance. 01100 @param until The ending time for this run (in milliseconds). 01101 @see @ref creating_schedulers 01102 */ 01103 void scheduler_run(void *x, double until); 01104 01105 01106 /** Set the current time of the scheduler. 01107 @ingroup clocks 01108 @param x The scheduler to set. 01109 @param time The new current time for the selected scheduler (in milliseconds). 01110 @see @ref creating_schedulers 01111 */ 01112 void scheduler_settime(void *x, double time); 01113 01114 01115 /** Retrieve the current time of the selected scheduler. 01116 @ingroup clocks 01117 @param x The scheduler to query. 01118 @param time The current time of the selected scheduler. 01119 @see @ref creating_schedulers 01120 */ 01121 void scheduler_gettime(void *x, double *time); 01122 01123 01124 01125 01126 /** 01127 Cause a function to be executed at the timer level at some time in the future specified by a delay offset. 01128 01129 @ingroup threading 01130 @param ob First argument passed to the function fun when it executes. 01131 @param fun Function to be called, see below for how it should be declared. 01132 @param delay The delay from the current time before the function will be executed. 01133 @param sym Second argument passed to the function fun when it executes. 01134 @param argc Count of arguments in argv. argc is also the third argument passed to the function fun when it executes. 01135 @param argv Array containing a variable number of #t_atom function arguments. 01136 If this argument is non-zero, defer allocates memory to make a copy of the arguments 01137 (according to the size passed in argc) 01138 and passes the copied array to the function fun when it executes as the fourth argument. 01139 01140 @remark schedule_delay() is similar to schedule but allows you to specify the 01141 time as a delay rather than a specific logical time. 01142 01143 One use of schedule() or schedule_delay() is as an alternative to 01144 using the lockout flag. Here is an example click method that calls 01145 schedule() instead of outlet_int() surrounded by lockout_set() calls. 01146 01147 @code 01148 void myobject_click (t_myobject *x, Point pt, short modifiers) 01149 { 01150 t_atom a[1]; 01151 a[0].a_type = A_LONG; 01152 a[0].a_w.w_long = Random(); 01153 schedule_delay(x, myobject_sched, 0 ,0, 1, a); 01154 } 01155 01156 void myobject_sched (t_myobject *x, t_symbol *s, short ac, t_atom *av) 01157 { 01158 outlet_int(x->m_out,av->a_w.w_long); 01159 } 01160 @endcode 01161 01162 @see schedule() 01163 */ 01164 void schedule_delay(void *ob, method fun, long delay, t_symbol *sym, short argc, t_atom *argv); 01165 void schedule_fdelay(void *ob, method fun, double delay, t_symbol *sym, short argc, t_atom *argv); 01166 void schedule_defer(void *ob, method fun, long delay, t_symbol *sym, short argc, t_atom *arv); 01167 void schedule_fdefer(void *ob, method fun, double delay, t_symbol *sym, short argc, t_atom *arv); 01168 short lockout_set(short); 01169 01170 /** 01171 Determine whether your code is executing in the Max scheduler thread. 01172 01173 @ingroup threading 01174 @return This function returns non-zero if you are within Max's scheduler thread, zero otherwise. 01175 Note that if your code sets up other types of interrupt-level callbacks, 01176 such as for other types of device drivers used in asynchronous mode, isr will return false. 01177 */ 01178 long isr(void); 01179 short isr_set(short way); 01180 01181 01182 01183 // queue functions 01184 01185 /** 01186 Create a new Qelem. 01187 The created Qelem will need to be freed using qelem_free(), do not use freeobject(). 01188 01189 @ingroup qelems 01190 @param obj Argument to be passed to function fun when the Qelem executes. 01191 Normally a pointer to your object. 01192 @param fn Function to execute. 01193 @return A pointer to a Qelem instance. 01194 You need to store this value to pass to qelem_set(). 01195 01196 @remark Any kind of drawing or calling of Macintosh Toolbox routines that 01197 allocate or purge memory should be done in a Qelem function. 01198 */ 01199 void *qelem_new(void *obj, method fn); 01200 01201 01202 /** 01203 Cause a Qelem to execute. 01204 01205 @ingroup qelems 01206 @param q The Qelem whose function will be executed in the main thread. 01207 01208 @remark The key behavior of qelem_set() is this: if the Qelem object has already 01209 been set, it will not be set again. (If this is not what you want, see 01210 defer().) This is useful if you want to redraw the state of some 01211 data when it changes, but not in response to changes that occur faster 01212 than can be drawn. A Qelem object is unset after its queue function has 01213 been called. 01214 */ 01215 void qelem_set(void *q); 01216 01217 01218 /** 01219 Cancel a Qelem’s execution. 01220 If the Qelem’s function is set to be called, qelem_unset() will stop it 01221 from being called. Otherwise, qelem_unset() does nothing. 01222 01223 @ingroup qelems 01224 @param q The Qelem whose execution you wish to cancel. 01225 */ 01226 void qelem_unset(void *q); 01227 01228 01229 /** 01230 Free a Qelem object created with qelem_new(). 01231 Typically this will be in your object’s free funtion. 01232 01233 @ingroup qelems 01234 @param x The Qelem to destroy. 01235 */ 01236 void qelem_free(void *x); 01237 01238 01239 /** 01240 Cause a Qelem to execute with a higher priority. 01241 This function is identical to qelem_set(), except that the Qelem’s 01242 function is placed at the front of the list of routines to execute in the 01243 main thread instead of the back. Be polite and only use 01244 qelem_front() only for special time-critical applications. 01245 01246 @ingroup qelems 01247 @param x The Qelem whose function will be executed in the main thread. 01248 */ 01249 void qelem_front(void *x); 01250 01251 01252 /** 01253 Defer execution of a function to the main thread if (and only if) 01254 your function is executing in the scheduler thread. 01255 01256 @ingroup threading 01257 @param ob First argument passed to the function fun when it executes. 01258 @param fn Function to be called, see below for how it should be declared. 01259 @param sym Second argument passed to the function fun when it executes. 01260 @param argc Count of arguments in argv. argc is also the third argument passed to the function fun when it executes. 01261 @param argv Array containing a variable number of #t_atom function arguments. 01262 If this argument is non-zero, defer allocates memory to make a copy of the arguments 01263 (according to the size passed in argc) 01264 and passes the copied array to the function fun when it executes as the fourth argument. 01265 @return Return values is for internal Cycling '74 use only. 01266 01267 @remark This function uses the isr() routine to determine whether you’re at the 01268 Max timer interrupt level (in the scheduler thread). 01269 If so, defer() creates a Qelem (see @ref qelems), calls 01270 qelem_front(), and its queue function calls the function fn you 01271 passed with the specified arguments. 01272 If you’re not in the scheduler thread, the function is executed immediately with the 01273 arguments. Note that this implies that defer() is not appropriate for 01274 using in situations such as Device or File manager I/0 completion routines. 01275 The defer_low() function is appropriate however, because it always defers. 01276 01277 The deferred function should be declared as follows: 01278 @code 01279 void myobject_do (myObject *client, t_symbol *s, short argc, t_atom *argv); 01280 @endcode 01281 01282 @see defer_low() 01283 */ 01284 void *defer(void *ob,method fn,t_symbol *sym,short argc,t_atom *argv); 01285 01286 01287 /** 01288 Defer execution of a function to the back of the queue on the main thread. 01289 01290 @ingroup threading 01291 @param ob First argument passed to the function fun when it executes. 01292 @param fn Function to be called, see below for how it should be declared. 01293 @param sym Second argument passed to the function fun when it executes. 01294 @param argc Count of arguments in argv. argc is also the third argument passed to the function fun when it executes. 01295 @param argv Array containing a variable number of #t_atom function arguments. 01296 If this argument is non-zero, defer allocates memory to make a copy of the arguments 01297 (according to the size passed in argc) 01298 and passes the copied array to the function fun when it executes as the fourth argument. 01299 @return Return values is for internal Cycling '74 use only. 01300 01301 @remark defer_low() always defers a call to the function fun whether you are already 01302 in the main thread or not, and uses qelem_set(), not qelem_front(). This 01303 function is recommended for responding to messages that will cause 01304 your object to open a dialog box, such as read and write. 01305 01306 The deferred function should be declared as follows: 01307 @code 01308 void myobject_do (myObject *client, t_symbol *s, short argc, t_atom *argv); 01309 @endcode 01310 01311 @see defer() 01312 */ 01313 void *defer_low(void *ob,method fn,t_symbol *sym,short argc,t_atom *argv); 01314 01315 void *defer_medium(void *ob, method fn, t_symbol *sym, short argc, t_atom *argv); 01316 01317 void *defer_front(void *ob, method fn, t_symbol *sym, short argc, t_atom *argv); 01318 01319 // private 01320 void *defer_sys_low(void *ob,method fn,t_symbol *sym,short argc,t_atom *argv); 01321 01322 01323 01324 // binbuf functions 01325 01326 /** 01327 Use binbuf_new() to create and initialize a Binbuf. 01328 @ingroup binbuf 01329 @return Returns a new binbuf if successful, otherwise NULL. 01330 */ 01331 void *binbuf_new(void); 01332 01333 01334 /** 01335 Use binbuf_vinsert() to append a Max message to a Binbuf adding a semicolon. 01336 @ingroup binbuf 01337 01338 @param x Binbuf containing the desired Atom. 01339 @param fmt A C-string containing one or more letters corresponding to the types of each element of the message. 01340 s for #t_symbol*, l for long, or f for float. 01341 @param ... Elements of the message, passed directly to the function as Symbols, longs, or floats. 01342 01343 @remark binbuf_vinsert() works somewhat like a printf() for Binbufs. It 01344 allows you to pass a number of arguments of different types and insert 01345 them into a Binbuf. The entire message will then be terminated with a 01346 semicolon. Only 16 items can be passed to binbuf_vinsert(). 01347 01348 The example below shows the implementation of a normal object’s 01349 save method. The save method requires that you build a message that 01350 begins with #N (the new object) , followed by the name of your object 01351 (in this case, represented by the #t_symbol myobject), followed by any 01352 arguments your instance creation function requires. In this example, 01353 we save the values of two fields m_val1 and m_val2 defined as longs. 01354 01355 @code 01356 void myobject_save (myObject *x, Binbuf *dstBuf) 01357 { 01358 binbuf_vinsert(dstBuf, "ssll", gensym("#N"), 01359 gensym("myobject"), 01360 x->m_val1, x->m_val2); 01361 } 01362 @endcode 01363 01364 Suppose that such an object had written this data into a file. If you 01365 opened the file as text, you would see the following: 01366 01367 @code 01368 #N myobject 10 20; 01369 #P newobj 218 82 30 myobject; 01370 @endcode 01371 01372 The first line will result in a new myobject object to be created; the 01373 creation function receives the arguments 10 and 20. The second line 01374 contains the text of the object box. The newobj message to a patcher 01375 creates the object box user interface object and attaches it to the 01376 previously created myobject object. Normally, the newex message is 01377 used. This causes the object to be created using the arguments that 01378 were typed into the object box. 01379 */ 01380 void binbuf_vinsert(void *x, char *fmt, ...); 01381 01382 01383 /** 01384 Use binbuf_insert() to append a Max message to a Binbuf adding a semicolon. 01385 @ingroup binbuf 01386 01387 @param x Binbuf to receive the items. 01388 @param s Ignored. Pass NULL. 01389 @param argc Count of items in the argv array. 01390 @param argv Array of t_atoms to add to the Binbuf. 01391 01392 @remark You’ll use binbuf_insert() instead of binbuf_append() if you were 01393 saving your object into a Binbuf and wanted a semicolon at the end. If 01394 the message is part of a file that will later be evaluated, such as a 01395 Patcher file, the first argument argv[0] will be the receiver of the 01396 message and must be a Symbol. binbuf_vinsert() is 01397 easier to use than binbuf_insert(), since you don’t have to format 01398 your data into an array of Atoms first. 01399 01400 binbuf_insert() will also convert the t_symbols #1 through #9 into 01401 $1 through $9. This is used for saving patcher files that take 01402 arguments; you will probably never save these symbols as part of 01403 anything you are doing. 01404 */ 01405 void binbuf_insert(void *x, t_symbol *s, short argc, t_atom *argv); 01406 01407 01408 /** 01409 Use binbuf_eval to evaluate a Max message in a Binbuf, passing it arguments. 01410 binbuf_eval() is an advanced function that evaluates the message in a 01411 Binbuf with arguments in argv, and sends it to receiver. 01412 01413 @ingroup binbuf 01414 @param x Binbuf containing the message. 01415 @param ac Count of items in the argv array. 01416 @param av Array of t_atoms as the arguments to the message. 01417 @param to Receiver of the message. 01418 01419 @return The result of sending the message. 01420 */ 01421 void *binbuf_eval(void *x, short ac, t_atom *av, void *to); 01422 01423 01424 /** 01425 Use binbuf_getatom to retrieve a single Atom from a Binbuf. 01426 01427 @ingroup binbuf 01428 @param x Binbuf containing the desired #t_atom. 01429 @param p1 Offset into the Binbuf’s array of types. Modified to point to the next #t_atom. 01430 @param p2 Offset into the Binbuf’s array of data. Modified to point to the next #t_atom. 01431 @param ap Location of a #t_atom where the retrieved data will be placed. 01432 01433 @return 1 if there were no t_atoms at the specified offsets, 01434 0 if there’s a legitimate t_atom returned in result. 01435 01436 @remark To get the first t_atom, set both typeOffset and stuffOffset to 0. 01437 Here’s an example of getting all the items in a Binbuf: 01438 @code 01439 t_atom holder; 01440 long to, so; 01441 01442 to = 0; 01443 so = 0; 01444 while (!binbuf_getatom(x, &to, &so, &holder)){ 01445 // do something with the t_atom 01446 } 01447 @endcode 01448 */ 01449 short binbuf_getatom(void *x, long *p1, long *p2, t_atom *ap); 01450 01451 01452 /** 01453 Use binbuf_text() to convert a text handle to a Binbuf. 01454 binbuf_text() parses the text in the handle srcText and converts it 01455 into binary format. Use it to evaluate a text file or text line entry into a 01456 Binbuf. 01457 01458 @ingroup binbuf 01459 @param x Binbuf to contain the converted text. 01460 It must have already been created with binbuf_new. 01461 Its previous contents are destroyed. 01462 @param srcText Handle to the text to be converted. It need not be terminated with a 0. 01463 @param n Number of characters in the text. 01464 @return If binbuf_text encounters an error during its operation, 01465 a non-zero result is returned, otherwise it returns 0. 01466 01467 @remark Note: Commas, symbols containing a dollar sign followed by a number 01468 1-9, and semicolons are identified by special pseudo-type constants for 01469 you when your text is binbuf-ized. 01470 01471 The following constants in the a_type field of Atoms returned by 01472 binbuf_getAtom identify the special symbols #A_SEMI, 01473 #A_COMMA, and #A_DOLLAR. 01474 01475 For a #t_atom of the pseudo-type #A_DOLLAR, the a_w.w_long field of 01476 the #t_atom contains the number after the dollar sign in the original 01477 text or symbol. 01478 01479 Using these pseudo-types may be helpful in separating “sentences” and 01480 “phrases” in the input language you design. For example, the old pop-up 01481 umenu object allowed users to have spaces in between words by requiring 01482 the menu items be separated by commas. It’s reasonably easy, using 01483 binbuf_getatom(), to find the commas in a Binbuf in order to 01484 determine the beginning of a new item when reading the atomized text 01485 to be displayed in the menu. 01486 01487 If you want to use a literal comma or semicolon in a symbol, precede it 01488 with a backslash (\\) character. The backslash character can be included 01489 by using two backslashes in a row. 01490 */ 01491 short binbuf_text(void *x, char **srcText, long n); 01492 01493 01494 /** 01495 Use binbuf_totext() to convert a Binbuf into a text handle. 01496 binbuf_totext() converts a Binbuf into text and places it in a handle. 01497 Backslashes are added to protect literal commas and semicolons 01498 contained in symbols. The pseudo-types are converted into commas, 01499 semicolons, or dollar-sign and number, without backslashes preceding 01500 them. binbuf_text can read the output of binbuf_totext and 01501 make the same Binbuf. 01502 01503 @ingroup binbuf 01504 @param x Binbuf with data to convert to text. 01505 @param dstText Pre-existing handle where the text will be placed. 01506 dstText will be resized to accomodate the text. 01507 @param sizep Where binbuf_totext() returns the number of characters in the converted text handle. 01508 @return If binbuf_totext runs out of memory during its operation, it returns a non-zero result, 01509 otherwise it returns 0. 01510 */ 01511 short binbuf_totext(void *x, char **dstText, long *sizep); 01512 01513 01514 /** 01515 Use binbuf_set() to change the entire contents of a Binbuf. 01516 The previous contents of the Binbuf are destroyed. 01517 01518 @ingroup binbuf 01519 @param x Binbuf to receive the items. 01520 @param s Ignored. Pass NULL. 01521 @param argc Count of items in the argv array. 01522 @param argv Array of t_atoms to put in the Binbuf. 01523 */ 01524 void binbuf_set(void *x, t_symbol *s, short argc, t_atom *argv); 01525 01526 01527 /** 01528 Use binbuf_append to append t_atoms to a Binbuf without modifying them. 01529 @ingroup binbuf 01530 @param x Binbuf to receive the items. 01531 @param s Ignored. Pass NULL. 01532 @param argc Count of items in the argv array. 01533 @param argv Array of atoms to add to the Binbuf. 01534 */ 01535 void binbuf_append(void *x, t_symbol *s, short argc, t_atom *argv); 01536 01537 // still supported? 01538 short binbuf_read(void *x, char *name, short volume, short binary); 01539 01540 // still supported? 01541 short binbuf_write(void *x, char *fn, short vol, short binary); 01542 01543 void binbuf_savebox(void *x, void *w, t_symbol *what, short d1, short d2, short d3, long d4, short hidden, short user); 01544 void binbuf_delete(void *x, long fromType, long toType, long fromData, long toData); 01545 void binbuf_addtext(void *x, char **text, long size); 01546 01547 01548 /** 01549 Use readatom() to read a single Atom from a text buffer. 01550 @ingroup binbuf 01551 @param outstr C-string of 256 characters that will receive the next text item read from the buffer. 01552 @param text Handle to the text buffer to be read. 01553 @param n Starts at 0, and is modified by readatom to point to the next item in the text buffer. 01554 @param e Number of characters in text. 01555 @param ap Where the resulting Atom read from the text buffer is placed. 01556 @return readatom() returns non-zero if there is more text to read, 01557 and zero if it has reached the end of the text. 01558 Note that this return value has the opposite logic from that of binbuf_getatom(). 01559 01560 @remark This function provides access to the low-level Max text evaluator used 01561 by binbuf_text(). It is designed to operate on a handle of characters 01562 (text) and called in a loop, as in the example shown below. 01563 @code 01564 long index = 0; 01565 t_atom dst; 01566 char outstr[256]; 01567 01568 while (readatom(outstr,textHandle,&index,textLength,&dst)) 01569 { 01570 // do something with the resulting Atom 01571 } 01572 @endcode 01573 01574 @remark An alternative to using readatom is to turn your text into a Binbuf 01575 using binbuf_text(), then call binbuf_getatom() in a loop. 01576 */ 01577 short readatom(char *outstr, char **text, long *n, long e, t_atom *ap); 01578 char *atom_string(t_atom *a); 01579 01580 01581 // atombuf functions 01582 01583 /** 01584 Use atombuf_new() to create a new Atombuf from an array of t_atoms. 01585 01586 @ingroup atombuf 01587 @param argc Number of t_atoms in the argv array. May be 0. 01588 @param argv Array of t_atoms. If creating an empty Atombuf, you may pass 0. 01589 @return atombuf_new() create a new #t_atombuf and returns a pointer to it. 01590 If 0 is returned, insufficient memory was available. 01591 */ 01592 void *atombuf_new(long argc, t_atom *argv); 01593 01594 01595 /** 01596 Use atombuf_free() to dispose of the memory used by a #t_atombuf. 01597 01598 @ingroup atombuf 01599 @param x The #t_atombuf to free. 01600 */ 01601 void atombuf_free(t_atombuf *x); 01602 01603 01604 /** 01605 Use atombuf_text() to convert text to a #t_atom array in a #t_atombuf. 01606 To use this routine to create a new Atombuf from the text buffer, first 01607 create a new empty t_atombuf with a call to atombuf_new(0,NULL). 01608 01609 @ingroup atombuf 01610 @param x Pointer to existing atombuf variable. 01611 The variable will be replaced by a new Atombuf containing the converted text. 01612 @param text Handle to the text to be converted. It need not be zero-terminated. 01613 @param size Number of characters in the text. 01614 */ 01615 void atombuf_text(t_atombuf **x, char **text, long size); 01616 01617 void atombuf_totext(t_atombuf *x, char **text, long *size); 01618 short atombuf_count(t_atombuf *x); 01619 void atombuf_set(t_atombuf *x, short start, short num); 01620 long atombuf_replacepoundargs(t_atombuf *x, long argc, t_atom *argv); 01621 01622 01623 // message functions 01624 01625 /** Send a typed message directly to a Max object. 01626 @ingroup class_old 01627 01628 @param op Max object that will receive the message. 01629 @param msg The message selector. 01630 @param argc Count of message arguments in argv. 01631 @param argp Array of t_atoms; the message arguments. 01632 @return If the receiver object can respond to the message, 01633 typedmess() returns the result. Otherwise, an error message will be 01634 seen in the Max window and 0 will be returned. 01635 01636 @remark typedmess sends a message to a Max object (receiver) a message 01637 with arguments. Note that the message 01638 must be a #t_symbol, not a character string, so you must call gensym 01639 on a string before passing it to typedmess. Also, note that untyped 01640 messages defined for classes with the argument list #A_CANT cannot be 01641 sent using typedmess. You must use getfn() etc. instead. 01642 01643 Example: 01644 @code 01645 //If you want to send a bang message to the object bang_me… 01646 void *bangResult; 01647 bangResult = typedmess(bang_me,gensym("bang"),0,0L); 01648 @endcode 01649 */ 01650 void *typedmess(t_object *op, t_symbol *msg, short argc, t_atom *argp); 01651 01652 01653 /** Use getfn() to send an untyped message to a Max object with error checking. 01654 @ingroup class_old 01655 01656 @param op Receiver of the message. 01657 @param msg Message selector. 01658 @return getfn returns a pointer to the method bound to the message selector 01659 msg in the receiver’s message list. It returns 0 and prints an error 01660 message in Max Window if the method can’t be found. 01661 */ 01662 method getfn(t_object *op, t_symbol *msg); 01663 01664 01665 /** Use egetfn() to send an untyped message to a Max object that always works. 01666 @ingroup class_old 01667 01668 @param op Receiver of the message. 01669 @param msg Message selector. 01670 @return egetfn returns a pointer to the method bound to the message selector 01671 msg in the receiver’s message list. If the method can’t be found, a 01672 pointer to a do-nothing function is returned. 01673 */ 01674 method egetfn(t_object *op, t_symbol *msg); 01675 01676 01677 /** Use zgetfn() to send an untyped message to a Max object without error checking. 01678 @ingroup class_old 01679 01680 @param op Receiver of the message. 01681 @param msg Message selector. 01682 @return zgetfn returns a pointer to the method bound to the message selector 01683 msg in the receiver’s message list. It returns 0 but doesn’t print an 01684 error message in Max Window if the method can’t be found. 01685 */ 01686 method zgetfn(t_object *op, t_symbol *msg); 01687 01688 01689 01690 // commenting out -- some of these are probably still good, we need to investigate -- TAP 01691 void patcher_eachdo(eachdomethod fun, void *arg); // this one is still legit 01692 void loadbang_suspend(void); // used by poly~ on windows 01693 void loadbang_resume(void); // used by poly~ on windows 01694 /* 01695 // patcher functions 01696 GrafPtr patcher_setport(t_patcher *p); 01697 #ifdef WIN_VERSION 01698 void patcher_restoreport(GrafPtr gp); 01699 #endif 01700 #ifdef MAC_VERSION 01701 #define patcher_restoreport SetPort 01702 #endif 01703 void *patchbox(void *p, method fn, short ac, t_atom *av, short defwidth); 01704 void patcher_dirty(t_patcher *p); 01705 void patcher_selectbox(t_patcher *p, t_box *b); 01706 void patcher_deselectbox(t_patcher *p, t_box *b); 01707 void patcher_okclose(t_patcher *p, void *x); 01708 void patcher_eachdo(eachdomethod fun, void *arg); 01709 void patcher_avoidrect(t_patcher *p, Rect *r2, short id); 01710 short patcher_boxname(t_patcher *p, t_box *b, t_symbol **s); 01711 void patcher_setboxname(t_patcher *p, t_box *b, t_symbol *s); 01712 void patcher_nohilite(t_patcher *p); 01713 void hilite_settarget(t_patcher *p, t_box *b); 01714 void *patcher_parentpatcher(t_patcher *p); 01715 01716 // box functions 01717 void box_new(t_box *b, t_patcher *patcher, short flags, short x1, short y1, short x2, short y2); 01718 void box_free(t_box *b); 01719 void box_ready(t_box *b); 01720 short box_ownerlocked(t_box *b); 01721 void box_size(void *b, short x, short y); 01722 void *textbox(void *p, method fn, short ac, t_atom *av); 01723 short box_nodraw(t_box *b); 01724 void box_erase(t_box *b); 01725 short box_invalnow(t_box *b); 01726 void *box_clip(t_box *b); 01727 void box_enddraw(t_box *b); 01728 short box_visible(t_box *b); 01729 void box_hilite(t_box *b, short way); 01730 void box_color(t_box *b); 01731 void box_getcolor(t_box *b,short index, RGBColor *rgb); 01732 long usecolor(t_box *b); 01733 void palette_getcolor(t_box *b, short index, RGBColor *rgb); 01734 long boxcolor_rgb2index(RGBColor *n); 01735 */ 01736 01737 01738 01739 // table functions 01740 01741 /** Get a handle to the data in a named table object. 01742 @ingroup tables 01743 01744 @param s Symbol containing the name of the table object to find. 01745 @param hp Address of a handle where the table’s data will be returned if the named table object is found. 01746 @param sp Number of elements in the table (its size in longs). 01747 @return If no table object is associated with the symbol tableName, table_get() returns a non-zero result. 01748 01749 @remark table_get searches for a table associated with the t_symbol 01750 tableName. If one is found, a Handle to its elements (stored as an 01751 array of long integers) is returned and the function returns 0. 01752 Never count on a table to exist across calls to 01753 one of your methods. Call table_get and check the result each time 01754 you wish to use a table. 01755 01756 Here is an example of retrieving the 40th element of a table: 01757 @code 01758 long **storage,size,value; 01759 if (!table_get(gensym("somename"),&storage,&size)) { 01760 if (size > 40) 01761 value = *((*storage)+40); 01762 } 01763 @endcode 01764 */ 01765 short table_get(t_symbol *s, long ***hp, long *sp); 01766 01767 01768 /** Mark a table object as having changed data. 01769 @ingroup tables 01770 @param s Symbol containing the name of a table object. 01771 @return If no table is associated with tableName, table_dirty returns a non-zero result. 01772 */ 01773 short table_dirty(t_symbol *s); 01774 01775 // commenting out, where are the replacements? -- tap 01776 /* 01777 // ed functions 01778 void *ed_new(t_object *assoc); 01779 void ed_vis(t_ed *x); 01780 void ed_settext(t_ed *x, t_handle text, long len); 01781 */ 01782 01783 01784 // file functions 01785 01786 /** Load a data file into a handle. 01787 This is a low-level routine used for reading text and data files. You 01788 specify the file’s name and Path ID, as well as a pointer to a Handle. 01789 01790 @ingroup loading_max_files 01791 @param name Name of the patcher file to load. 01792 @param volume Path ID specifying the location of the file. 01793 @param h Pointer to a handle variable that will receive the handle 01794 that contains the data in the file. 01795 @param sizep Size of the handle returned in h. 01796 @return If the file is found, readtohandle creates a Handle, reads all the data in 01797 the file into it, assigns the handle to the variable hp, and returns the 01798 size of the data in size. readtohandle returns 0 if the file was 01799 opened and read successfully, and non-zero if there was an error. 01800 */ 01801 short readtohandle(char *name, short volume, char ***h, long *sizep); 01802 01803 01804 /** Load a patcher file by name and volume reference number. 01805 @ingroup loading_max_files 01806 @param name Filename of the patcher file to load (C string). 01807 @param vol Path ID specifying the location of the file. 01808 @return If the file is found, fileload tries to open 01809 the file, evaluate it, open a window, and bring it to the front. A pointer 01810 to the newly created Patcher is returned if loading is successful, 01811 otherwise, if the file is not found or there is insufficient memory, zero 01812 is returned. 01813 */ 01814 void *fileload(char *name, short vol); 01815 01816 01817 /** Pass arguments to Max files when you open them. 01818 This function loads the specified file and returns a pointer to the 01819 created object. Historically, intload() is was used to open patcher files, 01820 whether they are in text or Max binary format. 01821 It could also open table files whose contents begin with the word “table.” 01822 01823 @ingroup loading_max_files 01824 @param name Name of the file to open. 01825 @param volume Path ID specifying the location of the file. 01826 @param s A symbol. 01827 @param ac Count of t_atoms in av. To properly open a patcher file, ac should be 9. 01828 @param av Array of t_atoms that will replace the changeable 01829 arguments 1-9. The default behavior could be to set 01830 all these to t_atoms of type #A_LONG with a value of 0. 01831 @param couldedit If non-zero and the file is not a patcher file, the file is opened as a text file. 01832 @return If couldedit is non-zero and the file is not a patcher file, it is made into 01833 a text editor, and lowload returns 0. If couldedit is non-zero, lowload 01834 will just alert the user to an error and return 0. If there is no error, the 01835 value returned will be a pointer to a patcher or table object. 01836 */ 01837 void *intload(char *name, short volume, t_symbol *s, short ac, t_atom *av, short couldedit); 01838 01839 01840 /** Load a patcher file located in the Max search path by name. 01841 This function searches for a patcher file, opens it, 01842 evaluates it as a patcher file, opens a window for the patcher and brings 01843 it to the front. You need only specify a filename and Max will look 01844 through its search path for the file. The search path begins with the 01845 current “default volume” that is often the volume of the last opened 01846 patcher file, then the folders specified in the File Preferences dialog, 01847 searched depth first, then finally the folder that contains the Max 01848 application. 01849 01850 @ingroup loading_max_files 01851 @param name Filename of the patcher file to load (C string). 01852 @return If stringload() returns a non-zero result, you can later 01853 use freeobject() to close the patcher, or just let users do it themselves. 01854 If stringload() returns zero, no file with the specified name was 01855 found or there was insufficient memory to open it. 01856 */ 01857 void *stringload(char *name); 01858 01859 void *resource_install(char *name, long rsrc); 01860 void *toolfile_new(char *name, short vol, long type); 01861 long toolfile_fread(void *t, char *buf, long n); 01862 long toolfile_fwrite(void *t, char *buf, long n); 01863 short toolfile_getc(void *t); 01864 short collective_load(char *name, short vol, short argc, t_atom *argv); 01865 void *onecopy_fileload(char *s, short path); 01866 01867 // resource functions 01868 short rescopy(long type,short id); 01869 short resnamecopy(long type, char *name); 01870 01871 01872 01873 // preset functions 01874 01875 /** Give the preset object a general message to restore the current state of your object. 01876 This is a general preset function for use when your object’s state 01877 cannot be restored with a simple int or set message. The example 01878 below shows the expected format for specifying what your current 01879 state is to a preset object. The first thing you supply is your object itself, 01880 followed by the symbol that is the name of your object’s class (which 01881 you can retrieve from your object using the macro ob_sym, declared in 01882 ext_mess.h). Next, supply the symbol that specifies the message you 01883 want receive (a method for which had better be defined in your class), 01884 followed by the arguments to this message—the current values of your 01885 object’s fields. 01886 01887 @ingroup presets 01888 @param fmt C string containing one or more letters corresponding 01889 to the types of each element of the message. s for 01890 Symbol, l for long, or f for float. 01891 @param ... Elements of the message used to restore the state of 01892 your object, passed directly to the function as Symbols, 01893 longs, or floats. See below for an example that 01894 conforms to what the preset object expects. 01895 */ 01896 void preset_store(char *fmt, ... /*struct b100 arg1 */); 01897 01898 01899 /** Restore the state of your object with a set message. 01900 This function causes a set message with the argument value to be sent 01901 to your object from the preset object when the user executes a preset. 01902 01903 @ingroup presets 01904 @param obj Your object. 01905 @param val Current value of your object. 01906 01907 */ 01908 void preset_set(t_object *obj, long val); 01909 01910 01911 /** Restore the state of your object with an int message. 01912 This function causes an int message with the argument value to be 01913 sent to your object from the preset object when the user executes a 01914 preset. All of the existing user interface objects use the int message for 01915 restoring their state when a preset is executed. 01916 01917 @ingroup presets 01918 @param x Your object. 01919 @param n Current value of your object. 01920 */ 01921 void preset_int(void *x,long n); 01922 01923 01924 01925 // num functions 01926 01927 /** Increment the event serial number. 01928 @ingroup evnum 01929 */ 01930 void evnum_incr(void); 01931 01932 01933 /** Get the current value of the event serial number. 01934 @ingroup evnum 01935 @return The current value of the event serial number. 01936 */ 01937 long evnum_get(void); 01938 01939 01940 // commenting out -- tap 01941 //t_numerical *num_new(short top, short left, short bottom, short right, method draw, 01942 // longmethod inc, long flags, long min, long max, long val, short font, short fsize); 01943 //void num_draw(t_numerical *x); 01944 //void num_hilite(t_numerical *x, short way); 01945 //long num_test(t_numerical *x, Point pt); 01946 //void num_track(t_numerical *x, Point pt, method track, void *arg); 01947 //void num_setvalue(t_numerical *x, long newval, short redraw); 01948 01949 01950 01951 // proxy functions 01952 01953 /** 01954 Use proxy_new to create a new Proxy object. 01955 01956 @ingroup inout 01957 @param x Your object. 01958 @param id A non-zero number to be written into your object when a message is received in this particular Proxy. 01959 Normally, id will be the inlet “number” analogous to in1, in2 etc. 01960 @param stuffloc A pointer to a location where the id value will be written. 01961 @return A pointer to the new proxy inlet. 01962 01963 @remark This routine creates a new Proxy object (that includes an inlet). It 01964 allows you to identify messages based on an id value stored in the 01965 location specified by stuffLoc. You should store the pointer 01966 returned by proxy_new() because you’ll need to free all Proxies in your 01967 object’s free function using object_free(). 01968 01969 After your method has finished, Proxy sets the stuffLoc location 01970 back to 0, since it never sees messages coming in an object’s leftmost 01971 inlet. You’ll know you received a message in the leftmost inlet if the 01972 contents of stuffLoc is 0. As of Max 4.3, stuffLoc is not always 01973 guaranteed to be a correct indicator of the inlet in which a message was 01974 received. Use proxy_getinlet() to determine the inlet number. 01975 */ 01976 void *proxy_new(void *x,long id,long *stuffloc); 01977 01978 01979 /** 01980 Use proxy_getinlet to get the inlet number in which a message was received. 01981 Note that the “owner” argument should point to your external object’s instance, not a proxy object. 01982 01983 @ingroup inout 01984 @param master Your object. 01985 @return The index number of the inlet that received the message. 01986 */ 01987 long proxy_getinlet(t_object *master); 01988 01989 01990 //void *gwind_new(t_object *assoc, t_symbol *s, short style, short left, short top, short bottom, short right); 01991 01992 01993 // connection functions 01994 void *connection_client(t_object *cli, t_symbol *name, t_symbol *classname, method traverse); 01995 void connection_server(t_object *obj, t_symbol *name); 01996 void connection_send(t_object *server, t_symbol *name, t_symbol *mess, void *arg); 01997 void connection_delete(t_object *ob, t_symbol *name); 01998 01999 02000 // quittask functions 02001 02002 /** 02003 Register a function that will be called when Max exits. 02004 02005 @ingroup misc 02006 @param m A function that will be called on Max exit. 02007 @param a Argument to be used with method m. 02008 02009 @remark quittask_install() provides a mechanism for your external to 02010 register a routine to be called prior to Max shutdown. This is useful for 02011 objects that need to provide disk-based persistance outside the 02012 standard Max storage mechanisms, or need to shut down hardware or 02013 their connection to system software and cannot do so in the 02014 termination routine of a code fragment. 02015 */ 02016 void quittask_install(method m, void *a); 02017 02018 02019 /** 02020 Unregister a function previously registered with quittask_install(). 02021 02022 @ingroup misc 02023 @param m Function to be removed as a shutdown method. 02024 */ 02025 void quittask_remove(method m); 02026 void quittask_remove2(method m, void *a); 02027 02028 02029 // notify functions 02030 void *notify_new(t_object *owner); 02031 void notify_enlist(t_object *dependent, t_object *owner); 02032 void notify_update(void *xx); 02033 void notify_free(t_object *owner); 02034 02035 // commenting out -- tap 02036 /* 02037 // syswind functions 02038 Boolean syswindow_inlist(t_syswind w); 02039 Boolean syswindow_isvisible(t_syswind w); 02040 Boolean syswindow_isfloating(t_syswind w); 02041 void syswindow_show(t_syswind w); 02042 void syswindow_hide(t_syswind w); 02043 void syswindow_move(t_syswind w, long x, long y, Boolean front); 02044 void syswindow_size(t_syswind w, long width, long height, Boolean update); 02045 t_wind *syswindow_wind(t_syswind w); 02046 */ 02047 02048 02049 02050 // miscellaneous functions 02051 02052 /** 02053 Determine version information about the current Max environment. 02054 02055 This function returns the version number of Max. In Max versions 02056 2.1.4 and later, this number is the version number of the Max kernel 02057 application in binary-coded decimal. Thus, 2.1.4 would return 214 hex 02058 or 532 decimal. Version 3.0 returns 300 hex. 02059 02060 Use this to check for the existence of particular function macros that are only present in more 02061 recent Max versions. Versions before 2.1.4 returned 1, except for 02062 versions 2.1.1 - 2.1.3 which returned 2. 02063 02064 Bit 14 (counting from left) will 02065 be set if Max is running as a standalone application, so you should 02066 mask the lower 12 bits to get the version number. 02067 02068 @ingroup misc 02069 @return The Max environment's version number. 02070 */ 02071 short maxversion(void); 02072 02073 02074 /** Get a unique number for each Patcher file saved. 02075 This function returns a serial number that is incremented each time a 02076 Patcher file is saved. This routine is useful for objects like table and coll 02077 that have multiple objects that refer to the same data, and can “embed” 02078 the data inside a Patcher file. If the serial number hasn’t changed since 02079 your object was last saved, you can detect this and avoid saving 02080 multiple copies of the object’s data. 02081 02082 @ingroup evnum 02083 @return The serial number. 02084 */ 02085 long serialno(void); 02086 02087 02088 char **palette(void); 02089 short ispatcher(t_object *x); 02090 short isnewex(t_object *x); 02091 // commenting out -- tap 02092 //short newex_knows(t_box *x, t_symbol *selector); 02093 void colorinfo(void *r); 02094 void *callback_new(void *assoc, ProcPtr proc, long refCon, short offset, ProcPtr *callfun); 02095 02096 02097 /** 02098 Use open_promptset() to add a prompt message to the open file dialog displayed by open_dialog(). 02099 02100 Calling this function before open_dialog() permits a string to 02101 displayed in the dialog box instructing the user as to the purpose of the 02102 file being opened. It will only apply to the call of open_dialog() that 02103 immediately follows open_promptset(). 02104 02105 @ingroup files 02106 @param s A C-string containing the prompt you wish to display in the dialog box. 02107 @return Ignore. 02108 02109 @see open_dialog() 02110 */ 02111 void open_promptset(char *s); 02112 02113 02114 /** 02115 Use saveas_promptset() to add a prompt message to the open file dialog displayed by saveas_dialog() 02116 or saveasdialog_extended(). 02117 02118 Calling this function before saveasdialog_extended() permits a string to 02119 displayed in the dialog box instructing the user as to the purpose of the 02120 file being opened. It will only apply to the call of saveasdialog_extended() that 02121 immediately follows saveas_promptset(). 02122 02123 @ingroup files 02124 @param s A C-string containing the prompt you wish to display in the dialog box. 02125 @return Ignore. 02126 02127 @see open_dialog() 02128 */ 02129 void saveas_promptset(char *s); 02130 02131 02132 void dialog_setkey(long type); 02133 void saveasdialog_pathset(short path, short force); 02134 void dialog_poll(short dosched, short doevent, unsigned short evtMask); 02135 void forecolor(short index, short way); 02136 void backcolor(short index, short way); 02137 void *tabfromhandle(long **handle, long size); 02138 void stdlist(t_object *x, t_symbol *s, short ac, t_atom *av); 02139 void assist_queue(t_object *x, method fun); 02140 void inspector_open(t_object *x, void *p, void *b); 02141 void *object_subpatcher(t_object *x, long *index, void *arg); 02142 02143 02144 02145 // filewatch functions 02146 02147 /** Create a new filewatcher. 02148 The file will not be actively watched until filewatcher_start() is called. 02149 The filewatcher can be freed using object_free(). 02150 02151 @ingroup files 02152 @param owner Your object. 02153 This object will receive the message "filechanged" when the watcher sees a change in the file or folder. 02154 @param path The path in which the file being watched resides, or the path of the folder being watched. 02155 @param filename The name of the file being watched, or an empty string if you are simply watching the folder specified by path. 02156 @return A pointer to the new filewatcher. 02157 @remark The "filechanged" method should have the prototype: 02158 @code 02159 void myObject_filechanged(t_myObject *x, char *filename, short path); 02160 @endcode 02161 */ 02162 void *filewatcher_new(t_object *owner, short path, char *filename); 02163 02164 /** Start watching a file using a filewatcher created with filewatcher_new(). 02165 @param x A filewatcher pointer, as returned by filewatcher_new(). */ 02166 void filewatcher_start(void *x); 02167 02168 /** Stop watching a file using a filewatcher created with filewatcher_new(). 02169 @param x A filewatcher pointer, as returned by filewatcher_new(). */ 02170 void filewatcher_stop(void *x); 02171 02172 02173 02174 // fileusage functions 02175 02176 /** Add a file to a collective. 02177 @ingroup files 02178 @param w Handle for the collective builder. 02179 @param flags If flags == 1, copy this file to support folder of an app instead of to the collective in an app. 02180 @param name The name of the file. 02181 @param path The path of the file to add. 02182 */ 02183 void fileusage_addfile(void *w, long flags, char *name, short path); 02184 02185 void fileusage_addfilename(void *w, long flags, char *name); 02186 void fileusage_addpathname(void *w, long flags, char *name); 02187 void fileusage_copyfolder(void *w, char *name, long recursive); 02188 void fileusage_makefolder(void *w, char *name); 02189 02190 02191 // fileformat functions 02192 void fileformat_stripsuffix(char *name, long *types, short numtypes); 02193 02194 02195 #ifdef WIN_VERSION 02196 // systext functions 02197 void systext_mactoansi(char *sz); 02198 void systext_ansitomac(char *sz); 02199 #endif 02200 02201 02202 #ifdef MAC_VERSION 02203 long fontinfo_getencoding(long id); 02204 long fontinfo_convert(t_object *x, char *src, long srclen, long encoding, char **out); 02205 long fontinfo_reconvert(t_object *x, char *src, long srclen, long encoding, char **out); 02206 void fontinfo_reconverthandle(t_object *x, char **h, long encoding); 02207 #endif 02208 02209 02210 long fontinfo_prefcheckencoding(void); 02211 02212 t_atom *atom_dynamic_start(const t_atom *static_array, long static_count, long request_count); 02213 void atom_dynamic_end(const t_atom *static_array, t_atom *request_array); 02214 02215 #ifdef __cplusplus 02216 } 02217 #endif 02218 02219 #endif // _EXT_PROTO_H_ 02220
Copyright © 2008, Cycling '74