Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Section

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 UXPanelthe UXPanel, unless you want to override the drag-drop behaviors for certain items.

UXPanel has 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 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 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.

Code Block
titleEnable Drag Drop in standard ListBox Control
languagexml
<UserControl.Resources>
    <ItemsPanelTemplate x:Key="ItemsPanelTemplate1">
        <Intersoft:UXStackPanel Orientation="Vertical" AllowMoveItem="True"
			AllowDropItem="True" AllowReorderItem="True" AllowRemoveItem="True"/>
    </ItemsPanelTemplate>
    <ItemsPanelTemplate x:Key="ItemsPanelTemplate2">
        <Intersoft:UXStackPanel Orientation="Vertical" AllowMoveItem="True"
			AllowDropItem="True" AllowReorderItem="True"/>                     
    </ItemsPanelTemplate>
</UserControl.Resources>
    
<Grid x:Name="LayoutRoot" Background="White">
    <StackPanel HorizontalAlignment="Left" VerticalAlignment="Center" Width="250">
    <ListBox x:Name="ListBox1" ItemsPanel="{StaticResource ItemsPanelTemplate1}">
        <ListBoxItem Content="To-do: Prepare Walkthrough Materials"/>
        <ListBoxItem Content="To-do: Prepare Video Materials"/>
        <ListBoxItem Content="To-do: Create Press Release"/>
    </ListBox>
    <Intersoft:FieldLabel Header="Selected Index: " HeaderWidth="100"
			HorizontalHeaderAlignment="Right">
        <TextBlock Text="{Binding SelectedIndex, ElementName=ListBox1}"
			VerticalAlignment="Center"/>
    </Intersoft:FieldLabel>
    <Intersoft:FieldLabel Header="Selected Item: " HeaderWidth="100"
			HorizontalHeaderAlignment="Right">
        <TextBlock Text="{Binding SelectedItem.Content, ElementName=ListBox1}"
			VerticalAlignment="Center"/>
    </Intersoft:FieldLabel>
    </StackPanel>
    <StackPanel HorizontalAlignment="Right" VerticalAlignment="Center" Width="250">
        <ListBox x:Name="ListBox2" ItemsPanel="{StaticResource ItemsPanelTemplate2}">
                <ListBoxItem Content="To-do: Fix Bug #1337"/>
                <ListBoxItem Content="To-do: Enhance Drag Drop Logic"/>
                <ListBoxItem Content="To-do: Create Sample"/>
        </ListBox>
        <Intersoft:FieldLabel Header="Selected Index: " HeaderWidth="100"
					HorizontalHeaderAlignment="Right">
                <TextBlock Text="{Binding SelectedIndex, ElementName=ListBox2}"
					VerticalAlignment="Center"/>
        </Intersoft:FieldLabel>
        <Intersoft:FieldLabel Header="Selected Item: " HeaderWidth="100"
					HorizontalHeaderAlignment="Right">
                <TextBlock Text="{Binding SelectedItem.Content, ElementName=ListBox2}"
					VerticalAlignment="Center"/>
        </Intersoft:FieldLabel>
    </StackPanel>
</Grid>

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.

Code Block
titleXAML
languagexml
<Intersoft:UXStackPanel HorizontalAlignment="Center"
			VerticalAlignment="Center" AllowReorderItem="True"
			ShadowInit="UXStackPanel_ShadowInit">
        <StackPanel>
                <Image Source="folder.png" Height="64" Width="64"/>
                <TextBlock Text="My Archive" HorizontalAlignment="Center"
					VerticalAlignment="Center"/>
        </StackPanel>
        <StackPanel>
                <Image Source="folder.png" Height="64" Width="64"/>
                <TextBlock Text="My Photos" HorizontalAlignment="Center"
					VerticalAlignment="Center"/>
        </StackPanel>
        <StackPanel>
                <Image Source="folder.png" Height="64" Width="64"/>
                <TextBlock Text="My Videos" HorizontalAlignment="Center"
					VerticalAlignment="Center"/>
        </StackPanel>
</Intersoft:UXStackPanel>
Code Block
titleC#
languagec#
private void UXStackPanel_ShadowInit(object sender,
	Intersoft.Client.UI.Controls.Interactivity.DragDropShadowEventArgs e)
{
    Image originalShadow = e.ShadowObject as Image;
    Image image = new Image() { Source = originalShadow.Source };
    image.Height = originalShadow.ActualHeight;
    image.Width = originalShadow.ActualWidth;
    Border shadow = new Border();
    shadow.BorderThickness = new Thickness(1);
    shadow.BorderBrush = new SolidColorBrush(Color.FromArgb(255, 0, 0, 0));
    shadow.Child = image;
    e.ShadowObject = shadow;
}

Definition

public abstract class UXPanel : ISPanel

...

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.

...