Dock Settings

Dock.Settings exposes global properties and constants that control drag and drop behavior. Use these when you need to adjust interaction distances or override the default templates.

Attached properties

DockProperties defines several attached properties that can be applied to any Avalonia control. They are used by the default control templates but you can set them manually:

Property	Type	Description
`IsDockTarget`	`bool`	Marks a control as a docking surface that can display a `DockTargetBase` adorner.
`IsDragArea`	`bool`	Identifies a region that allows starting a drag.
`IsDropArea`	`bool`	Identifies a region that can accept dropped dockables.
`IsDragEnabled`	`bool`	Globally enables or disables dragging for child dockables.
`IsDropEnabled`	`bool`	Globally enables or disables dropping of dockables.
`ShowDockIndicatorOnly`	`bool`	Shows only drop indicators, hiding the dock target visuals.
`IndicatorDockOperation`	`DockOperation`	Sets the dock operation when showing indicators only.
`DockAdornerHost`	`Control`	Hosts the dock target adorner instead of the adorned control.
`DockGroup`	`string`	Restricts docking to matching groups (inherited).

Use DockGroup to restrict docking operations across your layout. For details see Docking groups.

Example disabling drag and drop for an entire window:

<Window xmlns:dockSettings="clr-namespace:Dock.Settings;assembly=Dock.Settings"
        dockSettings:DockProperties.IsDragEnabled="False"
        dockSettings:DockProperties.IsDropEnabled="False">
    <DockControl />
</Window>

Drag thresholds

DockSettings contains two public fields controlling how far the pointer must move before a drag operation begins:

DockSettings.MinimumHorizontalDragDistance = 4;
DockSettings.MinimumVerticalDragDistance = 4;

Increase these values if small pointer movements should not initiate dragging.

Global docking

IDock.EnableGlobalDocking controls whether dockables can be dropped onto a specific dock from outside its current dock control. This is useful for creating multi-window applications where you can drag dockables between windows. Each dock can individually control whether it accepts global docking operations, with the default being enabled (true).

Inheritance

The EnableGlobalDocking property is inherited down the dock hierarchy. When evaluating whether global docking should be allowed for a target dock, the system walks up the ownership chain checking all ancestor docks. If any ancestor dock has EnableGlobalDocking = false, global docking is disabled for the entire subtree.

This allows you to disable global docking for a large section of your docking layout by setting it to false on a parent dock. For example:

// Disable global docking for an entire window/section
var parentDock = new ProportionalDock 
{ 
    EnableGlobalDocking = false 
};

// All child docks inherit the disabled setting
var childDock = new ToolDock 
{ 
    Owner = parentDock,
    EnableGlobalDocking = true  // This is overridden by parent's false
};

Note: the previous global setting and AppBuilder extension for enabling/disabling global docking have been removed. Use the per-dock IDock.EnableGlobalDocking property instead.

DockSettings.GlobalDockingProportion controls the split ratio used when a dockable is dropped as a global dock target (for example, dropping into a different window). The default value is 0.5.

DockSettings.GlobalDockingPreset controls how global docking decisions are made. The default value is DockGlobalDockingPreset.GlobalFirst.

DockGlobalDockingPreset.LocalFirst:
- Uses legacy local-first operation selection.
- Resolves global target from the immediate drop context.
DockGlobalDockingPreset.GlobalFirst:
- Uses global-first operation selection when a global target is active.
- Resolves global target to the outermost global target in the owner chain.

Example:

DockSettings.GlobalDockingPreset = DockGlobalDockingPreset.GlobalFirst;
DockSettings.GlobalDockingProportion = 0.33;

Set these before docking interactions start (typically during app startup).

Floating window owner

DockSettings.UseOwnerForFloatingWindows keeps floating windows above the main window by setting it as their owner. This is applied when IDockWindow.OwnerMode is DockWindowOwnerMode.Default and can be overridden per window.

The default owner lookup supplies a title and icon only when the floating host has no value for those properties. Explicit values, styles and live bindings remain in control of the floating window's title and icon.

DockSettings.FloatingWindowOwnerPolicy provides an explicit global owner policy (Default, AlwaysOwned, NeverOwned). When set to Default, Dock falls back to UseOwnerForFloatingWindows to preserve compatibility.

DockSettings.DefaultFloatingWindowOwnerMode defines which owner strategy to use when a floating window has IDockWindow.OwnerMode = DockWindowOwnerMode.Default.

Example:

// Use the root dock window as the owner when OwnerMode is Default.
DockSettings.DefaultFloatingWindowOwnerMode = DockWindowOwnerMode.RootWindow;

You can set the same behavior through the app builder:

AppBuilder.Configure<App>()
    .UsePlatformDetect()
    .UseDefaultFloatingWindowOwnerMode(DockWindowOwnerMode.RootWindow);

Close floating windows with the main window

DockSettings.CloseFloatingWindowsOnMainWindowClose controls whether Dock closes floating windows when the main (non-host) window is closing.

Example:

DockSettings.CloseFloatingWindowsOnMainWindowClose = true;

App builder example:

AppBuilder.Configure<App>()
    .UsePlatformDetect()
    .CloseFloatingWindowsOnMainWindowClose(true);

Floating window host mode

DockSettings.FloatingWindowHostMode controls whether floating windows are hosted as native OS windows or managed in-app windows. Default defers to DockSettings.UseManagedWindows.

Floating dock adorners

DockSettings.UseFloatingDockAdorner enables showing drop indicators in a transparent floating window instead of overlays on the target controls. See Floating Dock Adorners for details.

Pinned dock windows

DockSettings.UsePinnedDockWindow shows auto-hidden dockables inside a floating window instead of sliding panels. See Pinned Dock Window for details.

Managed windows

DockSettings.UseManagedWindows hosts floating windows inside the main window using the managed window layer. This affects only floating docks; the main window remains native. See Managed windows guide for details.

IRootDock.FloatingWindowHostMode can override the host mode for a specific root dock.

Window magnetism

DockSettings.EnableWindowMagnetism toggles snapping of floating windows. The snap distance is controlled by DockSettings.WindowMagnetDistance.

Bring windows to front on drag

DockSettings.BringWindowsToFrontOnDrag determines whether all floating windows and any main window hosting a DockControl are activated when dragging begins. Enabled by default.

Drag preview

DockSettings.ShowDockablePreviewOnDrag toggles whether the drag preview window renders the full dockable layout instead of only the title/status badge.

A factory can implement IDockDragPreviewPolicy to choose this independently for each workspace or dockable. ShowDockablePreviewOnDrag(IDockable) takes precedence over the global setting in both native windows and managed overlays. Factories without the policy retain the global default. The policy is evaluated when a drag preview opens; changing it affects the next drag.

Content previews capture registered visuals for documents, tools and whole panes, including their custom templates, without reparenting live controls. The image is captured once at the source display's scale, before tab selection or source layout changes, and released when the drag ends. This keeps the dragged content visible even when the source control is recycled for another tab. When no attached visual is registered, Dock retains its data-template fallback.

DockSettings.DragPreviewOpacity controls the preview window opacity (0.0 to 1.0).

During a move drag, a collapsible tool/document pane is temporarily omitted from proportional layout once the drag threshold is crossed. The remaining panes reflow before hit-testing and highlighting a drop target. Dragging one tab out of a group retains the group's space, hides the dragged tab and temporarily selects a remaining tab; dragging the whole group vacates the pane.

Pane reflow changes only visual arrangement. Tab previews use normal active-tab selection, including its selection notifications, so custom and cached-content templates display the remaining tab. Ownership, tab order and saved proportions remain unchanged until the drop commits; no add/remove/close events are raised. Cancellation restores the previous tab selection unless the application changed it during the drag. Escape, capture loss, docking being disabled, or an invalid non-floating drop restores the original arrangement. Copy/swap operations retain the source arrangement. Layouts with unsupported containers or application constraints that cannot be projected keep the existing preview behavior. No theme/template changes are required.

ItemsSource unregister synchronization

DockSettings.UpdateItemsSourceOnUnregister controls whether closing an ItemsSource-generated document/tool attempts to remove the source item from the backing collection (when it implements IList). The default is true.

Per-dock overrides are available through:

DocumentDock.CanUpdateItemsSourceOnUnregister
ToolDock.CanUpdateItemsSourceOnUnregister

When a per-dock value is null, Dock uses the global DockSettings value.

Selector hotkeys

Dock exposes a document and panel selector that can be toggled with keyboard gestures:

DockSettings.SelectorEnabled = true;
DockSettings.DocumentSelectorKeyGesture = new KeyGesture(Key.Tab, KeyModifiers.Control);
DockSettings.ToolSelectorKeyGesture = new KeyGesture(Key.Tab, KeyModifiers.Control | KeyModifiers.Alt);

Disable SelectorEnabled to turn off the overlay entirely.

Dockables can also opt out or provide a custom label for the selector:

document.ShowInSelector = false;
document.SelectorTitle = "Runtime Config";

See Selector overlay for behavior and navigation details.

Command bar merging

Command bar merging is disabled by default. Enable it and choose a scope:

DockSettings.CommandBarMergingEnabled = true;
DockSettings.CommandBarMergingScope = DockCommandBarMergingScope.ActiveDocument;

See Command bars for definitions and merge behavior.

Diagnostics logging

Enable verbose diagnostics logging when you need to inspect docking workflows:

DockSettings.EnableDiagnosticsLogging = true;
DockSettings.DiagnosticsLogHandler = message => Debug.WriteLine(message);

When enabled, Dock writes internal messages to DiagnosticsLogHandler if provided, otherwise it uses standard debug output.

You can also emit your own messages through DockLogger. For details and examples see Diagnostics logging.

App builder integration

You can configure the settings when building your Avalonia application:

using Dock.Settings;

AppBuilder.Configure<App>()
    .UsePlatformDetect()
    .UseFloatingDockAdorner()
    .UseOwnerForFloatingWindows()
    .UseDefaultFloatingWindowOwnerMode(DockWindowOwnerMode.RootWindow)
    .UseManagedWindows()
    .CloseFloatingWindowsOnMainWindowClose()
    .EnableWindowMagnetism()
    .SetWindowMagnetDistance(16)
    .BringWindowsToFrontOnDrag()
    .ShowDockablePreviewOnDrag()
    .SetDragPreviewOpacity(0.6)
    .UpdateItemsSourceOnUnregister(true)
    .WithDockSettings(new DockSettingsOptions
    {
        MinimumHorizontalDragDistance = 6,
        DefaultFloatingWindowOwnerMode = DockWindowOwnerMode.RootWindow,
        CloseFloatingWindowsOnMainWindowClose = true
    });

DockSettingsOptions reference

DockSettingsOptions mirrors DockSettings and lets you override individual values when calling WithDockSettings. Any property left as null keeps the current DockSettings value.

Option	Applies to	Description
`MinimumHorizontalDragDistance`	`DockSettings.MinimumHorizontalDragDistance`	Horizontal drag threshold.
`MinimumVerticalDragDistance`	`DockSettings.MinimumVerticalDragDistance`	Vertical drag threshold.
`UseFloatingDockAdorner`	`DockSettings.UseFloatingDockAdorner`	Floating adorner window.
`UsePinnedDockWindow`	`DockSettings.UsePinnedDockWindow`	Floating pinned dock window.
`UseManagedWindows`	`DockSettings.UseManagedWindows`	Managed floating windows.
`FloatingWindowHostMode`	`DockSettings.FloatingWindowHostMode`	Native vs managed floating host mode selection.
`UseOwnerForFloatingWindows`	`DockSettings.UseOwnerForFloatingWindows`	Assign owners to floating windows.
`FloatingWindowOwnerPolicy`	`DockSettings.FloatingWindowOwnerPolicy`	Global owner policy for floating windows.
`DefaultFloatingWindowOwnerMode`	`DockSettings.DefaultFloatingWindowOwnerMode`	Owner strategy used when a window OwnerMode is `Default`.
`EnableWindowMagnetism`	`DockSettings.EnableWindowMagnetism`	Snap floating windows.
`WindowMagnetDistance`	`DockSettings.WindowMagnetDistance`	Snap distance in pixels.
`BringWindowsToFrontOnDrag`	`DockSettings.BringWindowsToFrontOnDrag`	Activate windows when dragging.
`CloseFloatingWindowsOnMainWindowClose`	`DockSettings.CloseFloatingWindowsOnMainWindowClose`	Close floating windows when the main window closes.
`ShowDockablePreviewOnDrag`	`DockSettings.ShowDockablePreviewOnDrag`	Render dockable content in drag preview.
`DragPreviewOpacity`	`DockSettings.DragPreviewOpacity`	Opacity for the drag preview window.
`UpdateItemsSourceOnUnregister`	`DockSettings.UpdateItemsSourceOnUnregister`	Sync close/unregister of generated items back to source collections.
`SelectorEnabled`	`DockSettings.SelectorEnabled`	Toggle selector overlay.
`DocumentSelectorKeyGesture`	`DockSettings.DocumentSelectorKeyGesture`	Document selector shortcut.
`ToolSelectorKeyGesture`	`DockSettings.ToolSelectorKeyGesture`	Tool selector shortcut.
`CommandBarMergingEnabled`	`DockSettings.CommandBarMergingEnabled`	Enable command bar merging.
`CommandBarMergingScope`	`DockSettings.CommandBarMergingScope`	Merge scope for command bars.

GlobalDockingPreset is currently configured directly on DockSettings rather than through DockSettingsOptions.

Hide on close

FactoryBase exposes two properties that control whether closing a tool or document hides it instead of removing it. Hidden items can be restored through the factory helpers:

var factory = new MyFactory
{
    HideToolsOnClose = true,
    HideDocumentsOnClose = true
};

Both options are disabled by default. When enabled the CloseDockable command moves the dockable to the IRootDock.HiddenDockables collection instead of deleting it.

Prevent closing the last dockable

Each dock exposes a CanCloseLastDockable property. When set to false the CloseDockable command ignores requests that would remove the final visible item from that dock.

For more details on dockable properties see Dockable Property Settings.

Custom edge docking zones

For themes using stretched transparent edge selectors, set GlobalDockTarget.EdgeHitTestThickness to the maximum outer-edge hit thickness in DIPs (for example, 20). The effective zone is also capped at one fifth of the hovered pane's width or height, leaving local docking targets reachable in narrow panes. The pane is resolved from DockAdornerHost or the nearest IsDockTarget ancestor, so hovering a small tab/header does not shrink the outer zone. Local selector templates should use proportional regions without fixed insets that can consume the whole pane. Outer docking still targets the layout root; GlobalDockingPreset need not change.

The default NaN preserves existing template-defined hit areas, so stock docking buttons and themes require no changes. This option only restricts existing edge selectors; it does not enlarge or reposition them. Selector rectangles are tested in the adorned pane's coordinate space, including when an unclipped projected preview extends beyond that pane. Keep local selector regions measured while global highlighting is active; hide only the local highlight visuals.

Escape cancels an active dock drag even when keyboard focus is outside its DockControl or capture has transferred to another host. It restores the source preview layout and clears the pending drop; later pointer release cannot commit it. The keyboard handler is removed when the drag ends.

Table of Contents

Dock Settings

Attached properties

Drag thresholds

Global docking

Inheritance

Floating window owner

Close floating windows with the main window

Floating window host mode

Floating dock adorners

Pinned dock windows

Managed windows

Window magnetism

Bring windows to front on drag

Drag preview

ItemsSource unregister synchronization

Selector hotkeys

Command bar merging

Diagnostics logging

App builder integration

DockSettingsOptions reference

Hide on close

Prevent closing the last dockable

Custom edge docking zones