Skip to end of metadata
Go to start of metadata

Remarks

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.

  • AllowDropItem
    AllowDropItem indicates whether the panel can accept drop. (Making the panel as droppable target).
  • AllowMoveItem
    AllowMoveItem indicates whether the item can be moved to other droppable target.
  • AllowReorderItem
    AllowReorderItem indicates whether the item can be reordered within the panel.
  • AllowRemoveItem
    AllowRemoveItem indicates whether the item can be removed from panel by dropping it at empty space.
  • DragMode
    DragMode indicates the drag action, whether it is a Copy or a Move action.
    Move action will move the object from its original container to the target droppable container, while copy action will require user to create the copy object and insert it to the target droppable container. Note that when you set the DragMode property to Copy action, you can not reorder the item even though AllowReorderItem is set to true.

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:

  • DragMode = MoveAllowRemoveItem = False
    Using this configuration, the tooltip will show a "Move" visual hint when you initiated a drag operation on an object. As soon as the object is dragged out from the panel, the tooltip will show a "Not Allowed" visual hint until the object is over a droppable target, or when the source panel receives a command to set the tooltip back to "Move".
  • DragMode = MoveAllowRemoveItem = True
    Using this configuration, the tooltip will show a "Move" visual hint when you initiated a drag operation on an object. As soon as the object is dragged out from the panel, the tooltip will show a"Remove" visual hint.

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.

Enable Drag Drop in 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.

Working with ShadowInit Event

The following example code demonstrates how to handle ShadowInit event to customize drag shadow object for UXPanel items.

XAML
C#

Definition

public abstract class UXPanel : ISPanel

Summary

The following table summarizes the members exposed in this class.

Protected Constructors

Public Properties

AllowDropItemGets or sets a value that determines whether external item can be dropped into this control.
AllowMoveItemGets or sets a value that determines whether the Items in this control can be moved to other controls.
AllowRemoveItemGets or sets a value that determines whether the Items in this control can be removed.
AllowReorderItemGets or sets a value that determines whether external the Items in this control can be repositioned.
DragDropScopeGets or sets the drag drop scope.
DragDropTooltipIconGets or sets the icon of the DragDropTooltip.
DragDropTooltipLatencyGets or sets a value that determines the latency to show the DragDropTooltip.
DragDropTooltipOffsetGets or sets the offset position of the DragDropTooltip.
DragDropTooltipStyleGets or sets the style of the DragDropTooltip.
DragDropTooltipTextGets or sets the text of the DragDropTooltip.
DragModeGets or sets the dragging behavior.
DropableTargetsGets the collection of dropable target names.
InsertAtTheEndIndicates whether this panel should use insert an item at the end when insert index can't be determined.
IsControlVisibleGets a value that determine that the current ux panel is visible. This property need to be set when a parent container is collapsed or resized that cause the entire element is not visible.
ItemsControlGets host.
LatencyGets or sets a value that determine the latency before the item collection is re-adjusted when an item is inserted, moved or removed.
UseAnimationGets or sets a value that determine whether the insert, reorder, and removed animation is used.
UseShadowDimensionForFillElementIndicates whether this panel should use shadow object's dimension for the fill element

Fields

AllowDropItemPropertyIdentifies the AllowDropItem dependency property.
AllowMoveItemPropertyIdentifies the AllowMoveItem dependency property.
AllowRemoveItemPropertyIdentifies the AllowRemoveItem dependency property.
AllowReorderItemPropertyIdentifies the AllowReorderItem dependency property.
AnimationPropertyIdentifies the Animation dependency property.
DimensionPropertyIdentifies the Dimension dependency property.
DragDropScopePropertyIdentifies the DragDropScope dependency property.
DragDropTooltipIconPropertyIdentifies the DragDropTooltipIcon dependency property.
DragDropTooltipLatencyPropertyIdentifies the DragDropTooltipLatency dependency property.
DragDropTooltipOffsetPropertyIdentifies the DragDropTooltipOffset dependency property.
DragDropTooltipStylePropertyIdentifies the DragDropTooltipText dependency property.
DragDropTooltipTextPropertyIdentifies the DragDropTooltipText dependency property.
DragModePropertyIdentifies the DragMode dependency property.
DropableTargetsPropertyIdentifies the DropableTargets dependency property.
InsertedEventIdentifies the Inserted routed event.
InsertingEventIdentifies the Inserting routed event.
LatencyPropertyIdentifies the Latency dependency property.
MovedEventIdentifies the Moved routed event.
MovingEventIdentifies the Moving routed event.
OriginalDimensionPropertyIdentifies the OriginalDimension dependency property.
RemovedEventIdentifies the Removed routed event.
RemovingEventIdentifies the Removing routed event.

Static Methods

GetAnimation(UIElement)Gets animation value from target element.
GetDimension(UIElement)Gets dimension value from target element.
GetOriginalDimension(UIElement)Gets original dimension value from target element.
SetAnimation(UIElement, Storyboard)Sets animation value to target element.
SetDimension(UIElement, Nullable<Size>)Sets dimension to target element.
SetOriginalDimension(UIElement, Nullable<Size>)Sets original dimension to target element.

Public Methods

AddChild(int, FrameworkElement)Add new element into specified index.
FlagVisibility(bool)Set the visibility flag of UXPanel. (Used for internal mechanism).
GetDropableObject()Gets the dropable object.
IsDropable()Gets a value that indicates wheter the current panel is dropable.
IsDropable(DragEventArgs)Gets a value indicating whether the target is dropable.
IsFillElement(UIElement)Gets a value that indicates whether the specified element is FillElement.
MoveChild(int, int)Move the element from current index to target index.
OverrideFillElement(FrameworkElement)Overrides fill element.
RemoveChild(UIElement)Removed the UIElement from UXPanel.
RemoveChild(int)Removed the UIElement at specified index.

Events

DragEndOccurs when drag end.
DragEndedOccurs when drag is ended.
DragEnterOccurs when drag drop is entering drop target.
DragInitOccurs when drag is initializing.
DragLeaveOccurs when drag is leaving drop target.
DragOverOccurs when drag drop is hovering drop target.
DragReturnOccurs when drag object is returning to original position.
DragReturnedOccurs when drag object is returned to original position.
DragStartOccurs when drag start.
DragStartedOccurs when drag started.
DropOccurs when drag drop.
DropObjectChangedOccurs when drop object is changed.
InsertedOccurs when an item is being inserted.
InsertingOccurs when an item is going to be inserted.
MovedOccurs when an item is being moved.
MovingOccurs when an item is going to be moved.
NativeDragEnterOccurs when native drag enter event triggered.
NativeDragLeaveOccurs when native drag leave event triggered.
NativeDragOverOccurs when native drag over event triggered.
NativeDropOccurs when native drop event triggered.
PrepareDropOccurs when before drop event.
PreviewDragEnterOccurs when previewing drag enter.
PreviewDragLeaveOccurs when previewing drag enter.
PreviewDragOverOccurs when previewing drag over.
PreviewDropOccurs when previewing drop.
PreviewQueryDropStateOccurs when previewing query drop state.
QueryDropStateOccurs when querying drop state.
RemovedOccurs when an item is being removed.
RemovingOccurs when an item is going to be removed.
ShadowCreatedOccurs when shadow is created.
ShadowInitOccurs when shadow is initializing.

Protected Constructors

protected UXPanel()

 

Public Properties

public bool AllowDropItem { get; set; }

Gets or sets a value that determines whether external item can be dropped into this control.

public bool AllowMoveItem { get; set; }

Gets or sets a value that determines whether the Items in this control can be moved to other controls.

public bool AllowRemoveItem { get; set; }

Gets or sets a value that determines whether the Items in this control can be removed.

public bool AllowReorderItem { get; set; }

Gets or sets a value that determines whether external the Items in this control can be repositioned.

public DragDropScope DragDropScope { get; set; }

Gets or sets the drag drop scope.

public ImageSource DragDropTooltipIcon { get; set; }

Gets or sets the icon of the DragDropTooltip.

public double DragDropTooltipLatency { get; set; }

Gets or sets a value that determines the latency to show the DragDropTooltip.

public Point DragDropTooltipOffset { get; set; }

Gets or sets the offset position of the DragDropTooltip.

public Style DragDropTooltipStyle { get; set; }

Gets or sets the style of the DragDropTooltip.

public string DragDropTooltipText { get; set; }

Gets or sets the text of the DragDropTooltip.

public DragMode DragMode { get; set; }

Gets or sets the dragging behavior.

public ObservableCollection<string> DropableTargets { get; }

Gets the collection of dropable target names.

public bool InsertAtTheEnd { get; set; }

Indicates whether this panel should use insert an item at the end when insert index can't be determined.

public bool IsControlVisible { get; }

Gets a value that determine that the current ux panel is visible. This property need to be set when a parent container is collapsed or resized that cause the entire element is not visible.

public ItemsControl ItemsControl { get; }

Gets host.

public double Latency { get; set; }

Gets or sets a value that determine the latency before the item collection is re-adjusted when an item is inserted, moved or removed.

public bool UseAnimation { get; set; }

Gets or sets a value that determine whether the insert, reorder, and removed animation is used.

public bool UseShadowDimensionForFillElement { get; set; }

Indicates whether this panel should use shadow object's dimension for the fill element

Fields

public static readonly DependencyProperty AllowDropItemProperty

Identifies the AllowDropItem dependency property.

public static readonly DependencyProperty AllowMoveItemProperty

Identifies the AllowMoveItem dependency property.

public static readonly DependencyProperty AllowRemoveItemProperty

Identifies the AllowRemoveItem dependency property.

public static readonly DependencyProperty AllowReorderItemProperty

Identifies the AllowReorderItem dependency property.

public static readonly DependencyProperty AnimationProperty

Identifies the Animation dependency property.

public static readonly DependencyProperty DimensionProperty

Identifies the Dimension dependency property.

public static readonly DependencyProperty DragDropScopeProperty

Identifies the DragDropScope dependency property.

public static readonly DependencyProperty DragDropTooltipIconProperty

Identifies the DragDropTooltipIcon dependency property.

public static readonly DependencyProperty DragDropTooltipLatencyProperty

Identifies the DragDropTooltipLatency dependency property.

public static readonly DependencyProperty DragDropTooltipOffsetProperty

Identifies the DragDropTooltipOffset dependency property.

public static readonly DependencyProperty DragDropTooltipStyleProperty

Identifies the DragDropTooltipText dependency property.

public static readonly DependencyProperty DragDropTooltipTextProperty

Identifies the DragDropTooltipText dependency property.

public static readonly DependencyProperty DragModeProperty

Identifies the DragMode dependency property.

public static readonly DependencyProperty DropableTargetsProperty

Identifies the DropableTargets dependency property.

public static readonly RoutedEvent InsertedEvent

Identifies the Inserted routed event.

public static readonly RoutedEvent InsertingEvent

Identifies the Inserting routed event.

public static readonly DependencyProperty LatencyProperty

Identifies the Latency dependency property.

public static readonly RoutedEvent MovedEvent

Identifies the Moved routed event.

public static readonly RoutedEvent MovingEvent

Identifies the Moving routed event.

public static readonly DependencyProperty OriginalDimensionProperty

Identifies the OriginalDimension dependency property.

public static readonly RoutedEvent RemovedEvent

Identifies the Removed routed event.

public static readonly RoutedEvent RemovingEvent

Identifies the Removing routed event.

Static Methods

public static Storyboard GetAnimation(UIElement element)

Gets animation value from target element.

Parameters

elementTarget element.

Return Types

Animation.

 

public static Nullable<Size> GetDimension(UIElement element)

Gets dimension value from target element.

Parameters

elementTarget element.

Return Types

Dimension.

 

public static Nullable<Size> GetOriginalDimension(UIElement element)

Gets original dimension value from target element.

Parameters

elementTarget element.

Return Types

Dimension.

 

public static void SetAnimation(UIElement element, Storyboard value)

Sets animation value to target element.

Parameters

elementTarget element.
valueAnimation.

 

public static void SetDimension(UIElement element, Nullable<Size> value)

Sets dimension to target element.

Parameters

elementTarget element.
valueDimension.

 

public static void SetOriginalDimension(UIElement element, Nullable<Size> value)

Sets original dimension to target element.

Parameters

elementTarget element.
valueDimension.

 

Public Methods

public void AddChild(int index, FrameworkElement element)

Add new element into specified index.

Parameters

indexIndex.
elementElement.

 

public void FlagVisibility(bool visibility)

Set the visibility flag of UXPanel. (Used for internal mechanism).

Parameters

visibilityVisibility flag.

 

public DependencyObject GetDropableObject()

Gets the dropable object.

Return Types

Dropable object.

 

public bool IsDropable()

Gets a value that indicates wheter the current panel is dropable.

Return Types

A value that indicates wheter the current panel is dropable.

 

public bool IsDropable(DragEventArgs args)

Gets a value indicating whether the target is dropable.

Parameters

argsArgument that hold information about the drop target.

Return Types

Value that indicates whether the target is dropable.

 

public bool IsFillElement(UIElement element)

Gets a value that indicates whether the specified element is FillElement.

Parameters

element 

 

public void MoveChild(int currentIndex, int targetIndex)

Move the element from current index to target index.

Parameters

currentIndexCurrent index.
targetIndexTarget index.

 

public void OverrideFillElement(FrameworkElement fillElement)

Overrides fill element.

Parameters

fillElementFill element.

 

public void RemoveChild(UIElement child)

Removed the UIElement from UXPanel.

Parameters

childElement that going to be removed.

 

public void RemoveChild(int index)

Removed the UIElement at specified index.

Parameters

indexIndex.

 

Events

public event DragEventHandler DragEnd

Occurs when drag end.

public event DragEventHandler DragEnded

Occurs when drag is ended.

public event DragEventHandler DragEnter

Occurs when drag drop is entering drop target.

public event DragEventHandler DragInit

Occurs when drag is initializing.

public event DragEventHandler DragLeave

Occurs when drag is leaving drop target.

public event DragEventHandler DragOver

Occurs when drag drop is hovering drop target.

public event DragEventHandler DragReturn

Occurs when drag object is returning to original position.

public event DragEventHandler DragReturned

Occurs when drag object is returned to original position.

public event DragEventHandler DragStart

Occurs when drag start.

public event DragEventHandler DragStarted

Occurs when drag started.

public event DragEventHandler Drop

Occurs when drag drop.

public event DropObjectChangedRoutedEventHandler DropObjectChanged

Occurs when drop object is changed.

public event UXPanelActionRoutedEventHandler Inserted

Occurs when an item is being inserted.

public event UXPanelActionRoutedEventHandler Inserting

Occurs when an item is going to be inserted.

Occurs when an item is being moved.

Occurs when an item is going to be moved.

public event DragEventHandler NativeDragEnter

Occurs when native drag enter event triggered.

public event DragEventHandler NativeDragLeave

Occurs when native drag leave event triggered.

public event DragEventHandler NativeDragOver

Occurs when native drag over event triggered.

public event DragEventHandler NativeDrop

Occurs when native drop event triggered.

public event DragEventHandler PrepareDrop

Occurs when before drop event.

public event DragEventHandler PreviewDragEnter

Occurs when previewing drag enter.

public event DragEventHandler PreviewDragLeave

Occurs when previewing drag enter.

public event DragEventHandler PreviewDragOver

Occurs when previewing drag over.

public event DragEventHandler PreviewDrop

Occurs when previewing drop.

public event QueryDropStateEventHandler PreviewQueryDropState

Occurs when previewing query drop state.

public event QueryDropStateEventHandler QueryDropState

Occurs when querying drop state.

public event UXPanelActionRoutedEventHandler Removed

Occurs when an item is being removed.

public event UXPanelActionRoutedEventHandler Removing

Occurs when an item is going to be removed.

public event DragDropShadowRoutedEventHandler ShadowCreated

Occurs when shadow is created.

public event DragDropShadowRoutedEventHandler ShadowInit

Occurs when shadow is initializing.

Remarks

This event raised when shadow image is being initialized. You can customize the drag shadow object from this event.
  • No labels