Max 5 API Reference
Max 5 API Reference
00001 /** 00002 @page chapter_dragndrop Drag'n'Drop 00003 00004 The Max file browser permits you to drag files to a patcher window or onto objects to perform file operations. Your object can specify the file types accepted as well as a message that will be sent when the user releases the mouse button with the file on top of the object. UI and non-UI objects use the same interface to drag'n'drop. 00005 00006 Example UI object: <a href="pictmeter~_8c-source.html">pictmeter~</a>. Example non-UI: TBD. 00007 00008 Messages to support: 00009 @code 00010 acceptsdrag_locked (A_CANT) 00011 @endcode 00012 00013 Sent to an object during a drag when the mouse is over the object in an unlocked patcher. 00014 @code 00015 acceptsdrag_unlocked (A_CANT) 00016 @endcode 00017 00018 Sent to an object during a drag when the mouse is over the object in a locked patcher. 00019 00020 00021 @section chapter_dragndrop_discussion Discussion 00022 00023 Why two different scenarios? acceptsdrag_unlocked() can be thought of as an "editing" operation. For example, objects such as pictslider accept new image files for changing their appearance when the patcher is unlocked, but not when the patcher is locked. By contrast, sfplay~ can accept audio files for playback in either locked or unlocked patchers, since that is something you can do with a message (rather than an editing operation that changes the patcher). 00024 00025 Message handler definitions: 00026 @code 00027 long myobject_acceptsdrag_unlocked(t_myobject *x, t_object *drag, t_object *view); 00028 long myobject_acceptsdrag_locked(t_myobject *x, t_object *drag, t_object *view); 00029 @endcode 00030 00031 The handlers return true if the file(s) contained in the drag can be used in some way by the object. To test the filetypes, use jdrag_matchdragrole() passing in the drag object and a symbol for the file type. Here is list of pre-defined file types: 00032 00033 - audiofile 00034 - imagefile 00035 - moviefile 00036 - patcher 00037 - helpfile 00038 - textfile 00039 00040 or to accept all files, use file 00041 00042 If jdrag_matchdragrole() returns true, you then describe the messages your object receives when the drag completes using jdrag_object_add(). You can add as many messages as you wish. If you are only adding a single message, use jdrag_object_add(). For more control over the process, and for adding more than one message, jdrag_add() can be used. If you add more than one message, the user can use the option key to specify the desired action. By default, the first one you add is used. If there are two actions, the option key will cause the second one to be picked. If there are more than two, a pop-up menu appears with descriptions of the actions (as passed to jdrag_add()), and the selected action is used. 00043 00044 Example: 00045 00046 This code shows how to respond to an audiofile being dropped on your object by having the read message sent. 00047 @code 00048 if (jdrag_matchdragrole(drag, gensym("audiofile"), 0)) { 00049 jdrag_object_add(drag, (t_object *)x, gensym("read")); 00050 return true; 00051 } 00052 return false; 00053 @endcode 00054 00055 Your acceptsdrag handler can test for multiple types of files and add different messages. 00056 00057 00058 */
Copyright © 2008, Cycling '74