Microsoft SDK for Java

Performing Clipboard and Drag-and-Drop Operations

The drag-and-drop feature in WFC is based on the Win32 (OLE) model, which implements a shortcut for copying and pasting data. When you use the Clipboard, you must perform several steps involving selecting the data, choosing Cut or Copy from the context menu, moving to the destination file, window, or application, and choosing Paste from the context menu. (The origin of the data is called the source and the destination is called the target.)

The drag-and-drop feature removes the necessity of using the context menu. Instead, it uses the action of pressing the left mouse button to capture the selected data in the source and releasing the button in the target to drop it. Drag-and-drop operations can transfer any data that can be placed on the Clipboard; consequently, the data formats for drag and drop are the same as those of the Clipboard. Data formats specify, for example, whether the data is text, bitmap, HTML, .wav, and so on. The com.ms.wfc.app.DataFormats class contains fields pertaining to each of the Clipboard formats. These field names (such as CF_TEXT) originate directly from the Win32 constant names.

The data for Clipboard and drag-and-drop operations is stored in a com.ms.wfc.app class called DataObject, which implements the IDataObject interface. IDataObject defines methods for setting and retrieving the data, getting a list of data formats in the data object, and querying for the existence a specific data format.

To programmatically place data on and retrieve it from the Clipboard, use the static methods in com.ms.wfc.app.Clipboard. Clipboard.setDataObject takes an IDataObject and places it on the Windows Clipboard; Clipboard.getDataObject returns an IDataObject from the Clipboard. The target must ensure that the data format on the Clipboard is one that it can use. To do this, it should query the data object with the IDataObject.getDataPresent method, passing it a data format that it can accept; getDataPresent returns true if this type of data is present.

Implementing a Drop Source

For any WFC control component (based on com.ms.wfc.ui.Control), the Control.doDragDrop method is called to start the operation. This is typically done in response to the user's moving the mouse with the left button pressed. Therefore, the code is placed in a mouseMove event handler where the MouseEvent object is checked to see if the left button is down, indicating the start of a drag operation. For example, the following code is an event handler for a list box control containing filenames.

Example

   private void listFiles_mouseMove(Object source, MouseEvent e)
   {
      //If the left button is down, do the drag/drop.
      if(this.getMouseButtons()==MouseButton.LEFT)
      {
         String data = (String)listFiles.getSelectedItem();
         listFiles.doDragDrop( data, DragDropEffect.ALL);
      }                      
   }
 

The doDragDrop method takes the data to be transferred and a com.ms.wfc.ui.DragDropEffect object. The DragDropEffect class contains the following constants that can be combined using the bitwise OR for the intended mode of the drag-and-drop operation.

DragDropEffect Method Description
COPY Specifies that data will not be removed from the source after the transfer.
MOVE Specifies that data will be removed from the source after the transfer.
SCROLL Specifies that data will be scrolled in the target after the transfer.
ALL Specifies that data will be removed from the source after the transfer and scrolled into the target (essentially COPY | MOVE | SCROLL).
NONE Specifies that no operation is performed.

The target that receives the data in the drag-drop operation receives the dragDrop event, which contains this DragDropEffect object, so it can easily determine the intent of the operation.

Implementing a Drop Target

The drop part of the drag-and-drop operation is handled as an event. The Control class provides the event handler infrastructure for these drag-and-drop events: dragDrop, dragEnter, dragLeave, and dragOver. You can use the following methods to specify handlers for these events.

Control Method Description
addOnDragDrop Specifies a handler for data that is dropped into your control or window (when the left mouse button is released).
addOnDragEnter Specifies a handler for drop data as the cursor first enters the window.
addOnDragLeave Specifies a handler for drop data as the cursor leaves the window.
addOnDragOver Specifies a handler for drop data as the cursor is dragged across the window.

All these addOn methods have reciprocal removeOn methods to remove the event handler. As with all event handler addOn and removeOn methods in WFC, these methods take a delegate (in this case, DragEventHandler) that is created with the name of your handler method. For example, the following line adds the txtFile_dragDrop method as a dragDrop event handler:

txtFile.addOnDragDrop(new DragEventHandler(this.txtFile_dragDrop));

Of all the drag-and-drop events, the dragDrop event is the most commonly handled. Regardless of which of these events is handled, the code in the handler must do at least three things. It must first determine if it can accept the data format, and if so, it must then copy the data and optionally display it (or provide some user interface feedback that the data was dropped).

All data and information is passed in the DragEvent event. This contains, among other fields, a data field and an effect field. The DragEvent.data field contains an object that supports IDataObject that has methods to retrieve the data and the data formats to query for the existence of a specific format. Therefore, the handler must first call DragEvent.data.getDataPresent method with a format it will accept, and then determine whether it holds that data type. If so, it can then call the DragEvent.data.getData method (passing in that data type) and retrieve the data. How the data is displayed is determined by that control. The following example illustrates an edit control dragDrop event handler that displays text data dropped to it.

Example

    private void txtFile_dragDrop(Object source, DragEvent e)
   {
      // If text is in the object, write it into the edit control.
      if (e.data.getDataPresent(DataFormats.CF_TEXT))
      {
         String filename=(String)e.data.getData(DataFormats.CF_TEXT);
         txtFile.setText(filename);
      }
   }

© 1999 Microsoft Corporation. All rights reserved. Terms of use.