Control Dragging and Dropping Items

The WinExplorerBar™ control automatically supports dragging and dropping Items between Groups . There are properties you can use to provide fine-grained control over which Items can be dragged and where they can be dropped. There are also several events you can use to manage the drag-and-drop process.

Before you start writing any code, you should place using/imports directives in your code-behind so you don’t need to always type out a member’s fully qualified name.

In Visual Basic:

Imports Infragistics.Win.UltraWinExplorerBar

In C#:

using Infragistics.Win.UltraWinExplorerBar;

Use the AllowDragCopy and AllowDragMove properties of the Item’s ItemSettings object to specify whether an Item may be moved or copied using drag-and-drop. The enumerated settings of these properties are used to specify the scope of the drag-and-drop movement with respect to the Group containing the Item. Possible settings are None, Within Groups and Within And Across Groups. These properties may also be inherited by using the Default setting.

If both of these properties are set to None, the Item cannot be dragged and dropped. Setting both properties to a value other than None allows the user to perform either moving or copying of Items by using standard drag-and-drop keyboard conventions (drag or drag + shift key to move, drag + control key to copy.) Setting either property individually enables the corresponding behavior within the specified scope, either only moving or only copying the item.

The following code limits a specified Item to being moved only within its Group. It cannot be moved or copied outside of its Group.

In Visual Basic:

Private Sub Control_Dragging_and_Dropping_Items_Load( _
  ByVal sender As System.Object, _
  ByVal e As System.EventArgs) Handles MyBase.Load
	Me.UltraExplorerBar1.Groups(0).Items("SteveWalls").Settings.AllowDragCopy = _
	  ItemDragStyle.None
	Me.UltraExplorerBar1.Groups(0).Items("SteveWalls").Settings.AllowDragMove = _
	  ItemDragStyle.WithinGroupOnly
End Sub

In C#:

private void Control_Dragging_and_Dropping_Items_Load(object sender,
  EventArgs e)
{
	this.ultraExplorerBar1.Groups[0].Items["SteveWalls"].Settings.AllowDragCopy =
	  ItemDragStyle.None;
	this.ultraExplorerBar1.Groups[0].Items["SteveWalls"].Settings.AllowDragMove =
	  ItemDragStyle.WithinGroupOnly;
}

If not explicitly set, the AllowDragCopy and AllowDragMove properties resolve to False for Items whose Style is Label or Separator, and to True for all other Item styles.

The AllowItemDrop property of the Group’s GroupSettings object specifies whether a given group can serve as a target for Items being dragged-and-dropped from other Groups. This property is a defaultable Boolean; it can inherit its value as well as being set either explicitly True or False.

The GroupSettings object also contains the AllowDrag property, which specifies whether the Group as a whole can be dragged. If this property resolves to True, the user can re-order the Groups with the mouse. Group dragging is not supported if the element’s Style property is set to ExplorerBar and its ColumnCount property is greater than 1.

In addition to simply setting permissions on Items and Groups, you can interact with the drag-and-drop process by using the events provided by the element. the WinExplorerBar has six events that are invoked during a drag-and-drop process; three that relate to the Item and three that relate to the Group. These events are outlined below.
- GroupDragging - Occurs when the user starts to drag a Group. You can use this event to examine the Group and the state of the application to determine whether the drag-and-drop operation should be permitted. The cancel parameter of this event can be set to True to prevent the Group from being dragged.
- GroupDragOver - Occurs as the Group being dragged passes over the target groups upon which it might be dropped. The parameters of this event include TargetGroup which returns the Group object onto which the current Group will be dropped, TargetGroupRelativePosition which passes in an enumerated value indicating whether the Group will be placed before or after the target Group when dropped, and AllowDrop which indicates whether the Group may legitimately be dropped on the current target Group. Other parameters provide access to the Group being dragged, the mouse cursor being displayed, and the X and Y position of the Group in screen coordinates.

In Visual Basic:

Private Sub UltraExplorerBar1_GroupDragOver(ByVal sender As Object, _
  ByVal e As Infragistics.Win.UltraWinExplorerBar.GroupDragOverEventArgs) _
  Handles UltraExplorerBar1.GroupDragOver
	' This code ensures that the topmost group remains on top
	' by preventing any group from being dropped above Group 0
	' It assumes a ListBar or Toolbox Style for the element
	If e.TargetGroup.Index = 0 Then
		If e.TargetGroupRelativePosition = GroupDropPosition.Before Then
			e.DragCursor = System.Windows.Forms.Cursors.PanSouth
			e.AllowDrop = False
		ElseIf e.TargetGroupRelativePosition = GroupDropPosition.After Then
			e.DragCursor = Cursors.Default
			e.AllowDrop = True
		End If
	End If
End Sub

In C#:

private void ultraExplorerBar1_GroupDragOver(object sender,
  Infragistics.Win.UltraWinExplorerBar.GroupDragOverEventArgs e)
{
	// This code ensures that the topmost group remains on top
	// by preventing any group from being dropped above Group 0
	// It assumes a ListBar or Toolbox Style for the element
	if (e.TargetGroup.Index == 0)
	{
		if (e.TargetGroupRelativePosition == GroupDropPosition.Before)
		{
			e.DragCursor = System.Windows.Forms.Cursors.PanSouth;
			e.AllowDrop = false;
		}
		else if (e.TargetGroupRelativePosition == GroupDropPosition.After)
		{
			e.DragCursor = System.Windows.Forms.Cursors.Default;
			e.AllowDrop = true;
		}
	}
}

GroupDropped - Occurs when the Group has completed the operation and occupies its new position in the Groups collection. Parameters include OriginalIndex, which indicates the Group’s position within the Groups collection before the drag-and-drop operation occurred.
ItemDragging - Occurs when the user starts to drag an Item. You can use this event to examine the Item and the state of the application to determine whether the drag-and-drop operation should be permitted. The cancel parameter of this event can be set to True to prevent the Item from being dragged.
ItemDragOver - Occurs as the Item being dragged passes over the target groups into which it might be dropped. The parameters of this event include TargetGroup which returns the Group object into which the current Item will be dropped, DragAction which passes in an enumerated value indicating whether the Item is being copied or moved, and AllowDrop which indicates whether the Item may legitimately be dropped on the current target Group. Other parameters provide access to the Item being dragged, the mouse cursor being displayed, and the X and Y position of the Item in screen coordinates.

In Visual Basic:

Private Sub UltraExplorerBar1_ItemDragOver(ByVal sender As Object, _
  ByVal e As Infragistics.Win.UltraWinExplorerBar.ItemDragOverEventArgs) _
  Handles UltraExplorerBar1.ItemDragOver
	If e.DragAction = _
	  Infragistics.Win.UltraWinExplorerBar.ItemDragAction.Move Then
		' Only allow the item to be copied to Employees.
		If e.TargetGroup.Key = "Employees" Then
			Me.UltraStatusBar1.Text = "Drop item here to copy it."
			e.DragCursor = System.Windows.Forms.Cursors.WaitCursor
			e.AllowDrop = True
		Else
			' Update the status bar text and cursor to indicate
			' that it is not ok to copy the item.
			Me.UltraStatusBar1.Text = "Item cannot be dropped on Group '" + _
			  e.TargetGroup.Text + "'."
			e.DragCursor = System.Windows.Forms.Cursors.No
			e.AllowDrop = False
		End If
	End If
End Sub

In C#:

private void ultraExplorerBar1_ItemDragOver(object sender,
  Infragistics.Win.UltraWinExplorerBar.ItemDragOverEventArgs e)
{
	if(e.DragAction == Infragistics.Win.UltraWinExplorerBar.ItemDragAction.Move)
	{
		// Only allow the item to be copied to Employees.
		if (e.TargetGroup.Key == "Employees")
		{
			this.ultraStatusBar1.Text = "Drop item here to copy it.";
			e.DragCursor =
			  System.Windows.Forms.Cursors.WaitCursor;
			e.AllowDrop = true;
		}
		else
		{
			// Update the status bar text and cursor to indicate
			// that it is not ok to copy the item.
			this.ultraStatusBar1.Text = "Item cannot be dropped on Group '" +
			  e.TargetGroup.Text + "'.";
			e.DragCursor = System.Windows.Forms.Cursors.No;
			e.AllowDrop = false;
		}
	}
}

ItemDropped - Occurs when the Item has completed the operation and occupies its new position. Parameters include DragAction which passes in an enumerated value indicating whether the Item is being copied or moved, and OriginalGroup, which indicates the Group that contained the Item before the drag-and-drop operation occurred.

Windows Forms | Help Topics

Control Dragging and Dropping Items