Method and apparatus for improved application program switching on a computer-controlled display system5530865Abstract A method and apparatus for transferring control between application programs. A messaging means is provided which allows a first application program to indicate to the messaging means that a second application program should assume control. The messaging means receives the message and performs an orderly shutdown of the first application program and messages the second application program that it should commence operation. Upon valid and proper operation of the second application program, the first application program is caused to be suspended, and the second application program is invoked. Claims What is claimed is: Description BACKGROUND OF THE INVENTION
TABLE 1
______________________________________
Dragging Semantics
To
File System
Document Same Different
Finder
From Same Different
Volume Volume Service
______________________________________
Document
Move Copy Copy Copy
Finder Copy Move Copy Copy
______________________________________
Thus, the general rule is that, if the window represents a different item or location, then the action is interpreted as a copy operation. In the case of a same document or same media volume, then it is interpreted as a move operation. Note that, in the cases where the action is in doubt, a copy operation is assumed to avoid any data loss which may occur. Thus, for the same document or window in which the data resides, the operation is assumed to be a move operation. Similarly, if it is the same physical media or same volume, then it is assumed that the operation is a move. In all other cases, if the windows are different or it is between a document and the Finder or a document in a Finder service, then the operation is assumed to be a copy operation or performing the Finder service which the icon or other Finder service performs (e.g., printing, sending electronic mail, etc.). Finder Icons When the user drags a document to a folder icon in the Finder, the behavior of the drop feedback is the reorganization of the document into the folder; the visual component is the disappearance of the document icon and the unhighlighting of the destination folder icon (in the case of a "move" operation). If an icon represents a system service, such as an electronic mail or printing, the drop feedback is followed by some indication that the service is being delivered. For example, if the user drags a document to a printer, the icon would slowly "fill up" in color as the printing job progresses towards completion. This is called "progress feedback" and is represented using a progress bar or other feedback. One method is illustrated in FIGS. 18c and 18d. For example, as is illustrated in FIG. 18c, a progress window 1880 may be displayed upon dropping an item into a system service such as a printing routine, as was illustrated in FIGS. 9a-9d. A progress bar window, such as 1880 shown in FIG. 18c, may be displayed first. As is illustrated, progress bar 1890 is currently clear indicating that no printing has yet taken place at this initial stage. In a short time later, however, as illustrated in FIG. 1890, it may have a dark region 1895 which fills up the progress bar indicating the percentage of completion of the printing job. Other types of system service feedback may be provided using various techniques well-known to those skilled in the art. Graphics When dropping graphics, the drop feedback is the movement of the actual object to the location of the mouse-up event (the release of the selection device), in the preferred embodiment. This was illustrated in FIGS. 6a-6c. Text After dropping text, the drop feedback is the movement or copying of text from the source to the destination, accompanied by a series of "zooming rectangles" from the source text to the destination text in the preferred embodiment. The zooming rectangles are provided using a routine ZoomRects( ) described below and are displayed only after the text is rewrapped because the destination text may end up being a distance away from the exact point where the user dropped the text. If a "move" operation is in effect, the source text disappears. In either case, the text is inserted at the destination is selected and may be performed using the techniques disclosed in Ser. No. 07/993,784 assigned to the assignee of the present invention. Transferring Selections After a successful drag-and-drop sequence involving a single window, the selection feedback is transferred from the source to the destination. This is discussed with reference to FIGS. 19a and 19b. In a single window 1901, as is illustrated in FIG. 19a, selected text 1902 may be desired to be moved. As is illustrated in FIG. 19b, text 1902 has been moved, and the region remains selected. This process of copying between windows is illustrated in FIGS. 19c and 19d. Background Window Dropping The results of the process of dragging and dropping into a background window is illustrated with reference to FIGS. 19c and 19d. For example, a user may desire to select text (e.g., 1915) in a first window 1910, which is active, and copy that text to a second window 1920, which is not active (e.g., it may be controlled by an inactive application program). This can be applied to any type of data being selected, dragged, and dropped between windows. The results of the drag and drop are shown in FIG. 19d. As is illustrated, background window 1920 does not become active (e.g., its title bar 1926 is not shown in active state), and region 1925 is shown in the single-pixel outline representation surrounding the copied text 1925 from 1915 from window 1910. The window is also not brought to the front, in this circumstance. Abort Feedback Dropping outside a destination is considered as an "abort" and is indicated in the preferred embodiment by zooming rectangles that originate at the position of the drop and end at the source's location. If, for some reason, dropping inside a destination does not result in a successful operation, zooming rectangles are used in the preferred embodiment. This is a form of "negative" drop feedback. This is illustrated with reference to FIGS. 20-20e. For example, a user may drag, using cursor 2000, an icon 2020 into a second window 2002, as is illustrated in FIG. 20a. This is folder 2010 which was dragged from window 2001, as is shown by its highlighted state. Then, as illustrated in FIG. 20b, the abort may be indicated by series of "zooming rectangles" 2030 generated by the subroutine ZoomRects() discussed below. As is illustrated in FIG. 20c, zooming rectangles head back towards the original folder 2010 until the zooming rectangles completely disappear from the screen, as shown in FIG. 20d. This is an animated effect indicating to the user that the drag operation was unsuccessful. Summary of the Behavior of Windows Independent Windows When a window is brought to the front, in the preferred embodiment, only that specific window is brought to the front; the entire window hierarchy belonging to the application is not brought to the front, as in prior art systems. This behavior makes it easier to have a source window and destination window side-by-side, especially when the two windows belong to different applications. Even with this behavior, the user is still able to bring the entire window hierarchy belonging to an application to the front. This can be done in the preferred embodiment by choosing the application's menu item in an application menu of the user interface display. In the case of the Finder, clicking on the desktop brings the Finder's window hierarchy to the front. Also, double-clicking on the application's Finder icon brings the entire window hierarchy of the application to the front. Bringing Windows to the Front In the preferred embodiment, as already been illustrated, the release of the selection device (the mouse-up event) serves as the application-switching trigger (instead of the mouse-down event as in the prior art), subject to certain exceptions. If the user clicks inside an inactive window without dragging at least three pixels between the mouse-down and mouse-up events (no drag has taken place), the window is brought to the front. If the user drags wholly inside an inactive window (i.e., the source and destination are in the same inactive window), the window is brought to the front as soon as the mouse-up event occurs. If the user drags from any window to another window that is inactive, the inactive window is not brought to the front after the drag-and-drop sequence is completed. If the drag-and-drop sequence ends at the Finder desktop, no window is brought to the front. As discussed above, whenever an inactive window is brought to the front, a background selection (if any) in that window becomes highlighted as a normal selection, instead of the single-pixel outline representation. Drag Verbs There are three ways in which the user can specify the drag verb that is applied to a given drag-and-drop sequence. The first way is to perform the drag without holding down any modifier keys. In this case, the most frequently used or most likely verb is applied. For example, a printing routine assumes that a print operation is to take place, and the sending application program and the system service negotiate the type of data transmitted to allow the information to be printed (see, discussion below). The second method is when the user performs the drag while holding down the Option key. This method specifies the secondary verb. In most cases, this verb would be Copy. However, in cases where Copy is not applicable, the verb can be something else, such as overriding the confirmation dialog when dragging an icon from a remote read-only volume to the desktop. The third way of specifying the drag verb is to hold down the Control key when dragging; as soon as the dragged object is dropped, a verb selection dialog appears, as in FIG. 21. The user can choose the verb in this dialog, or cancel the operation altogether. For example, as is illustrated in FIG. 21, a dialog window 2110 is displayed. The user may select, such as using cursor 2100, a selection 2102 in verb list 2105. As is typical in standard prior an Macintosh.RTM. dialog boxes, the user may either double-click, using cursor 2100 and the selection device, a selection such as 2102 to cause the verb to be performed or select "OK" button 2104. To cancel the operation, the user selects "Cancel" button 2103. The list of verbs displayed will be a match between data item flavors, which are specified by the sending application program, and the service performed by the object at the destination (e.g., a printing or mail service). Functional Description Drag Handlers and Drag Procedures Application programs supply the Drag Manager callback routines (e.g., pointers to routines in the program) that the Drag Manager calls to allow the application to implement dragging. The Drag Manager uses two different types of callback routines, called drag handlers and drag procedures. Drag handlers are routines that are installed on windows that the Drag Manager uses when dragging over that window. Drag procedures are routines that are used by the Drag Manager during a drag regardless of which window the user may be dragging over. The Drag Manager allows application programs to install the following drag handlers on the program's windows: a receive data handler that the Drag Manager calls when the user finishes a drag in one of an application's windows a drag tracking handler that the Drag Manager calls when the user drags a selection through one of the application's windows to allow the application to track the drag within the window a constrain mouse handler that the Drag Manager calls when the user drags a selection through one of the application's windows to allow the application to modify the mouse coordinates The Drag Manager provides a family of InstallHandler and RemoveHandier routines that allow an application program to register handlers of each of these types with the application. An application can register a different set of handlers to be used for each window in the application. An application can also register with the Drag Manager a set of handlers to be used when a window does not have its own handlers. If an application assigns more than one handler of the same type on the same window, the Drag Manager calls each of these handler routines in the order that they were installed. This technique is known as "chaining" and allows the control of various areas in a window, such as icons, subwindows, fields, panes, or other user interface objects. FIG. 22 shows an example of the tracking handler registry 2200 for an application that has installed two handlers 2211 and 2212 for its "Graphics" window 2210, a single handler 2221 for its "Documents" window 2220 and a single handler 2231 to be used for all of the application's other windows. When the Drag Manager 2280 tracks a drag through the "Documents" window, handler 2221 is called. When the Drag Manager tracks a drag through the "Graphics" window, handler 2211 is called followed by handler 2212 being called. Finally, if the Drag Manager tracks a drag through any other window in the application, handler 2231 is called. For example, handler 2211 and 2212 may be two distinct tracking handlers, one for the window itself and a second for a specific icon or other ornament within the window. This may be an additional pane for a window or other type of object within a window. The "Documents" window and other windows which are accessed by the tracking handler registry 2200 for this particular application program will have only single tracking handlers 2221 and 2231, respectively, associated with them for any and all actions within windows in those circumstances. The second type of callback routine that may be provided to the Drag Manager is a drag procedure. The Drag Manager uses the following drag procedures: a send data procedure that the Drag Manager calls when the receiver application requests a drag item flavor that the Drag Manager does not currently have the data cached for a drag input procedure that the Drag Manager calls when sampling the mouse position and keyboard state to allow the application program to override the current state of the input devices a drag drawing procedure that if provided by the sender application program, the Drag Manager calls to allow the sender application to assume responsibility for drawing the drag feedback on the screen Sending Data When the user chooses a destination for the items being dragged, the receiving application program may request from the Drag Manager any number of types of data. These various types of data are known, in the preferred embodiment, as drag item "flavors." Flavors may be of any son, including ASCII text (flavor type `TEXT`), styled text (`styl`), and rich text (`rtf`). Many other flavors may be used, in the preferred embodiment, according to the data types that the sending and receiving application programs understand. Another advantage to the method(s) and apparatus of the preferred embodiment is that sending application programs may provide data in addition to flavors. This is done if there is sufficient time available to provide the data in addition to the flavor. If the sending application program provided the flavor's data to the Drag Manager when calling one of the AddFlavor routines, the Drag Manager will simply provide that data to the receiver. The application program may have chosen not to provide the data to the Drag Manager when calling one of the AddFlavor routines because it might have taken too long to prepare the data (and, perhaps, cause a user-perceivable performance penalty), or there might not have been enough memory to store the data. In this case, the Drag Manager calls the DragSendProc (if one was given to the Drag Manager) to allow the sending application to provide the data to the Drag Manager only when needed by the receiver, and the flavors provided act as "promises" which may be fulfilled at such time that the receiver requests the data. If the sending application only exports small pieces of data that are easily generated, the data would presumably by provided when calling the AddFlavor routines discussed below and therefore the sender application would not need to provide a DragSendProc. Receiving Data When the user drops a collection of items in one of a receiving application's windows, the Drag Manager calls all of the ReceiveDropHandler routines that are installed on the destination window. This call allows the program to request the drag item flavors that the receiving application wishes to accept. The receiver application program can inspect the available flavors by using the CountDragItems, GetItemReferenceNumber, CountDragItemFlavors, GetFlavorType, GetFlavorFlags and GetFlavorData functions which are described in more detail below. It receives flavor from the sender application by calling the GetFlavorData function. The GetFlavorData function calls the sender's SendDataProc if necessary to get the data for the receiver. Drag Tracking While the user drags a collection of items on the screen, as the mouse passes through one application's windows, the Drag Manager calls the DragTrackingHandler routines that are installed on the window under the mouse to allow the application program to track the drag through its windows. For example, this allows the highlight or other drag feedback to take place, as discussed below with reference to FIGS. 16-18b. The Drag Manager sends the application's DragTrackingHandler tracking status messages as the user moves the mouse. The DragTrackingHandler receives the following messages from the Drag Manager: an enter handler message when the focus of a drag enters a window that is handled by an application's DragTrackingHandler from any window that is not handled by the same DragTrackingHandler an enter window message when the focus of a drag enters any window that is handled by an application's DragTrackingHandler an in window message as the user drags within a window handled by the application's DragTrackingHandler a leave window message when the focus of a drag leaves any window that is handled by an application's DragTrackingHandler a leave handler message when the focus of a drag enters a window that is not handled by an application's DragTrackingHandler When an application's handier receives any of these messages from the Drag Manager, it can use the CountDragItems, GetItemReferenceNumber, CountDragItemFlavors, GetFlavorType and GetFlavorFlags routines to inspect the drag item flavors that are contained in the drag to determine if the application program should highlight its window or a portion of its window. The in window message can be used to highlight specific containers within a window or if window contains a text field, an insertion point within the text field. The enter window and leave window messages occur in pairs. These messages are useful for highlighting a window that can accept the items being dragged. The enter handler and leave handler messages also occur in pairs. These messages only occur when the drag moves between windows that are handled by different routines. These messages are useful for allocating and releasing memory that the application might need when tracking within a specific set of windows. FIG. 23 shows an example of a user dragging a clippings file from a Finder window 2310 through two windows 2320 and 2330 of a word processing application. The following example demonstrates what tracking messages are sent to the Finder's tracking handier and an application requested by icon 2311 during a drag: Cursor 2300 at position 2350--The user clicks and drags on the clippings file and the Finder starts a drag. The Finder receives an enter handler message followed by an enter window message. As the user drags within the Finder's "Clippings" window, the Finder receives multiple in window messages. Cursor 2300 at position 2360--When the user drags into the word processor's "Untitled 1" window, the Finder receives a leave window message followed by a leave handler message. The word processing application then receives an enter handler message followed by an enter window message. While the user drags within the application's "Untitled 1" window 2320, the application program receives in window messages. Cursor 2300 at position 2370--Assuming that both of the word processor's windows 2320 and 2330 are handled by the same DragTrackingHandler, when the user drags into the "Sample Text" window, the word processing application receives a leave window message followed by an enter window message. It does not receive any enter/leave handler messages since the same handler routine is used for both windows. As the user drags within the application's "Sample Text" window 2330, the application receives in window messages. Cursor 2300 at position 2380--When the user releases the selection device when the cursor is at position 2380, the data transaction occurs. Then the word processing application receives a leave window message followed by a leave handler message. Drag tracking is now complete. Using the Drag Manager The Drag Manager allows the user to drag items in and out of a window or other object controlled by an application program. Before items can be dragged into or out of a window, the application program must register a set of drag handlers for the Drag Manager to use when the application is involved in dragging. A drag and drop action by the user is broken down into three discrete steps. The steps are first to pick up the item or items being dragged, then to track the selection being dragged through application windows as the user searches for a place to drop the selection, and finally to then drop the item or items at the user's chosen destination. This section explains in detail how the Drag Manager is used to: install and remove drag handlers to and from the Drag Manager's handler registry for the application's windows prepare the Drag Manager with drag items and drag item flavors start a drag process track a drag through the application's windows send data to the receiver of a drag that originated from an application's windows request and receive data flavors from the sender application when the user drops the selection within an application's windows Installing and Removing Drag Handlers A drag handler is registered with the Drag Manager using the InstallHandler functions. There is a separate InstallHandler function for each kind of handler. These functions are InstallReceiveHandler, InstallTrackingHandler and InstatlConstrainHandler. Each of the InstallHandler functions takes a pointer to a window that the application wants to associate the handler with. If NIL is supplied as the window pointer, the Drag Manager will register the handler in the special area that is used when a drag occurs in a window that is not registered with the Drag Manager. Handlers installed in this special area are called default handlers. A reference constant may be passed to each of the InstallHandler functions. This value is stored by the Drag Manager and is forwarded to each handler's routine when it is called. The following code segment shows how to use the InstallHandler functions to install a default handler for the application:
______________________________________
OSErr MyInitDragManager()
{ OSErr result;
if (result = InstallReceiveHandler
(MyDefaultReceiveHandler, NIL, &myGlobals)) {
return(result);
return(InstallTrackingHandler
(MyDefaultTrackingHandler, NIL, &myGlobals));
}
______________________________________
The function MyInitDragManager calls InstallReceiveHandler and InstallTrackingHandler to install default receive and tracking handlers for the application program. In the window parameter, NIL is passed to specify that these handlers should be installed as default handlers. A pointer to the application's global variables is passed in the reference constant parameter. The following shows how to use the InstallHandler functions to install handlers for a specific window:
______________________________________
OSErr MyDoNewWindow(WindowPtr *newWindow)
{ OSErr result;
WindowPtr theWindow;
if (!(theWindow = GetNewWindow(kMyWindowID,
0L, -1L))) {
return(resNotFound);
if (result = InstallReceiveHandler(MyReceiveHandler,
theWindow, &myGlobals)) {
DisposeWindow(theWindow);
return(result);
}
if (result = InstallTrackingHandler(MyTrackingHandler,
theWindow, &myGlobals)) {
DisposeWindow(theWindow);
return(result);
}
*newWindow = theWindow;
return(noErr);
}
______________________________________
The function MyDoNewWindow calls all three of the InstallHandler functions to install a set of drag handlers for the window that it creates. In DoNewWindow, the window pointer is passed to the InstallHandler functions. In the scenario created in the last two example functions, the Drag Manager will use the MyReceiveHandler and MyTrackingHandler functions when the focus of a drag occurs within any window created with the DoNewWindow function. Any other windows in the application would use the MyDefaultReceiveHandler and the MyDefaultTrackingHandler functions. To remove a drag handler from the Drag Manager's handler registry, the RemoveHandler functions are used. The following shows how to remove drag handlers:
______________________________________
OSErr MyDoCloseWindow(WindowPtr theWindow)
RemoveReceiveHandler(MyReceiveHandler, theWindow);
RemoveTrackingHandler(MyTrackingHandler, theWindow);
DisposeWindow(theWindow);
return(noErr);
}
______________________________________
The function MyDoCloseWindow demonstrates the use of the RemoveHandler functions. The same routine address and window pointer is used to remove a handler. If NIL is used as the window pointer, the Drag Manager will attempt to remove the handler from the default handler registry. Beginning a Drag When the user clicks on an item or a selection of items in an application and begins to move the mouse without first releasing the mouse button, the user is making a gesture to begin dragging the selected objects. To start a drag, a new drag reference is created by calling the NewDrag function. The NewDrag function returns a reference number that the application uses to refer to a specific drag process in subsequent function calls to the Drag Manager. After creating a new drag reference, drag item flavors can be added to the drag by calling the Drag Manager's AddFlavor functions. When all of the data describing the items contained in the drag has been given to the Drag Manager, the application calls TrackDrag to actually begin the drag. The following code segments show how mouse down events and start drag operations are handled.
______________________________________
OSErr MyDoMouseDown(EventRecord *theEvent)
{ OSErr result = noErr;
short thePart;
WindowPtr theWindow;
Boolean onItem;
thePart = FindWindow(theEvent->where, &theWindow);
switch(thePart) {
case inContent:
if (theWindow == FrontWindow()) {
MyDoContentClick(theEvent, theWindow, &onItem);
if (onItem && WaitMouseMoved(theEvent)) {
result = MyDoStartDrag(theEvent, theWindow);
} else {
SelectWindow(theWindow);
}
case ...
}
return(result);
}
______________________________________
The function MyDoMouseDown above shows a simplified mouse down event service routine. Only the code for handling an inContent part code from FindWindow is shown. The MyDoContentClick function either selects, extends the selection or deselects an item in the application's document window. The onItem parameter it returns is true if the mouse down event occurred on a draggable item. The routine then calls WaitMouseMoved, which is a Drag Manager function that waits for the mouse button to be released or the mouse to move from its mouse down location. It returns true if the mouse moved. The MyDoStartDrag function, which is listed below, is called if the user gestures to start a drag.
______________________________________
OSErr MyDoStartDrag(EventRecord *theEvent, WindowPtr
theWindow)
{ OSErr result;
DragReference
theDrag;
if (result = NewDrag(&theDrag, (long) theWindow)) {
return(result);
if (result = MyDoAddFlavors(theWindow, theDrag)) {
DisposeDrag(theDrag);
return(result);
}
return(TrackDrag(theDrag));
}
______________________________________
The MyDoStartDrag function above first creates a new drag by calling the NewDrag function. It then calls the MyDoAddFlavors function, which is defined below, to add the application's drag item flavors to the drag. Finally, TrackDrag is called to perform the drag. To add drag item flavors to a drag, the AddFlavor functions are used. The AddFlavor functions require a drag reference number to add the flavor to. The application program also provides an item reference number when adding flavors. The handlers may specify any item reference numbers when adding items. The same item number is used for adding flavors to the same drag item. Using a different item number results in a new item being created.
______________________________________
OSErr MyDoAddFlavors(WindowPtr theWindow,
DragReference theDrag)
{ MyDocumentItem *theItem;
theItem = GetFirstSelectedItem(theWindow);
while (theItem) {
AddDragItemFlavor(theDrag, theItem, `MOOF`,
(Ptr) *(theItem->dataHandle),
GetHandleSize(theItem->dataHandle), 0);
AddDragItemFlavor(theDrag, theItem, `TEXT`,
(Ptr) 0L, 0L, 0);
if (theItem->hasStyles) {
AddDragItemFlavor(theDrag, theItem, `styl`, (Ptr) 0L, 0L, 0);
AddDragRegionFlavor(theDrag, theItem, theItem->
region);
theItem = theItem->nextSelectedItem;
}
}
______________________________________
The MyDoAddFlavors function shown above uses the Drag Manager's AddFlavor functions to add three or four flavors to the drag for each item that is selected in the window. The first call to AddDragItemFlavor uses the document item pointer as the drag item reference number. Since this is the first flavor added to the drag, a new drag item is created with that item number. The first flavor for the item is the application's own internal data type `MOOF`. A pointer to the data and the data's size is also passed to the AddDragItemFlavor function. The second call to AddDragItemFlavor uses the same document item pointer as the drag item reference number. Since this is the same item number as the last call, the second flavor is added to the same drag item. This flavor is of type `TEXT`. Suppose that an application does not want to create the plain text data unless this flavor is specifically requested by the receiver of a drag. A NIL pointer and zero size is passed to AddDragItemFlavor. By passing NIL, the Drag Manager will call this application DragSendProc to get the data later, if needed. In this example, an item in the selection may have text styles (such as bold or italic characters), and if it does, it also adds a `styl` flavor. Again, the same item number is used to add the flavor to the same drag item. The flavor data is not provided; it will only be created if needed. Finally, AddDragRegionFlavor is called to add the item's drag region to the item. This region is given in global coordinates. The Drag Manager uses this region to drag the dotted outline of the drag on the screen. The receiver may want to get the region to determine where to place the contents of the item. The MyDoAddFlavors function loops to the next selected item in its list. When it adds the flavors for the next item, it will be using a different item number (since the address of the next item is guaranteed to be different), which will result in a new drag item being created. To illustrate the effect of calling the MyDoAddFlavors function defined above, FIGS. 24 and 25 show an example list of selected items and the resulting drag items and drag item flavors. For example, as each item is selected, it is added to a linked list, as is illustrated by 2400 in FIG. 24. For example, as each item in windows are selected, drag items are acted to a selected item list, such as 2400 illustrated in FIG. 24. As each item is selected, a datum is added, such as 2410, 2420, and 2430, to the selected item list 2400. Each item contains four fields, each representing different portions of the item being selected. A first field (e.g., 2410a, 2420a, and 2430a) contains an integer representing a reference drag item number. A second field (e.g., 2410b, 2420b, and 2430b) contains the actual item information, which is shown in more detail below with reference to FIG. 25. 2410c contains an integer value representing a number of styles which are added in addition to a specific flavor of type `TEXT.` As shown, only 2430c has a value that is non-zero, indicating that one additional flavor type is promised by the sending process. 2410d, 2420d, and 2430d each contain references to the next drag item in the list with the last drag item pointer 2430d containing the pointer NIL indicating that no other drag items are being dragged and tracked by the Drag Manager. A more detailed view of the drag items in a drag item list, such as 2500, is illustrated in FIG. 25. For example, drag item 2410b contains three flavors, `MOOF` 2561, `TEXT` 2562, and `drgn` 2563. Because the application was able to create flavor data 2561a of type `MOOF,` field 2561 contains a flavor data field 2561a. The data type of type `TEXT` was not able to be created at the time of the drag, so a DragSendProc would need to be invoked in order for the sending application to provide that data to the receiver. Lastly, 2563 contains a drag region so that the Drag Manager may keep track and provide visual feedback to the user of the dotted drag item region while the drag is taking place across the user interface display. This flavor data is provided in field 2563a, which is a bitmap representation of the item as created by the sending application program's handler. Similarly, drag items 2420b and 2430b contain similar fields, with the exception that drag item 2430b contains an additional flavor type of type `styl` in field 2583, which might be made available to the receiving application upon the detection of the release of the selection device (e.g., a mouse-up event), as detected by the Drag Manager. The Drag Manager also provides two additional AddFlavor routines. They are AddHFSFlavor, which adds an HFSFlavor record given an FSSpec record, and AddAEFlavor, which adds the data contained within an AEDesc record, using the descriptor's data type as the flavor type. Tracking a Drag After creating a new drag with NewDrag, adding drag item flavors to the drag by using the AddFlavor functions, and starting the drag with TrackDrag, the Drag Manager proceeds by tracking the drag until the user releases the mouse button. During the drag, as the user moves the mouse on the screen, searching for a destination for the drag items, the Drag Manager sends a sequence of tracking messages to the tracking handlers that are registered for the window that the mouse is over. A tracking handler can inspect the drag item flavors contained in a drag and highlight the application's windows or part of an application's windows in response to data that the application can accept. The next code segment shows an example of a very simple tracking handler. This tracking handler highlights the window if any of the drag items contains either the application's `MOOF` flavor or the `TEXT` flavor. It also calls an application defined function MyTracklternUnderMouse that could be defined to highlight other parts of the window as the mouse moves through the window.
______________________________________
OSErr MyTrackingHandler(short theMessage, Point mouse,
WindowPtr theWindow, GlobalsPtr
myGlobals, DragReference theDrag)
switch(theMessage) {
case kDragEnterHandlerMessage:
myGlobals->canAcceptDrag = IsMyTypeAvailable(theDrag);
break;
case kDragEnterWindowMessage:
if (myGlobals->canAcceptDrag) {
ShowDragHilite(theDrag,
((WindowPeek) theWindow)->contRgn, true);
}
break;
case kDragInWindowMessage:
if (myGlobals->canAcceptDrag) {
MyTrackItemUnderMouse(mouse, theWindow);
}
break;
case kDragLeaveWindowMessage:
if (myGlobals->canAcceptDrag) {
HideDragHilite(theDrag);
}
break;
case kDragLeaveHandlerMessage:
myGlobals->canAcceptDrag = false;
break;
}
}
______________________________________
The MyTrackingHandler function defined above switches on the given message from the Drag Manager. If the message is kDragEnterHandlerMessage, the routine calls the application's IsMyTypeAvailable function, which is defined below, that returns either true or false, depending on whether or not a type is available that the application window can accept. The result of this function is stored in the application's global variable canAcceptDrag. When MyTrackingHandler received the kDragEnterWindowMessage message, it checks its global canAcceptDrag to determine if the window can accept the drag. If it can, the Drag Manager utility function ShowDragHilite is called to highlight the window. When the kDraglnWindowMessage message is received, if the window can accept the drag, the application's MyTrackItemUnderMouse is called. Presumably, MyTrackItemUnderMouse would use the mouse coordinate given by the Drag Manager to determine if the mouse is over an object that must also be highlighted. When the kDragLeaveWindowMessage message is received, if the window can accept the drag, the Drag Manager utility function HideDragHilite is called to remove the window highlighting. Finally, when the kDragLeaveHandlerMessage message is received, the application's global canAcceptDrag is reset to false. To determine what drag item flavors are available, an application calls routines in the Drag Manager known as CountDragItems, GetItemReferenceNumber, CountDraglternFlavors, GetFlavorType and GetFlavorFlags functions to determine how many drag items there are, return an item's reference number (e.g., stored in field 2410a), determine how many drag item flavors there are in a drag item, return a drag item flavor's type (e.g., stored in flavor 2561), and the flags identifying the attributes of a flavor. The next code segment shows the IsMyTypeAvailable function which demonstrates the use of these functions.
______________________________________
Boolean IsMyTypeAvailable(DragReference theDrag)
{ short items, index, result;
long flavorFlags;
ItemReference
itemID;
CountDragItems(theDrag, &items);
for (index= 1; index<= items; index++) {
GetItemReferenceNumber(theDrag, index, &itemID);
result = GetFlavorFlags(theDrag, itemID, `MOOF`,
&flavorFlags);
if ((result == noErr) && (flavorFlags &
kFlavorAvailable))
return(true);
result = GetFlavorFlags(theDrag, itemID, `TEXT`,
&flavorFlags);
if ((result == noErr) && (flavorFlags &
kFlavorAvailable))
return(true);
return(false);
}
______________________________________
The IsMyTypeAvailable function defined above counts the number of items in the drag and begins a loop through each of the items. It returns true when it encounters the fast item that contains either a `MOOF` flavor or a `TEXT` flavor, which are types (flavors) that this receiver can handle. The IsMyTypeAvailable function was used to determine if the application should highlight its window. In this manner, arbitration may be performed between sending and receiving handlers to test to determine if a type that the receiving application can receive. After the user releases the mouse button, the Drag Manager proceeded to the data transaction stage to the finish the drag. Finishing a Drag When the user has chosen a final destination for the items being dragged, the Drag Manager calls any receive drop handlers installed on the destination window. An application program's receive drop handler is responsible for accepting the drag by transferring the information being dragged into the destination location. A receive handler gets a pointer to the destination window, the handler's reference constant and the drag reference. The receive handler routine can call the CountDragItems, GetItemReferenceNumber, CountDragItemFlavors, GetFlavorType and GetFlavorFLags functions to determine what data types (flavors) are included in the drag. The GetFlavorData function can be used to get flavor data from the sender that the receiver application desires. The next code segment shows an example receive handler that attempts to receive a `MOOF` type and if available inserts it into the destination file's data and then on the display. If there is no `MOOF` flavor in the item, the handler checks to see if a `TEXT` type is available. If `TEXT` is available in the item, the handler gets the `TEXT` data and then also checks to see if a `styl` type is available. If `styl` is available, the handler get the `styl` data also. The handler inserts the `TEXT` data and optionally the `styl` data into the destination file's data and then on the display.
______________________________________
pascal OSErr MyReceiveHandler(WindowPtr theWindow,
unsigned long handlerRefCon,
DragReference theDrag)
{ Point mouse;
short items, index, result;
long flavorFlags, dataSize, stylSize;
ItemReference
itemID;
Ptr theData, theStyl;
DragGetMouse(&mouse, 0L, theDrag);
CountDragItems(theDrag, &items);
for (index = 1; index <= items; index++) {
GetItemReferenceNumber(theDrag, index, &itemID);
//
// First try to get type `MOOF`.
//
result = GetFlavorFlags(theDrag, itemID, `MOOF`,
&flavorFlags);
if ((result == noErr) && (flavorFlags &
kFlavorAvailable)) {
// Determine the size of the `MOOF` data
dataSize = 0;
GetFlavorData(theDrag, itemID, `MOOF`, 0L,
&dataSize, 0L);
// Allocate space for the `MOOF` data
theData = NewPtr(dataSize);
// Get the `MOOF` data
GetFlavorData(theDrag, itemID, `MOOF`, theData,
&dataSize, 0L);
// Put the data into the destination location
MyInsertDataAtPosition(theData, dataSize, mouse,
theWindow);
DisposePtr(theData);
} else {
//
// Since there is no `MOOF` type in the drag, try
to get
// `TEXT` and possibly `styl`.
//
result = GetFlavorFlags(theDrag, itemID, `TEXT`,
&flavorFlags);
if ((result == noErr) && (flavorFlags &
kFlavorAvailable)) {
// Determine the size of the `TEXT` data
dataSize = 0;
GetFlavorData(theDrag, itemID, `TEXT`, 0L,
&dataSize, 0L);
// Allocate space for the `TEXT` data
theData = NewPtr(dataSize);
// Get the `TEXT` data
GetFlavorData(theDrag, itemID, `TEXT`,
theData, &dataSize, 0L);
// Check for `styl` to accompany `TEXT`
theStyl = 0L;
result = GetFlavorFlags(theDrag, itemID,
`styl`, &flavorFlags);
if (result == noErr) && (flavorFlags &
kFlavorAvailable)) {
// Determine the size of the `styl` data
stylSize = 0;
GetFlavorData(theDrag, itemID, `styl`, 0L,
&stylSize, 0L);
// Allocate space for the `styl` data
theData = NewPtr(stylSize);
// Get the `styl` data
GetFlavorData(theDrag, itemID, `styl`,
theStyl, &stylSize, 0L);
MyInsertStylTextAtPoint(theData, dataSize, theStyl,
stylSize, mouse, theWindow);
DisposePtr(theData);
if (theStyl)
DisposePtr(theStyl);
}
}
}
return(noErr);
}
______________________________________
If the receiver of a drag requests a flavor, and if the sending application provided the flavor data to the Drag Manager when adding the flavor with one of the AddFlavor functions, the Drag Manager simply provides the data to the receiver. If the sender did not provide the flavor data to the Drag Manager when adding the flavor, the Drag Manager calls the sender's DragSeProc to allow the sending application program to provide the data to the Drag Manager on demand. The Drag Manager calls the DragSendProc with the request flavor type, an optional acceptorDescriptor parameter, the handler's reference constant, and the item an Drag reference numbers. The SetDragItemFlavorData function is used to provide the requested data to the Drag Manager in the DragSendProc.
______________________________________
pascal OSErr MySendDataProc(FlavorType theType, const
AEDesc *acceptorDescriptor,
unsigned long refCon,
ItemReference theItem,
DragReference theDrag)
{ OSErr result;
Document *theDocument = (Document *) theItem;
if (theType == `TEXT`) {
SetDragItemFlavorData(theDrag, theItem, `TEXT`,
MyGetSelectedTextPtr(theDocument),
MyGetSelectedTextSize(theDocument));
} else if (theType == `styl`) {
SetDragItemFlavorData(theDrag, theItem, `styl`,
MyGetSelectedStylPtr(theDocument),
MyGetSelectedStylSize(theDocument));
} else {
return(badDragFlavorErr);
return(noErr);
}
______________________________________
The MySendDataProc function shown above provides both the `TEXT` and `styl` flavors to the Drag Manager. The routine uses the item reference number as a pointer to the application's Doctortent data structure (this pointer was used when adding the drag item flavors with AddDragItemFlavor). This example routine calls several of its own routines that would presumably return the memory addresses and data sizes of both the selected text and the `styl` data. The Drag Manager's SetDragItemFlavorData function is called to pass the requested data to the Drag Manager. Drag Manager Variables and Routines This section describes the Drag Manager's constants, data structures and routines. The "Constants" section describes the constants received from the Drag Manager and used when calling Drag Manager routines. The "Data Structures" section shows the data structures used to refer to drags, drag items, drag item flavors and to special drag item flavor data. The "Drag Manager Routines" section describes Drag Manager routines for installing and removing drag handlers, creating and disposing of drag references, adding drag item flavors to a drag, providing drag callback routines, tracking a drag, getting drag item information, getting drag status information, window highlighting and Drag Manager related utilities. The "Application-Defined Routines" section describes the drag handler functions, the drag callback functions and the zoom callback function. Constants The constants described in this section are received from the Drag Manager and used when calling Drag Manager routines. Flavor Flags The following constants are used to provide additional attribute information about drag item flavors. These constants are used when calling the AddFlavor functions and can be obtained using the GetFlavorFlags function.
______________________________________
#define kFlavorAvailable
1
#define kFlavorSenderOnly
2
#define kFlavorSenderTranslated
4
#define kFlavorTMTranslated
8
______________________________________
Constant Descriptions: kFlavorAvailable--Set if the flavor is available to the receiver of a drag. kFlavorSenderOnly--Set if the flavor is only available to the sender of a drag. The flavor is visible only if the receiver is the same application as the sender. kFlavorSenderTranslated--Set if the flavor data is translated by the sender. This attribute is useful if the receiver needs to determine if the sender is performing its own translation to generate this data type. kFlavorTMTranslated--Set if the flavor data is provided by the Translation Manager. The Translation Manager is a second system service which is called during all drag operations and provides additional flavors and data, if needed, upon the performance of a drop by translating some flavor from the sender to one that the receiver can understand. In short, the Translation Manager adds flavors stored in the drag item and arbitrates between sender and receiver handlers at drop time where the data is translated. So, the sender makes promises about data in the form of flavors and so does the Translation Manager. If a flavor is requested by the receiver that only the Translation Manager can provide, then a translation is performed at drop time, and the receiver is notified when the data is ready to be received. Translation of data is provided in the manner provided in application Ser. No. 07/984,180, which is assigned to the assignee of the present invention. Although that application describes translation of files, the translation of discrete packets of data is performed in a similar manner. If this flavor is requested, the Drag Manager will obtain the required data type from the sender and then it will use the Translation Manager to provide the data that the receiver requested. Drag Attributes The following constants are used to provide additional attribute information about a drag that is in progress. The attribute flags provide information about the window and application that the drag is currently occurring in.
______________________________________
#define kDragHasLeftSourceWindow
1
#define kDragIsInSourceApplication
2
#define kDragIsInSourceWindow
4
______________________________________
Constant Descriptions: kDragHasLeftSourceWindow--Set if the drag has not left the source window since the beginning of the drag. This flag is useful for providing window highlighting after the user has moved the mouse outside of the source window. kDragIsInSourceApplication--Set if the drag is currently in any window that belongs to the application that started the drag. kDragIsInSourceWindow--Set if the drag is currently in the same window that the drag started from. Special Flavor Kinds The following constants are used to identify special flavor kinds that are defined by the Drag Manager.
______________________________________
#define kDragRegionFlavorKind
`drgn`
#define kHFSFlavorKind `hfs`
______________________________________
Constant Descriptions: kDragRegionFlavorKind--The flavor kind for a drag region flavor. The Drag Manager uses drag region flavors to determine the shape of each drag item being dragged. The drag region flavor data is a region in global coordinates of the item being dragged (for example, s used in the Apple brand QuickDraw graphics routines). Drag region flavors are created by calling the AddDragRegionFlavor function. kHFSFlavorKind--The flavor kind for an HFS (Hierarchical Filing System) file system object (e.g., a file being dragged). The Finder uses HFS flavors when dragging file system objects. The HFS flavor data is defined by the HFSFlavor structure defined below. HFS flavors are created by calling the AddHFSFlavor function. Zoom Acceleration The following constants are used when specifying a zoomAcceleration constant to either the ZoomRects or ZoomRegion functions.
______________________________________
#define kZoomNoAccelerate
0
#define kZoomAccelerate
1
#define kZoomDecelerate
2
______________________________________
Constant Descriptions: kZoomNoAccelerate--Linear interpolation is used for each free of animation between the source and destination. kZoomAccelerate--Increment the step size for each frame of animation between the source and destination. This option produces the visual appearance of the animation speeding up as it approaches the destination. kZoomDecelerate--Decrement the step size for each frame of animation between the source and destination. This option produces the visual appearance of the animation slowing down as it approaches the destination. Data Structures This section describes the data structures that are called to identify drags, drag items, drag item flavors and special drag item flavor data by application programs. Drag Reference The Drag Reference is a reference to a drag object. Before calling any other Drag Manager routine, a new Drag Reference must be first created by calling the NewDrag function. The Drag Reference that is returned by NewDrag is used in all subsequent calls to the Drag Manager. The DisposeDrag function is used to dispose of a Drag Reference after it is finished being used. typedef unsigned long DragReference; Drag Item Reference The Drag Item Reference is a reference number used to refer to a single item in a drag. Drag Item Reference numbers are created by the sender application when adding drag item flavor information to a drag. Drag Item Reference numbers are created by and are only be interpreted by the sender application. typedof unsigned long ItemReference; Flavor Type The Flavor Type is a four character type that describes the format of drag item flavor data. The Flavor Type has the same function as a scrap type; it designates the format of the associated data. Any scrap type, resource type or even AppleEvent brand descriptor type may be used. Four character types consisting of only lower-case letters are reserved by Apple. A unique type can be guaranteed by using the registered application signature. typedef ResType FlavorType; HFS Drag Item Flavor Record The Drag Manager defines a special data flavor for dragging file system objects. The HFS (Hierarchical Filing System) drag item flavor is used when dragging documents (e.g., files) and folder (e.g., directory) icons in the Finder. The HFS drag item flavor record is defined by the HFSFlavor data type. An HFS drag item flavor is added to a drag by the sending application program by using the AddHFSFlavor function.
______________________________________
typedef struct HFSFlavor {
OSType fileType; // file type
OSType fileCreator;
// file creator
unsigned short
fdFlags; // Finder flags
FSSpec fileSpec; // file system specification
}HFSFlavor;
______________________________________
Field Descriptions: fileType--The file type of the object. fileCreator--The file creator of the object. fdFlags--The Finder flags of the object (Finder flags are defined in the "Finder Interface" chapter of the publication "Inside Macintosh"). fileSpec--The FSSpec record for the object. Drag Manager Routines This section describes the Drag Manager routines are used to start a drag from an application program, gain control when the user drags an object into one of the application's windows, support the drag and drop user interface and to send and receive data as part of a drop transaction. Installing and Removing Drag Handler Routines The Drag Manager is called to install or remove handler routines for an entire application program or for one of an application program's windows. The Drag Manager provides a pair of install/remove functions for each handler type. InstallTrackingHandler The InstallTrackingHandler function is used to install a tracking handler routine for the Drag Manager to use while the user drags through an application's windows. The tracking handler provides feedback in windows controlled by the application program.
______________________________________
pascal OSErr InstallTrackingHandler
(DragTrackingHandler theTrackingHandler,
WindowPtr theWindow,
unsigned long handlerRefCon);
______________________________________
theTrackingHandler--Pointer to a DragTrackingHandler routine. theWindow--A pointer to the window to install the drag tracking handler for. When the cursor moves into this window during a drag, the Drag Manager sends tracking messages to the application program's handler routine. If this parameter is NIL, the given handler will be installed in the default handler space for the application (the handler is active for all windows in the application). handlerRefCon--A reference constant that will be forwarded to the application program's drag tracking handler routine when it is called by the Drag Manager. The InstallTrackingHandler function installs a tracking handler for one of the application's windows. Installing a tracking handler allows the application to track the user's movements through the application's windows during a drag. More than one drag tracking handler may be installed on a single window. The Drag Manager sequentially calls all of the drag tracking handlers installed on a window when the user moves the cursor over that window during a drag. By specifying a value of NIL in theWindow, the tracking handler is installed in the default handler space for the application. Drag tracking handlers installed in this way are called when the user moves the mouse over any window that belongs to the application. Multiple drag handler routines of the same kind may be installed for the same window to determine if subwindows, etc. may handle the data promised in the drag item(s) and handle highlighting of destinations, such as subwindows, etc., to provide feedback to the user. Each drag handler murine will be called in the chain until a handler handles the requested task.
______________________________________
Result Codes:
______________________________________
noErr 0 No error
paramErr -50 Parameter error
memFullErr -108 Not enough memory
handlerExistsErr
-1860 Handler already exists
______________________________________
InstallReceiveHandler The InstallReceiveHandler function is used to install a receive drop handler routine for the Drag Manager to use when the user releases the mouse button while dragging over one of the application's windows. This routine will allow data to be accepted by the destination application.
______________________________________
pascal OSErr InstallReceiveHandler
(ReceiveDropHandler theReceiveHandler,
WindowPtr theWindow,
unsigned long handleRefCon);
______________________________________
theReceiveHandler--Pointer to a ReceiveDropHandler routine. theWindow--A pointer to the window to install the receive drop handler for. When a drop occurs over (e.g., mouseUp event following a drag) this window, the Drag Manager calls this routine to allow the application to accept the drag. If this parameter is NIL, the given handler will be installed in the default handler space for the application (the handler will be called if a drop occurs in any window in the application). handlerRefCon--A reference constant that will be forwarded to the application program's receive drop handler routine when it is called by the Drag Manager. The InstallReceiveHandler function installs a receive drop handler for one of the application's windows. Installing a receive handler allows the application to accept a drag by getting drag item flavor data from the Drag Manager when the user releases the mouse button while dragging over one of the application's windows. More than one receive drop handler may be installed on a single window. The application program may install multiple drag handler routines of the same kind for the same window to allow multiple subwindows, etc. in the application to receive data. Each drag handler routine in the chain will be called until a handler handles the requested task. The Drag Manager sequentially calls all of the receive drop handlers installed on a window when a drop occurs in that window until a handler handles the requested task. By specifying a value of NIL in theWindow, the receive drop handler is installed in the default handler space for the application. Receive drop handlers installed in this way are called when a drop occurs in any window that belongs to the application.
______________________________________
Result Codes:
______________________________________
noErr 0 No error
paramErr -50 Parameter error
memFullErr -108 Not enough memory
handlerExistsErr
-1860 Handler already exists
______________________________________
InstallConstrainHandler The InstallConstrainHandler function is used to install a constrain mouse handler routine for the Drag Manager to use when the user releases the mouse button while dragging over one of the application's windows.
______________________________________
pascal OSErr InstallConstrainHandler
(DragConstrainHandler theConstrainHandler,
WindowPtr theWindow,
unsigned long handlerRefCon);
______________________________________
theConstrainHandler--Pointer to a DragConstrainHandler routine. theWindow--A pointer to the window to install the constrain mouse handler for. When the cursor is over this window, the Drag Manager calls this routine to allow the mouse coordinates to be constrained by the application. If this parameter is NIL, the given handler will be installed in the default handler space for the application (the handler will be called for all windows in the application). handlerRefCon--A reference constant that will be forwarded to the application program's constrain mouse handler routine when it is called by the Drag Manager. The InstallConstrainHandler function installs a constrain mouse handler for one of the application's windows. Installing a constrain mouse handler allows the application to constrain the dragging movement to any degree of freedom that a user chooses (such as horizontal, vertical or grid movement). More than one constrain mouse handler may be installed on a single window. The Drag Manager sequentially calls all of the constrain mouse handlers installed on a window when the user moves the cursor over that window during a drag. By specifying a value of NIL in theWindow, the constrain mouse handler is installed in the default handler space for the application. Constrain mouse handlers installed in this way are called when the user moves the mouse over any window that belongs to the application.
______________________________________
Result Codes:
______________________________________
noErr 0 No error
paramErr -50 Parameter error
memFullErr -108 Not enough memory
handlerExistsErr
-1860 Handler already exists
______________________________________
Remove TrackingHandler The RemoveTrackingHandler function is used to remove a tracking handler routine from one of the application's windows.
______________________________________
pascal OSErr RemoveTrackingHandler
(DragTrackingHandler theTrackingHandler,
WindowPtr theWindow),
______________________________________
theTrackingHandler--Pointer to a DragTrackingHandler routine. theWindow--A pointer to the window to remove the drag tracking handler from. If this parameter is NIL, the given handler will be removed from the default handler space for the application. The RemoveTrackingHandler function removes a drag tracking handler from one of the application's windows. By specifying a value of NIL in theWindow, the tracking handler is removed from the default handler space for the application (e.g., the chain).
______________________________________
Result Codes:
______________________________________
noErr 0 No error
paramErr -50 Parameter error
memFullErr -108 Not enough memory
handlerNotFoundErr
-1861 Drag handler could not be found
______________________________________
RemoveReceiveHandler The RemoveReceiveHandler function is used to remove a receive drop handler routine from one of the application's windows.
______________________________________
pascal OSErr RemoveReceiveHandler
(ReceiveDropHandler theReceiveHandler,
WindowPtr theWindow);
______________________________________
theReceiveHandler--Pointer to a ReceiveDropHandler routine. theWindow--A pointer to the window to remove the receive drop handler from. If this parameter is NIL, the given handler will be removed from the default handler space for the application. The RemoveReceiveHandler function removes a receive drop handler from one of the application's windows. By specifying a value of NIL in theWindow, the receive drop handler is removed from the default handler space for the application.
______________________________________
Result Codes:
______________________________________
noErr 0 No error
paramErr -50 Parameter error
memFullErr -108 Not enough memory
handlerNotFoundErr
-1861 Drag handler could not be found
______________________________________
RemoveConstrainHandler The RemoveConstrainHandler function is used to remove a constrain mouse handler routine from one of the application's windows.
______________________________________
pascal OSErr RemoveConstrainHandler
(DragConstrainHandler theConstrainHandler,
WindowPtr theWindow);
______________________________________
theConstrainHandler--Pointer to a DragConstrainHandler routine. theWindow--A pointer to the window to remove the constrain mouse handler from. If this parameter is NIL, the given handler will be removed from the default handler space for the application. The RemoveConstrainHandler function removes a constrain mouse handler from one of the application's windows. By specifying a value of NIL in theWindow, the constrain mouse handler is removed from the default handler space for the application.
______________________________________
Result Codes:
______________________________________
noErr 0 No error
paramErr -50 Parameter error
memFullErr -108 Not enough memory
handlerNotFoundErr
-1861 Drag handler could not be found
______________________________________
Creating and Disposing of Drag References A drag reference is created whenever an application wishes to start a drag. The drag reference is a token that used in all subsequent calls to Drag Manager routines to refer to a particular drag. NewDrag The NewDrag function is used to create a new drag reference token. pascal OSErr NewDrag (DragReference *theDragRef, unsigned long senderRefCon); theDragRef--The drag reference, which NewDrag fills in before returning. senderRefCon--A reference constant that will be forwarded to an application program's drag handler routines when they are called by the Drag Manager. This constant is used to pass any data that is wished to be forwarded to the application program's handler routines. The NewDrag function allocates a drag object in the Drag Manager and returns a drag reference token in the theDrag parameter. This drag reference is used in subsequent calls to the Drag Manager to identify the drag. This drag reference is required when adding drag item flavors and calling TrackDrag. All of the application program's installed drag handlers receive this drag reference so other Drag Manager routines can be called within the application program's drag handlers.
______________________________________
Result Codes:
______________________________________
noErr 0 No error
paramErr -50 Parameter error
memFullErr -108 Not enough memory
______________________________________
DisposeDrag The DisposeDrag function is used to dispose of a drag reference token and its associated data when a drag has been completed or if the drag is no longer needed. pascal OSErr DisposeDrag (DragReference theDragRef); theDragRef--The drag reference of the drag object to dispose of. The DisposeDrag function disposes of the drag object that is identified by the given drag reference token. If the drag reference contains drag item flavors, the memory associated with the drag item flavors is disposed of as well. DisposeDrag should be called after a drag has been performed using TrackDrag or if a drag reference was created but is no longer needed.
______________________________________
Result Codes:
______________________________________
noErr 0 No error
paramErr -50 Parameter error
badDragRefErr -1851 Unknown drag reference
dragInUseErr -1853 Drag reference is in use
______________________________________
Providing Drag Callback Procedures Drag callback procedures are provided to the Drag Manager when a user wants to override the default behavior of the Drag Manager. A user can override the mechanisms in the Drag Manager that provide data to a drop receiver, that samples the mouse and keyboard and that draws the standard "dotted outline" drag feedback. SetDragSendProc The SetDragSendProc function is used to set the send data procedure for the Drag Manager to use with a particular drag.
______________________________________
pascal OSErr SetDragSendProc
(DragReference theDragRef,
DragSendDataProc
theSendProc,
unsigned long theRefCon);
______________________________________
theDragRef--The drag reference that SetDragSendProc will set the drag send procedure for. theSendProc--The send data routine that will be called by the Drag Manager when the receiver of a drop requests the flavor data of a flavor that has not been cached by the Drag Manager. theRefCon--A reference constant that will be forwarded to the application program's drag send procedure when it is called by the Drag Manager. This constant is used to pass any data that is wished to be forwarded to the application program's drag send procedure. | ||||||