Last edit: 98-06-27 Graham Wideman

Delphi

Introduction

The following discussion uses a UML-style sequence diagram.  If you are not familiar with these diagrams, a brief intro follows at the end.

Initialization and Finalization

Here numerous participants are shown (in preparation for the drag sequence), but only a couple need attention for initialization and finalization.  To participate in OLE, both source and target applications have to call OleInitialize, and on shutdown must call OleUnInitialize (which app calls first is unimportant).

To receive OLE drops, the target application must create an IDropTarget object, lock it and call RegisterDragDrop. RegisterDragDrop requires an HWnd parameter that tells which "window" should be regarded as a drop target.  Recall that in Windows programming a "window" is an object that Windows has been engaged to provide services to (screen management, event notifications etc) and in the Delphi context includes any object derived from TWinControl (not just an entire TForm).

Later, probably on shutting the window that it pertains to, that IDropTarget object must be destroyed but only after we dissociate it from the system by calling RevokeDragDrop and unlocking it. 

(Note that revoking and unlocking will decrement the RefCount to zero, whereupon COM will call the object's destructor automatically.  This means that we have to think about how to destroy the object carefully, in particular we can't just call revoke/unlock willy nilly in the destructor. More on this in the description of the code.)

A Typical Drag-and-Drop Sequence

You might like to print the diagram below it so you can view it more easily while reading the description..

When the user initiates a drag operation, the source app creates two objects:

• IDropSource object which has functions to control the user interface during drag) and
• IDataSource object which has functions to provide access to data, and information about the data.

The source app then passes those two objects to the system with a call to DoDragDrop, and then the system takes over control.

At some point, the user passes the cursor over the drop area on an application that has registered an IDropTarget object. When that happens, the system calls IDropTarget.DragEnter, with position info and the IDataObject.  The drop target must decide whether it's willing to accept a drop, generally taking a look at the data formats by:

• IDataObject.QueryGetData: to ask about a specific data format.
• IDataObject.EnumFormatEtc: to get a list of formats that the DataObject can provide.

While the user continues to drag, the system loops through IDropTarget and IDropSource functions, giving target and source applications a chance to respond to mouse movements, key and mouse-button changes, and to provide user feedback. The source app controls the mouse cursor, while the target app controls hit feedback in the target window, like highlighting the target area. In addition, the IDropTarget functions return to the system an indication of what "effect" a drop will have (copy, move, none) according to the shift/ctrl keys that the user is pressing.

If the user ultimately doesn't drop in the target area, then that's all that happens.   But if the user does drop in the target area, then the system informs the target app with the IDropTarget.Drop function, again passing the IDataObject. The target app immediately uses that to request the data in a particular format, which IDataObject retrieves from the source app, packaged in a "storage medium" (TStgMedium) form.

A TStgMedium is actually a small structure that indicates the location of the data (eg: chunk of global memory, a file etc) and includes a pointer or reference to the actual data.  The application may do something with the data immediately (eg: pasting it into a document), or at its leisure.

COM Object Cleanup

Several COM objects are or may be created just for this transaction, to be passed from source app to system to target app:: IDropSource, IDataObject, and IEnumFormatEtc. Each is a COM object, and will live as long as there is a reference to it. To put it another way, the system will take care of deleting the objects (avoiding a memory leak) when there are no further references. In a Delphi app this means when the interface references go out of scope or are assigned another value (or nil). (This is demonstrated in the GWDropDemo app.)

The TStgMedium is not a COM object, and the target app has the responsibility of explicitly freeing it.

Requirements for Drop-Accepting App

As the above description indicates, the main requirement for an OLE drop-accepting app is to implement the IDropTarget object, to respond sensibly to the drag events, and to do something useful with the data when it's received. This latter will typically involve incorporating the dropped data into the target app's existing data, and updating the target app's user-interface view of the data.

Diagram Conventions

The diagrams in this article follow Unified Modeling Language conventions (which are somewhat loose depending on the drawing tool available, I used Visio).  Of the several UML diagram types, the ones above are "sequence diagrams", which works as follows:

• The participants are arrayed across the page left to right.
• Time flows downwards.
• Arrows are used to indicate one object "sending a message to" (usually means "calling") another. If there is only one thread of execution this call also transfers control. 
• I've used a thin vertical line as a sight guide for each object, a thick vertical line to indicate that the object exists, and an "X" to indicate that the object is deleted. 
• A rectangular box indicates that the object is active (ie: one of the object's functions has control).  In this notation, a caller continues to have a box while control is actually passed to a callee (control is nested.)
• The return from the call may be indicated explicitly with a return arrow, or implicitly as I have shown it... it just happens at the end of the box.
• UML defines some fancy notation for conditional paths, and for looping. I've fudged on these.

For more info, visit Rational Software Corporation.

Go to:  Drop Demo Intro Page, or