Drag-and-Drop Behavior

• Jul 09, 2019
• 6 minutes to read

Overview

The Drag-and-Drop Behavior can be attached to a control that displays data to allow users to move/reorder data items with the mouse.

Note

Run the XtraTreeList or XtraGrid demo to try out drag & drop functionality.

In comparison to the standard Control.DoDragDrop method, the Behavior gives you the following advantages.

• A drag operation is automatically initiated, there is no need to handle mouse events.
• The event arguments already include data items being dragged.
• A preview of the dragged element(s) is displayed during the drag operation.
• The mouse cursor indicates whether the user can drop items at the current position.
• An insert indicator shows the place where data items will be inserted.

Supported controls

The Behavior can be attached to the following controls.

• TreeList
• GridControl (GridView only)
• ListBoxControl

Typical scenarios

Reorder data items

To allow users to reorder data items within a single control, attach the Behavior to that control. The tree list and list box controls automatically support reordering if the Behavior is attached. The grid control requires to handle drag events to show a preview of the dragged elements, the insert indicator, and to reorder data items in the data source (see an example).

Move data items

To allow users to move data items between two controls (from one grid to another, from a grid to a tree list, etc.), attach the Behavior to both controls. If both grids/tree lists have the same columns, there are no more actions required. If data structure differs, you need to handle drag events to convert data items (see the XtraTreeList demo).

How to Attach the Drag-and-Drop Behavior to a Control in the Designer

To attach the Drag-and-Drop Behavior to a control, do the following.

• In Visual Studio’s Toolbox, find the BehaviorManager component and drop it on your form.
• Use the component’s smart tag menu, to invoke the editor.
• Use the editor’s drop-down menu, to add the Drag-and-Drop Behavior.

• The Target property is automatically set to a control on the form that supports the Behavior. You can change the target control.

  

  Important

  The attached Drag-and-Drop Behavior is disabled if the Control.AllowDrop property is set to true. It is assumed that you use the standard drag-and-drop engine in this case.

  Do not confuse the Control’s AllowDrop property with the Behavior’s AllowDrop property .

In the Behavior editor’s Properties section, you can specify the following options.

Option	Description
Target	Specifies the control/view to which the Behavior is attached. For a grid control with master-detail data presentation, attach the Drag-and-Drop Behavior to the main view (see GridControl.MainView).
PreviewVisible	Specifies whether a preview of dragged element(s) is displayed during operation.
InsertIndicatorVisible	Specifies whether to show where data items will be inserted. You can customize the indicator in a DragOver event handler.
AllowDrag	Specifies whether users are allowed to drag data items from the control. Set this property to false if you want the control to only be a target of drag operations.
AllowDrop	Specifies whether users are allowed to drop data items on the control. Set this property to false if you want the control to only be a source of drag operations. If this setting is set to false, the DragOver and consequent events do not raise. You can override this setting in a DragEnter event handler.
DragDropEventsName	Specifies the name of the DragDropEvents component that you can use to subscribe to drag events (see below).

How to Attach the Drag-and-drop Behavior to a Control in Code

To assign the Behavior to a control in code, use the BehaviorManager.Attach method. To remove the Behavior, use the BehaviorManager.Detach method. The code below shows how to assign the Behavior to two grids, specify options, and add event handlers.

C#

using DevExpress.Utils.Behaviors;
using DevExpress.Utils.DragDrop;

BehaviorManager behaviorManager1 = new BehaviorManager(this.components);

//To assign the Behavior to a control in code, use the Attach method.
behaviorManager1.Attach<DragDropBehavior>(gridView1, behavior => {
    behavior.Properties.AllowDrop = true;
    behavior.Properties.InsertIndicatorVisible = true;
    behavior.Properties.PreviewVisible = true;
    behavior.DragDrop += Behavior_DragDropToGrid1;
});

behaviorManager1.Attach<DragDropBehavior>(gridView2, behavior => {
    behavior.Properties.AllowDrop = false;
    behavior.Properties.InsertIndicatorVisible = false;
    behavior.Properties.PreviewVisible = false;
    behavior.DragDrop += Behavior_DragDropToGrid2;
});

//To remove the Behavior, use the Detach method.
behaviorManager1.Detach<DragDropBehavior>(gridView1);
behaviorManager1.Detach<DragDropBehavior>(gridView2);

VB.NET

Imports DevExpress.Utils.Behaviors
Imports DevExpress.Utils.DragDrop

Dim behaviorManager1 As New BehaviorManager(Me.components)

'To assign the Behavior to a control in code, use the Attach method.
behaviorManager1.Attach(Of DragDropBehavior)(gridView1, Sub(behavior)
    behavior.Properties.AllowDrop = True
    behavior.Properties.InsertIndicatorVisible = True
    behavior.Properties.PreviewVisible = True
    AddHandler behavior.DragDrop, AddressOf Behavior_DragDropToGrid1
End Sub)

behaviorManager1.Attach(Of DragDropBehavior)(gridView2, Sub(behavior)
    behavior.Properties.AllowDrop = False
    behavior.Properties.InsertIndicatorVisible = False
    behavior.Properties.PreviewVisible = False
    AddHandler behavior.DragDrop, AddressOf Behavior_DragDropToGrid2
End Sub)

'To remove the Behavior, use the Detach method.
behaviorManager1.Detach(Of DragDropBehavior)(gridView1)
behaviorManager1.Detach(Of DragDropBehavior)(gridView2)

How to Customize Drag-and-Drop Operations

To customize drag-and-drop operations, handle the events that fire at the following stages.

• The user starts to drag an item.
• The mouse pointer enters, leaves, or moves over a control.
• The user completes the operation (drops the element).

The DragDropEvents component is automatically added to your form when you attach the Behavior to a control in the designer. You can find its name in the Behavior editor’s Properties section. Use this component to subscribe to the following events.

Event	Description
BeginDragDrop	Occurs when a drag-and-drop operation is initiated.
DragEnter	Occurs when a data item is dragged into the control’s bounds
DragOver	Occurs when a data item is dragged over the control’s bounds
DragLeave	Occurs when a data item is dragged out of the control’s bounds.
DragDrop	Occurs when a data item is dropped on the control.
EndDragDrop	Occurs when a drag-and-drop operation is completed.

You can add event handlers in the designer or in code.

C#

dragDropEvents1.DragDrop += dragDropEvents1_DragDrop;
dragDropEvents1.DragOver += dragDropEvents1_DragOver;

VB.NET

AddHandler dragDropEvents1.DragDrop, AddressOf dragDropEvents1_DragDrop
AddHandler dragDropEvents1.DragOver, AddressOf dragDropEvents1_DragOver

If you attach the Behavior in code, the DragDropEvents component is not added to the form. Use the Behavior’s events in this case.

C#

behaviorManager1.Attach<DragDropBehavior>(gridView1, behavior => {
    behavior.DragDrop += Behavior_DragDropToGrid2;
});

VB.NET

behaviorManager1.Attach(Of DragDropBehavior)(gridView1, Sub(behavior)
    AddHandler behavior.DragDrop, AddressOf Behavior_DragDropToGrid1
End Sub)

Drag-and-Drop Manager

The static (Shared in VB) DragDropManager.Default property provides access to the Drag-and-Drop Behavior manager. You can also use this property to subscribe to drag-and-drop events in a centralized way or specify settings. See the XtraTreeList demo for an example.

Business Object Requirements

Business objects must have a default constructor with no parameters if the Behavior is attached to data-aware controls that store these objects defined in code. Otherwise, rows that display these objects cannot be moved between controls.