The following code shows one of the simplest examples possible that contains both a drag source and a drop target. To build this example, start a new projectand add two Label controls named lblDragSource and lblDropTarget.

Public Class Form1
    ' Start a drag.
    Private Sub lblDragSource_MouseDown() Handles lblDragSource.MouseDown
        lblDragSource.DoDragDrop("Here's the drag data!",
            DragDropEffects.Copy)
    End Sub

    ' Make sure the drag is coming from lblDragSource.
    Private Sub lblDropTarget_DragEnter(ByVal sender As Object,

ByVal e As System.Windows.Forms.DragEventArgs) _
     Handles lblDropTarget.DragEnter
        e.Effect = DragDropEffects.Copy
    End Sub

    ' Display the dropped data.
    Private Sub lblDropTarget_DragDrop(ByVal sender As Object,
     ByVal e As System.Windows.Forms.DragEventArgs) _
     Handles lblDropTarget.DragDrop
        MessageBox.Show(e.Data.GetData("Text").ToString)
    End Sub
End Class
                                                  

Note that the lblDropTarget control must have its AllowDrop property set to True either at design time or at runtime or it will not receive any drag-and-drop events. When the user presses a mouse button down over the lblDragSource control, the MouseDown event handler calls that control's DoDragDrop method, passing it the text ("Here's the drag data!") and indicating that it wants to perform a Copy. When the user drags the data over the lblDropTarget control, its DragEnter event handler executes. The event handler sets the routine's e.Effect value to indicate that the control will allow a Copy operation. If the user drops the data over thelblDropTarget control, its DragDrop event handler executes. This routine uses the e.Data.GetData method to get a text data value and displays it in a message box.

Example program LabelDrag uses this code to demonstrate a simple drag-and-drop operation.

As it is, this program lets you drag and drop data from the lblDragSource control to the lblDropTarget control. You can also drag data from the lblDragSourcecontrol into Word, WordPad, and any other application that can accept a drop of text data.

Similarly, the lblDropTarget control can act as a drop target for any application that provides drag sources. For example, if you open WordPad, enter some text, select it, and then click and drag it onto the lblDropTarget control, the application will display the text you dropped in a message box.

This example is a bit too simple to be really useful. If the drop target does nothing more, it should check the data it will receive and ensure that it is text. When you drag a file from Windows Explorer and drop it onto the lblDropTarget control, the e.Data.GetData method returns Nothing so the program cannot display its value. Because the program cannot display a file, it is misleading for the lblDropTarget control to display a Copy cursor when the user drags a file over it.

Example program LabelDrag2 uses the following code to make drag-and-drop a bit safer. The new lblDropTarget_DragEnter event handler uses the e.Data.GetDataPresent method to see if the data being dragged has a textual format. If a text format is available, the control allows a Copy operation. If the data does not come in a textual form, the control doesn't allow a drop.

' Make sure the drag is coming from lblDragSource.
Private Sub lblDropTarget_DragEnter(ByVal sender As Object,
 ByVal e As System.Windows.Forms.DragEventArgs) Handles lblDropTarget.DragEnter
    ' See if the drag data includes text.
    If e.Data.GetDataPresent("Text") Then
        e.Effect = DragDropEffects.Copy
    Else
        e.Effect = DragDropEffects.None
    End If
End Sub
                                                  

Now, if you drag a file from Windows Explorer onto lblDropTarget, the control displays a no drop icon.

The lblDropTarget_DragDrop event handler doesn't need to change because Visual Basic doesn't raise the event if the control does not allow any drop operation. For example, if the user drags a file from Windows Explorer onto lblDropTarget, that control's DragEnter event handler sets e.Effect to DragDropEffects.None, so Visual Basic doesn't raise the DragDrop event handler if the user drops the file there.

Example program DragBetweenListBoxes, which is also available for download, provides a more complete example than program LabelDrag2 and demonstrates many of the drag-and-drop events. It allows the user to drag items between two ListBoxes. It also allows the user to drag an item to a specific position in its new ListBoxand to drag an item from one position to another within the same ListBox.

Example program DragBetweenListBoxes2, which is also available for download, adds the ability to make copies of items. If the user holds down the Ctrl key while dragging an item, the program displays a plus sign drag icon to indicate that dropping the item will make a copy. If the user drops the item while pressing the Ctrl key, the program copies the item and leaves the original item where it started.

When the user drags data over a drop target, the target's DragEnter event handler decides which kinds of drop to allow. The event handler can use the e.GetDataPresent method to see whether the data is available in a particular format and then decide whether it should allow a drop accordingly.

GetDataPresent takes as a parameter a string giving the desired data type. An optional second parameter indicates whether the program will accept another format if the system can derive it from the original format. For example, the system can convert Text data into System.String data so you can decide whether to allow the system to make this conversion.

The DataFormats class provides standardized string values specifying various data types. For example, DataFormats.Text returns the string Text representing the text data type.

If you use a DataFormats value, you don't need to worry about misspelling one of these formats. Some of the most commonly used DataFormats include Bitmap, Html, StringFormat, and Text. See the online help for other formats. The web page msdn2.microsoft.com//system.windows.forms.dataformats_members.aspx lists the DataFormats class's supported formats.

GetDataPresent can also take as a parameter a data type. For example, the following code fragment uses GetDataPresent to allow a Copy operation if the drag data contains an Employee object:

if e.Data.GetDataPresent(GetType(Employee)) Then
    ' Allow Copy.
    e.Effect = DragDropEffects.Copy
Else
    ' Allow no other drops.
    e.Effect = DragDropEffects.None
End if

In addition to GetDataPresent, you can use the e.Data.GetFormats method to get an array of strings giving the names of the available formats. The following code shows how a program can list the formats available. It clears its 1stWithoutConversion ListBox and then loops through the values returned by e.Data.GetFormats, adding them to the ListBox. It passes GetFormats the parameter False to indicate that it should return only data formats that are directly available, not those that can be derived from others. The program then repeats these steps, this time passing GetFormats the parameter True to include derived formats.

Private Sub lblDropTarget_DragEnter(ByVal sender As Object,
 ByVal e As System.Windows.Forms.DragEventArgs) Handles lblDropTarget.DragEnter
    lstWithoutConversion.Items.Clear()
    For Each fmt As String In e.Data.GetFormats(False)
        lstWithoutConversion.Items.Add(fmt)
    Next fmt

    lstWithConversion.Items.Clear()
    For Each fmt As String In e.Data.GetFormats(True)
        lstWithConversion.Items.Add(fmt)
    Next fmt
End Sub

Sometimes, you may want a drop target to accept only data dragged from within the same application. The following code shows one way to handle this. Before it calls DoDragDrop, the program sets its m_Dragging variable to True. The lblDropTarget control's DragEnter event checks m_Dragging. If the user drags data from a program other than this one, m_Dragging will be False and the program sets e.Effect to DragDropEffects.None, prohibiting a drop. If m_Dragging is True, that means this program started the drag, so the program allows a Copy operation. After the drag and drop finishes, the lblDragSource control's MouseDown event handler sets m_Dragging to False, so the drop target will refuse future drags from other applications.

Public Class Form1
    ' True while we are dragging.
    Private m_Dragging As Boolean

    ' Start a drag.
    Private Sub lblDragSource_MouseDown() _
     Handles lblDragSource.MouseDown
        m_Dragging = True
        lblDragSource.DoDragDrop("Some text", DragDropEffects.Copy)
        m_Dragging = False
    End Sub
    ' Only allow Copy if we are dragging.
    Private Sub lblDropTarget_DragEnter(ByVal sender As Object,
     ByVal e As System.Windows.Forms.DragEventArgs) _
     Handles lblDropTarget.DragEnter
        If m_Dragging Then
            e.Effect = DragDropEffects.Copy
        Else
            e.Effect = DragDropEffects.None
        End If
    End Sub

    ' Display the dropped text.
    Private Sub lblDropTarget_DragDrop(ByVal sender As Object,
    ByVal e As System.Windows.Forms.DragEventArgs) _
    Handles lblDropTarget.DragDrop
      MessageBox.Show(e.Data.GetData(DataFormats.Text).ToString)
    End Sub
End Class
                                                  

Example program DragWithinApp uses this code to provide restricted drag-and-drop.

There is no easy way to allow your program to drag data to its own controls, but not allow it to drag data to another program. The philosophy is that a drag sourceprovides data for any application that can handle it, not just for its own use.

If you don't want other applications to read data dragged from your application, you can package the data in an object and drag the object as described in the section "Dragging Serializable Objects" later in this chapter. This will make it very difficult for most applications to understand the data, even if they try to accept it.

Many applications let you drop files onto them. When you drag files over a drop target, the data object contains data of several types, including FileDrop. This data is an array of strings containing the names of the files being dragged.

Example program AcceptDroppedFiles uses the following code to process files dragged onto it. The lblDropTarget control's DragEnter event handler uses the GetDataPresent method to see if the drag contains FileDrop data, and allows the Copy operation if it does. The control's DragDrop event handler uses GetData to get the data in FileDrop format. It converts the data from a generic object into an array of strings, and then loops through the entries, adding each to the 1stFiles ListBox.

Public Class Form1
    ' Allow Copy if there is FileDrop data.
    Private Sub lblDropTarget_DragEnter(ByVal sender As Object,
     ByVal e As System.Windows.Forms.DragEventArgs) _
     Handles lblDropTarget.DragEnter
        If e.Data.GetDataPresent(DataFormats.FileDrop) Then
            e.Effect = DragDropEffects.Copy
        Else
            e.Effect = DragDropEffects.None
        End If
    End Sub

    ' Display the dropped file names.
    Private Sub lblDropTarget_DragDrop(ByVal sender As Object,
     ByVal e As System.Windows.Forms.DragEventArgs) _
     Handles lblDropTarget.DragDrop
        lstFiles.Items.Clear()
        Dim file_names As String() =
            DirectCast(e.Data.GetData(DataFormats.FileDrop), String())
        For Each file_name As String In file_names
            lstFiles.Items.Add(file_name)
        Next file_name
    End Sub
End Class
                                                  

A more realistic application would do something more useful than simply listing the files. For example, it might delete them, move them into the wastebasket, copy them to a backup directory, display thumbnails of image files, and so forth.

Dragging text is simple enough. Simply pass the text into the DoDragDrop method and you're finished.

You can drag an arbitrary object in a similar manner, as long as the drag source and drop target are within the same application. If you want to drag objects between applications, however, you must use serializable objects. A serializable object is one that provides methods for translating the object into and out of a stream-like format. Usually, this format is text, and lately XML is the preferred method for storing text streams.

You can use drag and drop to move a serializable object between applications. The drag source converts the object into its serialization and sends the resulting text to the drop target. The drop target uses the serialization to re-create the object.

You might think it would be hard to make an object serializable. Fortunately, Visual Basic .NET can serialize and deserialize many classes automatically. In most cases, all you need to do is add the Serializable attribute to the class, as shown in the following code:

<Serializable()>
Public Class Employee
    ...
End Class

The drag source can pass objects of this type to the DoDragDrop method.

Example program DragEmployee allows you to drag and drop Employee objects. The program's code starts by defining the constant DATA_EMPLOYEE. This value, DragEmployee.frmDragEmployee+Employee, is the name of the data format type assigned to the Employee class. This name combines the project name, the module name where the class is defined, and the class name.

Public Const DATA_EMPLOYEE As String =
    "DragEmployee.frmDragEmployee+Employee"

The following code shows the program's serializable Employee class:

<Serializable()>
Public Class Employee
    Public FirstName As String
    Public LastName As String
    Public Sub New()
    End Sub
    Public Sub New(ByVal first_name As String, ByVal last_name As String)
        FirstName = first_name
        LastName = last_name
    End Sub
End Class
                                                  

The following code shows how an application can act as a drag source and a drop target for objects of the Employee class. It starts by defining the Employee class. It also defines the string constant DATA_EMPLOYEE. This value, DragEmployee.frmDragEmployee+Employee, is the name of the data format type assigned to the Employee class. This name combines the project name, the module name where the class is defined, and the class name.

When the user presses the mouse down over the lblDragSource control, the following MouseDown event handler creates an Employee object, initializing it with the values contained in the txtFirstName and txtLastName text boxes. It then calls the lblDragSource control's DoDragDrop method, passing it the Employee object and allowing the Move and Copy operations. If DoDragDrop returns the value Move, the user performed a Move rather than a Copy, so the program removes the values from the text boxes.

' Start dragging the Employee.
Private Sub lblDragSource_MouseDown() Handles lblDragSource.MouseDown
    Dim emp As New Employee(txtFirstName.Text, txtLastName.Text)

    If lblDragSource.DoDragDrop(emp,
        DragDropEffects.Copy Or DragDropEffects.Move) =
            DragDropEffects.Move _
    Then
        ' A Move succeeded. Clear the TextBoxes.
        txtFirstName.Text = ""
        txtLastName.Text = ""
    End If
End Sub
                                                  

When the user drags over the lblDropTarget control, the following DragOver event handler executes. The routine first uses the GetDataPresent method to verify that the dragged data contains an Employee object. It then checks the Ctrl key's state and allows a Copy or Move operation as appropriate.

' If an Employee object is available, allow a Move
' or Copy depending on whether the Ctrl key is pressed.
Private Sub lblDropTarget_DragOver(ByVal sender As Object,
 ByVal e As System.Windows.Forms.DragEventArgs) _
 Handles lblDropTarget.DragOver
    If e.Data.GetDataPresent(DATA_EMPLOYEE) Then
        ' Display the Move or Copy cursor.
        Const KEY_CTRL As Integer = 8
        If (e.KeyState And KEY_CTRL) <> 0 Then
            e.Effect = DragDropEffects.Copy
        Else
            e.Effect = DragDropEffects.Move
        End If
    End If
End Sub
                                                  

If the user drops the data on the lblDropTarget control, the following DragDrop event handler executes. It uses the GetData method to retrieve the Employee object. GetData returns a generic Object, so the program uses DirectCast to convert the result into an Employee object. The event handler finishes by displaying theobject's FirstName and LastName properties in its text boxes.

' Display the dropped Employee object.
Private Sub lblDropTarget_DragDrop(ByVal sender As Object,
 ByVal e As System.Windows.Forms.DragEventArgs) _
 Handles lblDropTarget.DragDrop
    Dim emp As Employee =
        DirectCast(e.Data.GetData(DATA_EMPLOYEE), Employee)
    lblFirstName.Text = emp.FirstName
    lblLastName.Text = emp.LastName
End Sub
                                                  

If you compile this program, you can run two copies of the executable program and drag from the drag source in one to the drop target in the other.

If you remove the Serializable attribute from the Employees class, the program still works if you drag from the drag source to the drop target within the same instance of the application. If you run two instances and drag from one to the other, however, the drop target gets the value Nothing from the GetData method, so the drag and drop fails.

The previous example dragged data with the rather unwieldy data format name DragEmployee.frmDragEmployee+Employee. This name identifies the class reasonably well, so it is unlikely that another application will try to load this data if it has some other definition for the Employee class.

On the other hand, the name is rather awkward. It is also problematic if you want to drag objects between two different applications, because each will use its project and module name to define the data format type. If you want to drag Employee objects between the TimeSheet program and the EmployeePayroll program, the names of the data formats generated by the two programs won't match.

The DataObject class provides more control over how the data is represented. Instead of dragging an Employee object directly, you create a DataObject, store the Employee object inside it with the data format name of your choosing, and then drag the DataObject.

Example program DragEmployee2 uses the following code fragment to demonstrate this technique. It creates an Employee object as before and then creates a DataObject. It calls the DataObject object's SetData method, passing it the Employee object and the data format name.

Dim emp As New Employee(txtFirstName.Text, txtLastName.Text)
Dim data_object As New DataObject()
data_object.SetData("Employee", emp)

If lblDragSource.DoDragDrop(data_object,
    DragDropEffects.Copy Or DragDropEffects.Move) = DragDropEffects.Move _
Then
   ' A Move succeeded. Clear the TextBoxes.
   txtFirstName.Text = ""
   txtLastName.Text = ""
End if
                                                  

In general, you should try to avoid very generic names such as Employee for data types. Using such a simple name increases the chances that another application will use the same name for a different class. Another program will not be able to convert your Employee data into a different type of Employee class.

To ensure consistency across applications, you must define a naming convention that can identify objects across projects. To ensure that different applications use exactly the same object definitions, you might also want to define the objects in a separate DLL used by all of the applications. That simplifies the naming problem, because you can use the DLL's name as part of the object's name.

For example, suppose that you build an assortment of billing database objects such as Employee, Customer, Order, OrderItem, and so forth. If the objects are defined in the module BillingObjects.dll, you could give the objects names such as BillingObjects.Employee, BillingObjects.Customer, and so forth.

The DataObject not only allows you to pick the data form name used by a drag; it also allows you to associate more than one piece of data with a drag. To do this, the program simply calls the object's SetData method more than once, passing it data in different formats.

Example program DragRichText uses the following code to drag the text in a RichTextBox control in three data formats: RTF, plain text, and HTML. (RTF, the Rich Text Format, allows text to include different fonts, sizes, styles, and colors.) The lblDragSource control's MouseDown event handler makes a DataObject and calls its SetData method, passing it the rchSource control's contents in the RTF and Text formats. It then builds an HTML string and passes that to the SetData method as well.

' Start a drag.
Private Sub lblDragSource_MouseDown() Handles lblDragSource.MouseDown
    ' Make a DataObject.
    Dim data_object As New DataObject
    ' Add the data in various formats.
    data_object.SetData(DataFormats.Rtf, rchSource.Rtf)
    data_object.SetData(DataFormats.Text, rchSource.Text)

    ' Build the HTML version.
    Dim html_text As String
    html_text = "<HTML>" & vbCrLf
    html_text &= " <HEAD>The Quick Brown Fox</HEAD>" & vbCrLf
    html_text &= " <BODY>" & vbCrLf
    html_text &= rchSource.Text & vbCrLf
    html_text &= " </BODY>" & vbCrLf & "</HTML>"
    data_object.SetData(DataFormats.Html, html_text)

    ' Start the drag.
    lblDragSource.DoDragDrop(data_object, DragDropEffects.Copy)
End Sub
                                                  

The following code shows the lblDropTarget control's DragEnter event handler. If the data includes the RTF, Text, or HTML data formats, the control allows a Copy operation.

' Allow drop of Rtf, Text, and HTML.
Private Sub lblDropTarget_DragEnter(ByVal sender As Object,
 ByVal e As System.Windows.Forms.DragEventArgs) _
 Handles lblDropTarget.DragEnter
    If e.Data.GetDataPresent(DataFormats.Rtf) Or
       e.Data.GetDataPresent(DataFormats.Text) Or
       e.Data.GetDataPresent(DataFormats.Html) _
    Then
        e.Effect = DragDropEffects.Copy
    End If
End Sub
                                                  

The following code shows how a program can read these formats. If the dropped data includes the DataFormats.Rtf format, the code displays it in the RichTextControl rchTarget. It also displays the RTF data in the lblRtf Label. This lets you see the Rich Text codes. If the data includes the Text format, the program displays it in the lblTarget label. Finally, if the data includes HTML, the program displays it in the lblHtml label.

' Display whatever data we can.
Private Sub lblDropTarget_DragDrop(ByVal sender As Object,
 ByVal e As System.Windows.Forms.DragEventArgs) Handles lblDropTarget.DragDrop
    If e.Data.GetDataPresent(DataFormats.Rtf) Then
        rchTarget.Rtf = e.Data.GetData(DataFormats.Rtf).ToString
        lblRtf.Text = e.Data.GetData(DataFormats.Rtf).ToString
    Else
        rchTarget.Text = ""
        lblRtf.Text = ""
    End If

    If e.Data.GetDataPresent(DataFormats.Text) Then
        lblTarget.Text = e.Data.GetData(DataFormats.Text).ToString
    Else
        lblTarget.Text = ""
    End If

    If e.Data.GetDataPresent(DataFormats.Html) Then
        lblHtml.Text = e.Data.GetData(DataFormats.Html).ToString
    Else
        lblHtml.Text = ""
    End If
End Sub
                                                  

Figure 23-1 shows the DragRichText program in action. The RichTextBox on the top shows the original data in rchSource. Below the dragsource and drop target labels, other controls show the dropped results. The first control is a RichTextBox that shows the RTF data. The second control is a label displaying the Rich Text codes. The third control is a label showing the Text data, and the final control is a label showing the HTML data.

Figure 23.1. This program drags and drops data in Text, RTF, and HTML formats.

If you drag data from another application onto the drop target, this program displays only the data that is available. For example, if you drag data from WordPad, this program will display only RTF and Text data, because those are the only compatible formats provided by WordPad.