Use drag-and-drop and clipboard to transfer Shell Objects

Msdn 2005-> Win32 and COM development-> User Interface-> Windows User Experience-> Windows Shell-> shell programmer's Guide-> shell basics-> transferring Shell objects with drag-and-drop and the clipboard

Many applications allow users to transfer data to other programs by dragging the mouse or using the clipboard. Shell objects such as files and folders are one of the many data types that can be transferred. Shell data transmission can occur between two applications, or between the application and the desktop or the resource manager.

Although the most frequently transmitted shell object is a file, any object in the shell namespace can be transmitted. For example, a program may need to transfer files to a virtual folder like the recycle bin, or accept objects from non-Microsoft namespace extensions. To implement namespace extension, you must make it the correct behavior as a drag-and-drop source and a drag-and-drop target.

This article discusses how to use drag and drop and clipboard to transfer Shell objects.

How is a shell object dragged and dropped?

Applications usually provide users with methods to transmit shell data. For example:

• Drag a file from the desktop or resource manager and place it in the application.
• Copy the file to the clipboard in resource manager and paste it to the application.
• Drag a file from the application and place it in the recycle bin.

For a detailed discussion of how to handle these and other situations, seeHandling shell data transfer scenariosIt discusses the general principle of shell data transmission.

Windows provides two standard methods for applications to transmit shell data:

• You can cut or copy shell data, such as one or more files, to the clipboard, and other applications obtain data from the clipboard.
• Drag an icon representing data from the source application and place it in the target window.

In both cases, the data to be transmitted is included in the data object. The data object is exposed.IdataobjectThe COM Object of the API. Generally, all shell data transmission must follow three necessary steps:

• Create a data object for the data to be transmitted from the transmission source
• TheIdataobjectInterface pointer
• Transfer target callIdataobjectInterface method to obtain data

The main difference between clipboard and drag-and-drop data transmission is thatIdataobjectHow to pass the pointer from the source to the target.

Clipboard data transmission

The clipboard is the simplest way to transmit shell data. The basic transfer process is similar to that of the standard clipboard. However, because the data object pointer instead of the data itself is transmitted, you must use the OLE clipboard API instead of the standard clipboard API. The basic process of using the OLE clipboard API to transmit shell data is as follows:

• Create a data object containing data from the transmission source
• Transfer source callOlesetclipboardPut the Data ObjectIdataobjectPointer to clipboard
• Transfer target callOlegetclipboardTheIdataobjectPointer
• Transfer target callIdataobject: getdataMethod to obtain data
• Certain shell data transmission targets must be calledIdataobject: setdataThe method provides feedback on data transmission results for data objects. For an example of this operation, seeHandling optimized move operations.

Drag and Drop Data Transmission

Although it is more complicated than Clipboard data transmission, drag-and-drop data transmission has the following advantages:

• Drag-and-drop data transmission can be completed with a simple mouse movement, which is more flexible and intuitive than clipboard operations.
• Drag and Drop provides users with a visual representation of operations. You can track the process of moving an icon from the source to the target.
• Drag and Drop will notify the drag and drop target when data is available

Drag and Drop Operations also use data objects to transmit data. However, the placement source must provide more functions than the clipboard transmission needs:

• Place source must create exposureIdropsourceInterface object. Unified operationIdropsourceCommunicates with the drag-and-drop source.
• Drag and Drop data objects are responsible for tracking the movement of the cursor and displaying icons representing the Data Objects

The placement destination must also provide more functions than are required to process clipboard transfers:

• The placement target must be exposed.IdroptargetInterface. The system usesIdroptargetProvide information such as the cursor position for the target, and notify the target when data is released.
• Drag and Drop targets must be calledRegisterdragdropRegister with the system. This function provides the system with a pointer to the destination window handle and the idroptarget interface of the target application.

Note: For drag-and-drop operations, the program must useOleinitializeInitialize com insteadCoinitialize.

The following are typical steps for Shell Data Transmission Using drag and drop:

1. Drag and Drop target callRegisterdragdropProvide the systemIdroptargetAnd register a window as the drag-and-drop target.
2. When you start the drag-and-drop operation, drag and drop the source to create a data object and callDodragdropInitiate a drag loop.
3. When the cursor is located on the target window, the system callsIdroptargetInterface Method notification target. When the cursor enters the target window, the system callsIdroptarget: dragenterWhen the cursor slides over the target window, the system callsIdroptarget: dragover. Both methods provide the cursor position, Ctrl, ALT, and other keyboard modifier key status information for the placement target. When the cursor leaves the target window, the system passes throughIdroptarget: dragleaveNotification target. After these methods are returned, the system callsIdropsourceThe interface passes the return value to the drag-and-drop source.
4. When the user releases the mouse button and places data, the system calls the targetIdroptarget: DropMethod, one of which is the data object'sIdataobjectInterface pointer.
5. TheIdataobject: getdataMethod to retrieve data.
6. For some types of shell data transmission, the target should also callIdataobject: setdataThe method provides data transmission feedback for the transmission source.
7. After the data object operation is completedIdroptarget: DropAnd then the systemDodrogdropMethod returned to notify the transmission source that the transfer is complete.
8. For some data transmission situations, the transmission source may needDodragdropThe Return Value of the method, as well as the value of the data object that the transmission target passes to, to perform additional actions. For example, if a file is moved, the drag-and-drop source must check the two values to determine whether to delete the original file.
9. The data object is released from the transmission source.

The above process is a general model of shell data transmission. However, shell data objects can contain different types of data, and applications may need to process different types of data transmission. For each data type and transmission condition, the three key steps in the above process must be processed differently:

• How to construct a data object containing shell data from the transmission source
• How to retrieve shell data from Data Objects
• How to transmit data from a transmission source

Shell Data ObjectIt provides a general discussion on how to construct shell data objects from the transmission source, and also discusses how the transmission target processes data objects.Handling shell data transfer scenariosIt discusses in detail how to handle various types of common shell data transmission.