Inside Macintosh: Programmer's Guide to MacApp / Part 1 - MacApp Theory and Architecture

Chapter 9 - Drag and Drop

Performing a Drag Operation

This section describes how the objects in the MacApp application DemoDialogs work together with the Macintosh Drag Manager to perform a drag operation. The discussion refers to the steps of a drag operation--those steps are shown in Figure 9-2 and Figure 9-3.

Setting the Drag Cursor

When a user moves the cursor over a view, MacApp calls the view's DoSetDragCursor method. The DoSetDragCursor method calls two other view methods to determine whether a mouse click would initiate a drag: DoMakeDragCursorRegion and WillDrag.

The TView::DoMakeDragCursorRegion method creates a region to describe the specific portion of the view's content that is draggable. Draggable content is often the area within the view that the user perceives as selected, such as highlighted cells in a grid view or selected text in a text view. In the TView class, DoMakeDragCursorRegion calls DoMakeDropHiliteRegion, which creates a region that matches the view's extent. Your application can override DoMakeDragCursorRegion or DoMakeDropHiliteRegion to supply a specialized drag cursor region. See MacApp's TEditText class for an example of overriding DoMakeDropHiliteRegion.

The TView::WillDrag method checks whether the fDraggable field is set to TRUE and the cursor is currently over the draggable region. The WillDrag method of subclasses of TView may check for additional conditions. For example, TTEView::WillDrag returns TRUE only if TView::WillDrag returns TRUE and the Shift key is not pressed. Dragging while the Shift key is pressed is used to select additional text rather than to initiate a drag operation.

If WillDrag returns TRUE, the DoSetDragCursor method calls the GetWillDragCursorID method. In TView, GetWillDragCursorID returns the resource ID for an open-hand image--an image appropriate for dragging data such as a picture. In both the TTEView and TEditText view classes, GetWillDragCursorID returns the kNoResource ID constant. This results in the display of an arrow cursor--an image appropriate for dragging text.

You can override GetWillDragCursorID to supply a special cursor ID resource for your view. The cursor you display should alert the user to the possibility of initiating a drag operation. Step 2 in Figure 9-2 shows an arrow cursor image over draggable text.

Performing a Drag

When a user clicks the mouse with the cursor image over a view, MacApp calls the view's HandleMouseDown method. To determine whether the click can initiate a drag, the HandleMouseDown method calls the same view methods DoSetDragCursor did: DoMakeDragCursorRegion and WillDrag.

Figure 9-2 Dragging and dropping text in the DemoDialogs application (steps 1-3)

Figure 9-3 Dragging and dropping text in the DemoDialogs application (steps 4-6)

If WillDrag returns TRUE, HandleMouseDown calls the GetIsDraggingCursorID method. In TView, GetIsDraggingCursorID returns the resource ID for a closed-hand image--an image appropriate for dragging data such as a picture. In both the TTEView and TEditText view classes, GetIsDraggingCursorID returns the kNoResource ID constant. This results in the display of an arrow cursor--an image appropriate for dragging text.

You can override GetIsDraggingCursorID to supply a special cursor ID resource for your view. Step 3 in Figure 9-2 shows an arrow cursor image as a user starts an operation to drag text.

After setting the cursor based on the supplied cursor ID, HandleMouseDown calls the view's HandleDrag method to prepare data and initiate a drag operation. The TView::HandleDrag method is not intended to be overridden and is consequently not declared as virtual.

Note

To provide flexibility, HandleMouseDown calls the DoGetDragProxy method, then calls the HandleDrag method of the returned object. For the TView class, DoGetDragProxy returns a reference to the view itself, but you can override DoGetDragProxy and provide a different object to handle the drag operation.

For example, the TDialogTEView class overrides DoGetDragProxy and returns a reference to its associated TEditText object, which then handles the drag.

The TView::HandleDrag method first calls the global drag session object's ClearDrag method to dispose of any previous drag operation. It then calls two view methods, DoAddDragContent and DoMakeDragOutlineRegion. These methods are described in the following sections.

Supplying Drag Data

The TView::DoAddDragContent method creates drag items to represent the data being dragged and installs the drag items into the drag session. The DoAddDragContent method calls the drag session object's AddDragItem method once for each item it adds to the drag. AddDragItem returns a pointer to a new TDragItem object. DoAddDragContent then calls TDragItem->AddFlavor once for each flavor it can supply for that data type. For example, a view might call AddFlavor for PICT, GIF, JPEG, QuickTime, and other flavors. Instead of AddFlavor, it may call TDragItem->PromiseFlavor to promise data that will only be delivered if requested. For information on the advantages of promising data, see "Promising Data" on page 267.

Supplying a Drag Outline Region

The TView::DoMakeDragOutlineRegion method creates and returns an outline region that represents the item or items to be dragged. The TView class implementation of DoMakeDragOutlineRegion calls the view's DoMakeDragCursorRegion method, which calls the DoMakeDropHiliteRegion method. In TView, DoMakeDropHiliteRegion provides the view's visible extent as a default region. If this doesn't work for your view, you can override any of these methods (DoMakeDragOutlineRegion, DoMakeDragCursorRegion, or DoMakeDropHiliteRegion).

Step 4 in Figure 9-3 shows the outline region for a dragged text selection.

Starting the Drag Session

Once the view's HandleDrag method has supplied data and an outline for the drag session, it calls the global drag session object's StartDrag method to initiate the drag session. The StartDrag method calls the Drag Manager routine TrackDrag to initiate the drag session and calls its own ClearDrag method to dispose of the session once it is completed.