Controlling Dock Operations

• Oct 29, 2020
• 4 minutes to read

This document describes how to respond to dock operations and cancel or disable them if necessary.

Disabling Dock Operations

Dock panels provide the DockPanel.Options property which contains a set of options to control dock operations on panels:

Option	Description
DockPanelOptions.AllowDockBottom	Specifies whether the dock panel can be docked to the bottom edge of a form (or user control).
DockPanelOptions.AllowDockFill	Specifies whether the dock panel can be docked to another dock panel.
DockPanelOptions.AllowDockLeft	Specifies whether the dock panel can be docked to the left edge of a form (or user control).
DockPanelOptions.AllowDockRight	Specifies whether the dock panel can be docked to the right edge of a form (or user control).
DockPanelOptions.AllowDockTop	Specifies whether the dock panel can be docked to the top edge of a form (or user control).
DockPanelOptions.AllowFloating	Specifies whether the dock panel can be floated.

These options allow you to prevent a panel from being docked at a specific position. However, they don’t provide full control of the docking functionality. For instance, even if a panel’s DockPanelOptions.AllowDockBottom option is set to false, this panel can still be docked to another panel which is docked to the bottom edge of the form.

To resolve this problem, set the panel’s DockPanelOptions.AllowDockFill option to false to prevent it from being docked to other panels, or handle the DockManager.Docking event. This event provides more flexibility to manage dock operations.

Responding to Dock Operations Performed by end-users

Unlike options described above, events provide full control over dock operations. The dock manager provides the following events that fire in response to dock operations being performed by end-users against dock panels, and these can be handled to implement your custom logic.

• DockManager.StartDocking

  Fires when an end-user starts to drag a panel. This event can be handled to cancel the dragging operation, if required.

• DockManager.Docking

  Fires when a panel is being hovered over a dock control (another panel or form), to which this panel will be docked if it’s dropped at its current position. The potential position of the panel within the target dock control is indicated with the frame. This event can be handled to prevent a panel from being docked to another panel (form), etc.

• DockManager.EndDocking

  Fires after the dock operation has been successfully completed or canceled. An end-user can cancel a dock operation by pressing the ESC key during dragging. This event only serves to provide a notification.

By default, an end-user can double-click any docked panel’s caption to float it. A subsequent double-click on the floating panel’s caption will restore it to its previous position. This feature can be disabled for all the panels by setting the dock manager’s BaseDockOptions.FloatOnDblClick option to false. To disable this feature for a specific panel, set the panel’s FloatOnDblClick option to false.

Example

The following example demonstrates how to prevent panels from being dragged from containers and from being docked to other panels. This also prevents end-users from destroying the existing container panels.

The DockManager.StartDocking and DockManager.Docking events are handled to restrict the dock operations.

C#

using DevExpress.XtraBars.Docking;

// Prevent a panel from being dragged from a container.
private void dockManager1_StartDocking(object sender, DockPanelCancelEventArgs e) {
   DockPanel parentPanel = e.Panel.ParentPanel;
      e.Cancel = parentPanel != null;
}

// Prevent a panel from being docked to another panel.
private void dockManager1_Docking(object sender, DockingEventArgs e) {
   e.Cancel = e.TargetPanel != null;
}

VB.NET

Imports DevExpress.XtraBars.Docking

' Prevent a panel from being dragged from a container.
Private Sub DockManager1_StartDocking(ByVal sender As Object, ByVal e As DockPanelCancelEventArgs) _
Handles DockManager1.StartDocking
   Dim parentPanel As DockPanel = e.Panel.ParentPanel
   e.Cancel = Not parentPanel Is Nothing
End Sub

' Prevent a panel from being docked to another panel.
Private Sub DockManager1_Docking(ByVal sender As Object, ByVal e As DockingEventArgs) _
Handles DockManager1.Docking
   e.Cancel = Not e.TargetPanel Is Nothing
End Sub