This topic provides an overview of Intersoft ClientUI Drag-drop Framework. Drag-and-drop commonly refers to a method of user interface (UI) interaction that involves using a mouse to select one or more objects, dragging these objects over some desired drop target in the UI, and dropping them.

This topic contains the following sections:

• Drag and Drop Support in ClientUI
• Drag and Drop Panel
• Drag and Drop Events
• Working with Data Objects

Drag and Drop Support in ClientUI

The drag-drop framework in ClientUI provides a comprehensive library to easily add drag and drop capability to any UI Elements within Silverlight or WPF application.

Drag-and-drop operations typically involve two parties: a drag source from which the dragged object originates and a drop target which receives the dropped object. Using the drag-drop framework available in ClientUI, you can make an UIElement dragable by simply attaching a behavior to the UIElement or using API to initiate the drag-drop session.

Making an UIElement Dragable using DragDropBehavior

To make an UIElement dragable, you attach a DragDropBehavior to that particular elements as shown in the XAML code below.

In the above sample, the DragDropBehavior is attached to a StackPanel that has an image and a text element.

When you dragged the StackPanel, the StackPanel is not moved from its original place. The actual element being moved is a shadow object that represents the current dragable object. This shadow object serves as an indicator where the object is currently dragged into. If it is dropped to a non droppable target, there will be an animation to indicate the shadow object being returned to the original position. To learn more how to customize the shadow object, see How to: Customize Drag Shadow Object.

The side effect of this concept is that you can start the drag-drop operation by dragging any elements within the StackPanel, which might not always be desirable. To make only certain elements dragable, you attach a DragDropPointBehavior to the desired dragable element which is the children element of the StackPanel.

The following code shows how you can limit the drag source to an Image element.

Customizing Drag Effects

When an object is being dragged, the source object is still displayed as the shadow object appears. This behavior can further customized by modifying the DragEffect property. There are three types of DragEffect that you can select:

Customizing Initial Tooltip

Each DragEffect comes with predefined tooltip image and text that indicates the drag action.

You can customize the tooltip by modifying the TooltipIcon and TooltipText properties as shown below.

You can also customize the offset position of the tooltip using the TooltipOffset property, or change the TooltipLatency property to enhance the user experience aspects.

Customizing Tooltip Latency

When the drag is initiated, the tooltip only shows the tooltip icon, it will then display the tooltip text until a certain time span has elapsed which is determined by the TooltipLatency property. After the text is shown, it will remain visible and will be updated accordingly to user modification.

 

Making an UIElement Dragable using provided API

To make an UIElement dragable, you can also use the provided API. The API to drag the object is DragDrop.DoDragDrop method. You can also use the ISDragDrop.DoDragDrop method, since this method is equivalent with DragDrop.DoDragDrop method.

The DragDrop.DoDragDrop is provided to enable unified shared code base with WPF, allowing you to easily migrate your existing WPF application that used WPF's Drag-drop API to the Silverlight application without major changes. 

To learn how to make an UIElement dragable using API, see How-to: Drag an UIElement using API.

Making an UIElement Droppable

To make an UIElement droppable, you can choose one of the following approaches:

Making an UIElement Droppable using DropTargetBehavior

The following code demonstrates how to make an UIElement droppable using DropTargetBehavior.

With DropTargetBehavior, you can easily customize the tooltip when an object is being dragged over to a target element by specifying the TooltipIcon property and the TooltipText property. You can also determine the drop action from DropBehavior property if the drop target is a Panel element.

The following list explains several drop behaviors that you can apply:

• AppendChild
  Remove the dragged object from original source and append it to drop target's children.
• Replace
  Remove the dragged object from original source and replace the drop target's children.
• Custom
  Requires user implementation on Drop event.

To learn how to handle Drop event, see How to: Copy the dragged object when dropped to the drop target and How to: Remove the drag object when dropped to drop target.

Making an UIElement Droppable using Intersoft:ISDragDrop.AllowDrop attached property

The following code demonstrates how to make an UIElement droppable by using the ISDragDrop.AllowDrop attached property.

This approach is only used to mark the UIElement as a droppable element. It does not include built-in handling such as in DropTargetBehavior thus requires you to write additional logic at the Drop event. To learn how to handle Drop event, see How to: Copy the dragged object when dropped to the drop target and How to: Remove the drag object when dropped to drop target.

Making an UIElement Droppable using AllowDrop attached property

The following code demonstrates how to make an UIElement droppable using AllowDrop property.

This approach is only used to mark the UIElement as a droppable element. It doesn't include built-in handling such as in DropTargetBehavior thus requires you to write additional logic at the Drop event. To learn more how to handle Drop event, see How to: Copy the dragged object when dropped to the drop target and How to: Remove the drag object when dropped to drop target.

Customizing Tooltip when Entering DropTarget

You can customize the tooltip text and icon of the drag-drop visual cues when the dragged object is over the drop target. The DropTargetBehavior already has the properties that allow you customize it directly in the form of TooltipIcon and TooltipText as explained in the following code.

For the first two approaches, you need to manually change the tooltip text and icon during DragEnter event. To learn more how to handle DragEnter event, see How to: Change tooltip when hovering drop target.

Drag Drop Scope

ClientUI provides a comprehensive drag-drop framework that enables you to easily create fluid drag and drop user experiences. When an object is being dragged, the drag-drop framework detects the available drop target within a certain scope which is determined by the DragDropScope property. The default value for this property is Global which means that the scope is set to the root visual of your application. In this case, the drag-drop framework will search for any droppable controls available in your application.

In certain scenarios, you might want to limit the scope of the drag drop operation. This can be done by changing the DragDropScope property to Parent, then apply the ISDragDrop.IsDragDropScope attached property to the element which the drag-drop operation should be scoped.

To understand about the drag-drop scope capability, consider the following scenario.

In this scenario, the dragable element is set to My Archive object while the droppable targets are set to the GreenContainer, the RedContainer, the SiblingContainer and the SourceContainer.

If the DragDropScope property is set to Global, the objects can be dragged and dropped into any of the drop targets. You can limit the drag-drop scope by setting the DragDropScope property to Parent and determine the drag-drop scope by using the Intersoft:ISDragDrop.ISDragDropScope attached property. See the following example.

With this configuration you are able to drag the My Archive object to SiblingContainer but not to RedContainer or GreenContainer. 

Drag and Drop Panel

In addition to the behaviors and API, ClientUI's drag-drop framework also provides panels that include built-in drag and drop functionality which makes drag and drop implementation very simple and easy. These panels are built on the top of core drag-drop framework and can be consumed by ItemsControl to enabled drag-drop functionality for its items collection.

Introducing UXPanel

UXPanel is the base class of all panel controls in ClientUI that expose the drag-drop capability. Every item registered under UXPanel will automatically have a DragDropBehavior attached, so you do not need to manually register the DragDropBehavior to the UXPanel, unless you want to override the drag-drop behaviors for certain items.

UXPanel has a set of specific properties that controls the drag and drop behaviors which are explained in the following list.

Each property above unlocks specific actions that you can do. Depending on your requirements, you will need enable or disable several settings.

The following section discusses the combination of settings to achieve common drag-drop scenarios.

Customizing Tooltip

When working with drag-drop, visual hints is important to notify users of the current drag-drop status. UXPanel provides built-in visual hints - such as predefined tooltip - that depends on the settings and the current user action, which significantly simplifies the development process to create fluid drag and drop user experiences.

For example:

Generally there are three main entry points where you can effectively customize the visual hints:

Integration With ItemsControl

ItemsControl such as ListBox (native), UXListBox, UXFlow, and many others use Panel to arrange their items. You can change the Panel used to arrange those items from ItemsPanel property. This gives you the flexibility to choose any panels in order to control the arrangement of your items. You can use UXPanel to easily add drag and drop functionality to your items control.

The following example shows you how to enable drag and drop in a standard ListBox control.

As shown in the above example,  you can change the ItemsPanel of each ListBox to a UXPanel (in this case UXStackPanel) which enables you to easily add drag and drop features such as AllowDropItem, AllowMoveItem, and more.

When an item is removed, moved or reordered in an ItemsControl such as ListBox, its item collection will be automatically synchronized. This powerful feature also works in data bound scenarios where a collection of items are bound to the ListBox through ItemsSource.

Working with Unbound ItemsControl and Bound ItemsControl

As illustrated in the above code example, you can change the ItemsPanel of an ItemsControl with UXPanel to enable drag and drop operations in ItemsControl. The ItemsControl can be configured in either unbound or bound mode.

When moving item between ItemsControl it is recommended to use the same mode for both ItemsControl (source and destination) to enable the automatic items synchronization. However, if your scenario requires the item to be moved using different mode, you need to handle the synchronization manually.

To learn how to handle the item drop from different bound mode, see How-to: Move item from bound ListBox to unbound ListBox using UXPanel and How-to: Move item from unbound ListBox to bound ListBox using UXPanel.

Working with Transformable Item

Having the understanding of the concept that drag-drop operations can be easily enabled in any controls that derive from ItemsControl, your application may consist of several different types of dragable ItemsControl where the drag-drop operations should work together across these controls.

ClientUI introduces numerous built-in dragable ItemsControl such as UXListBox, UXAccordion and UXDock. You can easily drag item from one control to another without requiring additional code thanks to the ITransformInfo interface implemented by each item control.

Drag and Drop Events

Drag-and-drop operations support an event driven model. Both the drag source and the drop target use a standard set of events to handle drag-and-drop operations. The following list summarizes the drag-and-drop events sequence.

On Drag Start

On Dragging

On Drop

On Key Down (During dragging)

When you examine the events sequence above, you will see some kind of redundant events such as ISDragDrop.DragSourceEvent (EventType = DragInit) with ISDragDrop.DragInitEvent, and ISDragDrop.DragSourceEvent (EventType = DragEnter) with DragDrop.DragEnterEvent.

The difference between this event is that ISDragDrop.DragSourceEvent is always raised from the drag source while the other relevant event is raised by either the drag source or drop target depending on the condition.

The benefit to have the ISDragDrop.DragSourceEvent is that you can handle the DragInit, DragStart, DragStarted, DragLeave, DragEnter, DragOver, DragEnd, Drop, DragEnded, DragReturn and DragReturned from the drag source directly. This event gives you the flexibility in your application design where you can handle the drag-drop operations from either the drag source or the drop target.

To help you understand the common usages of the provided events, the following list explains several common scenarios that you can achieve by using the provided events:

• As soon the drag about to start, perform a conditional checking to determine whether the item can be drag or not. This can be done during ISDragDrop.DragSourceEvent (EventType = DragInit) or ISDragDrop.DragInitEvent. To learn more about this, see How-to: Perform conditional checking to determine whether an item is dragable.
• Changing the drag shadow object. This can be done during ISDragDrop.ShadowInitEvent. To learn more how to customize the shadow object, see How to: Customize Drag Shadow Object.
• Customize the tooltip when entering a drop target. To learn more, see How to: Change tooltip when hovering drop target.
• Customize the tooltip when leaving a drop target. To learn more, see How to: Change tooltip when leaving drop target.
• Copy the object when dropping it to a drop target. To learn more, see How to: Copy the dragged object when dropped to the drop target.
• Remove the object when dropping it to drop target. To learn more, see How to: Remove the drag object when dropped to drop target.

Working With Data Objects

When dealing with drag and drop, it is common to assign a data to be carried during the drag and drop operation. The drag-drop framework in ClientUI also provides this architecture to store the data in multiple formats.

Storing Data

To store the data, you can use the DragInit event or perform the drag-drop manually by using the provided API, then store the data when you call the API.

To learn how to enable drag and drop using API and storing the data using API, see How-to: Drag an UIElement using API.

To learn how to store the data at DragInit event, see How-to: Store DataObject at DragInit event.

Querying a Data Object for Available Formats

Because a single data object can contain an arbitrary number of data formats, data objects include facilities for retrieving a list of available data formats.

The following example code uses the GetFormats overload to get an array of strings denoting all data formats available in a data object.

Retrieving Data from a Data Object

Retrieving data from a data object in a particular format simply involves calling one of the GetData methods and specifying the desired data format. One of the GetDataPresent methods can be used to check for the presence of a particular data format. GetData returns the data in a Object; depending on the data format, this object can be cast to a type-specific container.

The following example code uses the GetDataPresent(String) overload to first check if a specified data format is available (natively or by auto-convert). If the specified format is available, the example retrieves the data by using the GetData(String) method.

See Also