7.10 Supporting Drag and Drop Operations

You want to be able to drag and drop certain items onto your Windows Form.

Technique

Using the property browser for your form, set the AllowDrop property to true . Drag and drop uses the event system to control how a drag and drop is performed, which means you need to create a few event handlers. Click on the event button in the property browser toolbar and create event handlers for the DragDrop , DragEnter , DragLeave , and DragOver events.

The DragEnter and DragOver event handlers allow you to customize the display of the cursor as a drag operation occurs. Using the DragEventArgs parameter, you can query the data type of the object being dragged by calling the GetDataPresent method defined in the Data object of the event arguments. This method uses a value from the DataFormats enumerated data type as a parameter that denotes the type of data which is being dragged by the user. If the user is dragging a group of files, for instance, use the DataFormats.FileDrop value. If the object being dragged is supported by your application, set the Effect property in the DragEventArgs to a value defined in the DragDropEffects enumeration. This move changes the cursor to accurately reflect what your application plans to do with the objects. Furthermore, you can also determine whether the user is pressing a system key such as Ctrl or Alt by examining the KeyState property of the event argument's object:

 private void Form1_DragEnter(object sender, System.Windows.Forms.DragEventArgs e) {     if( e.Data.GetDataPresent(DataFormats.FileDrop, false) == true )     {         if( (e.KeyState & 8) == 8 )             e.Effect = DragDropEffects.Copy;         else if( (e.KeyState & 32) == 32 )             e.Effect = DragDropEffects.Link;         else             e.Effect = DragDropEffects.Move;     } } 

When the user releases the mouse button, the DragDrop event handler is called. This handler uses the same DragEventArgs , as shown earlier. To retrieve the actual data, call the GetData method defined in the Data object of the event arguments using the same data type specification used when querying for the type of data being dragged. Because the GetData method returns a generic System.Object , you have to cast the return value to the appropriate data type. For a FileDrop object, the return value is an array of strings denoting the filenames being dropped:

 private void Form1_DragDrop(object sender, System.Windows.Forms.DragEventArgs e) {     string[] files = (string[])e.Data.GetData("FileDrop", false);     StringBuilder fileList = new StringBuilder();     foreach (string s in files)     {         fileList.Append( s + "\n" );     }     MessageBox.Show( fileList.ToString() ); } 

Comments

Graphical user interfaces introduced metaphors. A user-interface metaphor acts to associate a common task or command in the operating system with a common and easily recognizable object in the physical world. The classic metaphor example is the Recycle Bin. Its purpose is to act as a holding place for objects that might potentially be deleted by using a trash-can metaphor. Likewise, directories containing files use a folder-based metaphor. The metaphor of this recipe is drag and drop. In the physical world, a person will take a folder that potentially contains a group of files and drop it into a trash can or drop it into a different folder. By using concepts that are prevalent within the physical world, you dramatically increase the ease of use for your user interface.

You add drag and drop by setting the AllowDrop property of a form to true . When you do this, your form class will be notified via events of any drag and drop operations that a user performs . The first event that occurs when a user drags an item over your form is the DragEnter event. In the handler for this event, you should make a check using the GetDataPresent method defined in the Data object within the DragEventArgs parameter. This check determines the cursor that is displayed to give a visual indication to the user about the type of drag and drop support there is for the item being dragged. If your form does not support that item, set the Effect property from the DragEventArgs parameter to DragDropEffects.None . If your form does support the data type of the item, you can further refine the cursor display by checking to see what system keys the user presses. Table 7.2 shows the numerical values of the system keys in the KeyState property of the event arguments. To check whether a key is pressed, perform a bitwise and ( & ) with the KeyState property and the numerical value of the system key you are checking against. If the value of the bitwise and is the same value as the key you are checking, then that key is pressed. Note also that even though the KeyState property appears to only check the keyboard state, it also determines the state of any of the mouse buttons .

Table 7.2. Bit Values of KeyState Property for System Keys

Bit	Key/Button
1	Left mouse button
2	Right mouse button
4	Shift key
8	Ctrl key
16	Middle mouse button
32	Alt key

The DragOver event occurs after the DragEnter event. When the DragOver event handler is called, the user is dragging an item within the form. You will use this event handler more extensively when working with form controls. However, you still need to perform the same data-type check and set the corresponding DragDropEffect within this event handler. This step allows the user to press a system key while dragging and allows you to update the cursor based on that key press.

At this point, the user can either cancel the drag and drop or perform the drop by releasing the mouse button. When a user cancels the operation, either by pressing the Esc key or dragging the item off the form, the DragLeave event is fired . This event allows you to perform any cleanup associated with the previous drag and drop event handlers that were called. If the user does in fact drop the item, you now have to access the data being dropped.

When the DragDrop event handler is called, you can access the associated item data by calling the GetData method defined in the Data object of the event arguments. The data type that you retrieve should be the same data type you used when performing data-type checks in the initial drag and drop events. The GetData method returns a System.Object , which means you have to cast the value to the appropriate data type. The final data type depends on the actual data type of the item being dropped. The code for the DragDrop event handler presented earlier called the GetData method, specifying that FileDrop data is requested . The FileDrop data item returns a string array consisting of filenames. The next chapter goes into detail about creating and using custom drag and drop scenarios. Even though the process mentioned utilizes controls for drag and drop, the process is similar to using forms.