Using the DragDropService in RadDock

Overview

The new docking framework introduces service-based semantic, which allows for granular and pluggable functionality per RadDock. Entire drag-and-drop functionality is handled by the registered DragDropService instance, which simply receives drag requests and instantiates the appropriate operation. The service is responsible for drop target hit-testing, displaying docking guides and docking hints as well as for processing user input while dragging is in progress.

On the screen above, toolWindow3 instance is being dragged. The service has hit-tested the MainDocumentContainer as a drop anchor and the appropriate docking guide is displayed. The “Left” docking position is selected and the service “hints” the user for the approximate position the panel would occupy after a successful “Commit” operation.

Drag-and-drop Modes

The service can operate in two modes: Immediate and Preview. The Immediate mode is the default one and it means that when a drag-and-drop operation is instantiated, the dragged window will be immediately detached from its current DockTabStrip and will become floating. On the contrary, in Preview mode the DockWindow will not be detached but rather a semi-translucent rectangle will be displayed, indicating the floating position it would take if the operation is committed. The major benefit of this new mode is that the operation is completely cancelable. The Preview mode is currently used by the framework at design-time. The following snippet demonstrates how to specify the desired mode:

DragDropService service = this.radDock1.GetService<DragDropService>();
service.DragDropMode = DragDropMode.Preview;
 
ToolWindow3 is being dragged and the service is in Preview mode. The semi-translucent rectangle indicates the floating bounds the window will occupy if the operation is committed.

Allowed Dock States

The service may be told which dock states are allowed to be hit-tested. For example we may exclude any floating window from hit-testing by simply specifying the following:

DragDropService service = this.radDock1.GetService<DragDropService>();
service.AllowedStates &= ~AllowedDockState.Floating;

Allowed Dock Manager Edges

The service may be told which edges of the owning RadDock instance are allowed for dock operation. The following example demonstrates how to set only top and bottom edges as allowed:

private void InitDragDropProperties()
{
    DragDropService service = this.radDock1.GetService<DragDropService>();
    service.AllowedDockManagerEdges = AllowedDockPosition.Top | AllowedDockPosition.Bottom;
}

Only Top and Bottom RadDock’s edges are available for drag-drop operation

Extending Service’s Behavior by Handling Events

The service exposes comprehensive set of events, which may be handled in order to provide completely custom behavior. Following is a brief overview of each event and what it may be used for:

1. Starting
Notifies that the service is about to start. The drag context is passed as an event argument, which allows listeners to examine it and optionally cancel undesired operation.

2. Started
Notifies for a successfully started DDO.

3. Stopping
Notifies that the service is about to stop. The Commit parameter is passed as an event argument, which allows listeners to examine it and to modify it or to prevent the service from stopping.

4. Stopped
Notifies that the service is successfully stopped.

5. Dragging
Notifies for a drag pass, performed upon each mouse move. Allows listeners to stop the DDO under some circumstances.

6. PreviewDropTarget
Allows listeners to examine and/or optionally modify the currently hit-tested drop target. For example this may be used to exclude certain panels from being hit-tested.

7. PreviewDockPosition
Allows listeners to examine and optionally modify the allowed dock position for the current drag operation. For example, here is right place to allow dock only bottom for a specific drop target.

8. PreviewHitTest
Allows for preview and/or modification of the generated hit-test result.

The following example demonstrates how to allow only DockPosition.Bottom for the MainDocumentContainer:

private void InitDragDropEvents()
{
    DragDropService service = this.radDock1.GetService<DragDropService>();
    service.PreviewDockPosition += new DragDropDockPositionEventHandler(service_PreviewDockPosition);
}
private void service_PreviewDockPosition(object sender, DragDropDockPositionEventArgs e)
{
    if (e.DropTarget == this.radDock1.MainDocumentContainer)
    {
        e.AllowedDockPosition = AllowedDockPosition.Bottom;
    }
}

Only DockPosition.Bottom is allowed for the MainDocumentContainer

Canceling Drag-and-drop Operation

A running drag-and-drop operation (DDO) may be easily canceled by either pressing the ESAPE key or manually, by calling the following method:

DragDropService service = this.radDock1.GetService<DragDropService>();
service.Stop(false);

The Boolean parameter determines whether the operation should be committed (applied) or not. Alternative way of canceling the operation is by handling the Starting or Dragging events and set the “Cancel” argument to true.


Well, that’s it. Enjoy yourself with the new service-based model, which allows you to implement virtually any drag-and-drop scenario. Stay tuned for more articles on some advanced techniques such as providing entirely custom service instance and extending base functionality by overriding virtual methods.