Docking Window Capabilities

One of the best features of Actipro Docking & MDI is the number of options that are available to you as a developer. Many options control the behaviors and capabilities of the docking windows and can be set at a global level as well as at a docking window instance level.

Global Default Options

A number of global default options appear on the DockSite and TabbedMdiHost classes. By default, docking windows will use these options unless their instance settings override them.

Member	Description
DockSite.AreDocumentWindowsDestroyedOnClose Property	Gets or sets whether document windows are automatically destroyed (removed from the `DockSite`) when closed. The default value is `true`.
DockSite.AreNewTabsInsertedBeforeExistingTabs Property	Gets or sets whether new tabs are inserted before existing tabs when they are added, such as when dragging and attaching a tool window to an existing tool window container. The default value is `true`.
TabbedMdiHost.CanDocumentsAttach Property	Gets or sets the global setting for whether documents may be attached to another document, creating a tabbed grouping. The default value is `true`.
TabbedMdiHost.CanDocumentsCloseOnMiddleClick Property	Gets or sets a value indicating whether documents can be closed by clicking the tab with the middle mouse button. The default value is `true`.
TabbedMdiHost.CanDocumentTabsDrag Property	Gets or sets the global setting for whether document tabs may be dragged to another location. The default value is `true`.
DockSite.CanDocumentWindowsClose Property	Gets or sets the global setting for whether document windows can be closed. The default value is `true`.
DockSite.CanToolWindowsDragToFloatingDockHostsWithWorkspaces Property	Gets or sets the global setting for whether tool windows may be dragged to floating dock hosts that contain a workspace. The default value is `true`. When `false`, tool windows can still be dragged and docked against floating dock hosts that only contain tool windows.
DockSite.CanDocumentWindowsDragToLinkedDockSites Property	Gets or sets the global setting for whether document windows may be dragged to a linked dock site. The default value is `true`.
DockSite.CanDocumentWindowsFloat Property	Gets or sets the global setting for whether document windows may be contained in a floating window. The default value is `false`.
DockSite.CanFloatingDockHostsHideOnDockSiteUnload Property	Gets or sets whether DockSite.FloatingDockHosts should hide when the `DockSite` is unloaded, such as in nested `DockSite` scenarios when the parent tab is deselected. The default value is `false`.
DockSite.CanToolWindowsAttach Property	Gets or sets the global setting for whether the end user can edit document window titles in-place when a document window tab is double-clicked. The default value is `true`.
DockSite.CanToolWindowsAutoHide Property	Gets or sets the global setting for whether tool windows may be placed in auto-hide mode. The default value is `true`.
DockSite.CanToolWindowsBecomeDocuments Property	Gets or sets the global setting for whether tool windows may be placed in a document state. The default value is `true`.
DockSite.CanToolWindowsClose Property	Gets or sets the global setting for whether tool windows can be closed. The default value is `true`.
DockSite.CanToolWindowsCloseOnMiddleClick Property	Gets or sets a value indicating whether tool windows can be closed by clicking the tab with the middle mouse button. The default value is `true`.
DockSite.CanToolWindowsDock Property	Gets or sets the global setting for whether tool windows can be docked. The default value is `true`.
DockSite.CanToolWindowTabsDrag Property	Gets or sets the global setting for whether tool window tabs may be dragged to another location. The default value is `true`.
DockSite.CanToolWindowsDragToLinkedDockSites Property	Gets or sets the global setting for whether tool windows may be dragged to a linked dock site. The default value is `true`.
DockSite.CanToolWindowsFloat Property	Gets or sets the global setting for whether tool windows may be floated into separate top-level containers. The default value is `true`.
DockSite.ClosePerContainer Property	Gets or sets the global setting for whether tool windows may be attached to another tool window, creating a tabbed grouping. The default value is `false`.
DockSite.ContainersHaveNewTabButtons Property	Gets or sets whether containers have new tab buttons. The default value is `false`.
DockSite.FloatingToolWindowContainersHaveMaximizeButtons Property	Gets or sets whether floating ToolWindowContainer controls can have title bar maximize buttons. The default value is `true`.
DockSite.FloatingToolWindowContainersHaveMinimizeButtons Property	Gets or sets whether floating ToolWindowContainer controls can have title bar maximize buttons. The default value is `false`.
DockSite.FloatingToolWindowContainerTitleBarDoubleClickMode Property	Gets or sets what happens when floating ToolWindowContainer controls' title bars are double-clicked. The default value is ToggleMaximized.
DockSite.HasTabCloseButtons Property	Gets or sets whether close buttons should appear on document tabs. The default value is `true`.
TabbedMdiHost.TabOverflowBehavior Property	Gets or sets the global setting for the overflow behavior of the document tabs. The default value is `TabOverflowBehavior.Menu`.
DockSite.IsDockGuideAnimationEnabled Property	Gets or sets whether dock guide animation is enabled. The default value is `true`.
DockSite.IsFloatingWindowSnapToScreenEnabled Property	Gets or sets whether floating windows are snapped onto the closest screen when displayed via a method other than being dragged. The default value is `true`.
DockSite.IsLiveSplittingEnabled Property	Gets or sets whether live splitting of docking windows is enabled. The default value is `true`.
DockSite.IsTabLayoutAnimationEnabled Property	Gets or sets whether animation effects are applied during tab layout, such as when tabs are added or removed. The default value is `true`.
TabbedMdiHost.TabStripPlacement Property	Gets or sets a Side indicating the side upon which the tabs are located. The default value is `Top`.
DockSite.ToolWindowsHaveCloseButtons Property	Gets or sets whether ToolWindowContainer controls can have title bar close buttons. The default value is `true`.
DockSite.ToolWindowsHaveOptionsButtons Property	Gets or sets whether ToolWindowContainer controls can have title bar options buttons. The default value is `true`.
DockSite.ToolWindowsHaveTitleBarIcons Property	Gets or sets the global setting for whether tool window title bars display the icon of the selected tool window. The default value is `false`.
DockSite.ToolWindowsHaveTitleBars Property	Gets or sets the global setting for whether tool windows display a title bar when not in MDI. The default value is `true`.
DockSite.ToolWindowsHaveToggleAutoHideButtons Property	Gets or sets whether ToolWindowContainer controls can have title bar toggle auto-hide buttons. The default value is `true`.
DockSite.ToolWindowsSingleTabLayoutBehavior Property	Gets or sets the global setting for the behavior used when a single tool window is in a container. The default value is `SingleTabLayoutBehavior.Hide`.
DockSite.ToolWindowsTabOverflowBehavior Property	Gets or sets the global setting for the overflow behavior of the tool window tabs. The default value is `TabOverflowBehavior.Shrink`.
DockSite.ToolWindowsTabStripPlacement Property	Gets or sets the global setting for the overflow behavior of the tool window tabs. The default value is `Bottom`.
DockSite.UseDragFloatPreviews Property	Gets or sets whether to use float previews when dragging windows instead of instantly creating floating windows. The default value is `false`.
DockSite.UseHostedFloatingWindows Property	Gets or sets whether floating windows should be hosted within the bounds of the dock site. The default value is `false`.
DockSite.UseHostedPopups Property	Gets or sets whether popups should be hosted within the bounds of the dock site. The default value is `true`.

Docking Window Instance Options

All of the global default options listed above will apply to docking windows by default. Related docking window instance options are all nullable booleans with default values of null, indicating that they will inherit the global defaults.

Member	Description
DockingWindow.CanAttach Property	Gets or sets whether the window may be attached to another window, creating a tabbed grouping.
ToolWindow.CanAutoHide Property	Gets or sets whether the tool window may be placed in auto-hide mode.
ToolWindow.CanBecomeDocument Property	Gets or sets whether the tool window may be placed in a document state.
DockingWindow.CanClose Property	Gets or sets whether the window may be closed.
DockingWindow.CanDock Property	Gets or sets whether the tool window may be docked.
DockingWindow.CanDragTab Property	Gets or sets whether the window's tab may be dragged to another location.
DockingWindow.CanDragToLinkedDockSites Property	Gets or sets whether the window may be dragged to a linked dock site.
DockingWindow.CanFloat Property	Gets or sets whether the window may be floated into a separate top-level container.
DockingWindow.CanSerialize Property	Gets or sets whether the window's layout information may be serialized.
DockingWindow.CanStandardMdiMaximize Property	Gets or sets whether the window may be maximized when hosted in a StandardMdiHost.
DockingWindow.CanStandardMdiMinimize Property	Gets or sets whether the window may be minimized when hosted in a StandardMdiHost.
ToolWindow.HasOptionsButton Property	Gets or sets whether the window has an options menu available.
ToolWindow.HasTitleBar Property	Gets or sets whether the window displays a title bar when docked.

How to Allow Tabs to Be Reordered, But Not Dragged Elsewhere

In some situations, you may wish to keep docking windows in their current container but still want to allow them to be reordered.

To accomplish this, turn all the appropriate options off such as CanDock and CanRaft, etc. but leave CanDrag on. This will allow the user to reorder tabs by dragging them within their container but will prevent the docking window from moving outside of the container.

Limiting the Allowed Dock Guides While Dragging

The DockSite.WindowsDragOver event is raised while dragging docking windows over a new drop target. This event is passed an instance of DockingWindowsDragOverEventArgs, which indicates the DockHost being dragged, the docking windows inside that DockHost, and the IDockTarget control that the pointer is currently over.

The DockingWindowsDragOverEventArgs.SupportedDockGuideKinds property lists the dock guide kinds (a DockGuideKinds flags enumeration value) that are supported with this particular combination and will be shown by default.

If you wish to prevent certain supported dock guides from being displayed, change the DockingWindowsDragOverEventArgs.AllowedDockGuideKinds property value. It defaults to the SupportedDockGuideKinds property value.

For instance, if you'd only like docking windows to be able to dock left, right, or center (attach), you could set the AllowedDockGuideKinds property to OuterLeft | InnerLeft | Center | InnerRight | OuterRight. Any values that you set to this property that aren't "supported" at the time will be ignored.

You can use complex logic to tailor the allowed dock guides based on your application design and its current state.

Magnetism

Magnetism allows floating windows to be "snapped" together when moving or resizing. This makes it easier for the end-user to line up the windows into rows or columns.

Magnetism can be configured using DockSite.MagnetismSnapDistance and DockSite.MagnetismGapDistance. The snap distance indicates the distance at which magnetism begins to snap windows being dragged. The gap distance indicates the distance between windows that are snapped together via magnetism. Magnetism can be disabled by setting the snap distance to 0.

Images on Tabs Option

The DockingWindow.ImageSource image can appear on docking window tabs when tab images are enabled. Several themes, such as the non-Metro themes, turn this feature on by default.

You can force the image to display on the tool window tabs by setting the DockSite.ToolWindowsHaveTabImages property to true, or on tabbed MDI tabs by setting the TabbedMdiHost.HasTabImages property to true.

Single Tab Layout Behavior

By default, when a ToolWindowContainer only has a single ToolWindow, then the tabs are hidden. This mimics the behavior seen in Visual Studio but can be customized. The tab for the single window can be hidden or shown.

The behavior can be customized using the DockSite.ToolWindowsSingleTabLayoutBehavior property, whose default value is Hide.

Screenshot

A ToolWindowContainer with a single window using Hide and Show behaviors

Tinting Tabs

Tabs can be tinted towards a color by setting the DockingWindow.TabTintColor property. The tab will have the same general visual appearance, but the colors will be skewed towards the tint color.

Screenshot

Several tinted tabs

Flashing Tabs

Tabs can enter a flashing mode by setting the DockingWindow.TabFlashMode property to either Blink or Smooth. The Blink mode will cause the tab to appear as flashing for a bit, then instantly restore it to normal for a bit, then appear as flashing for a bit, and so on until the mode is changed back to None. The Smooth mode will do a smooth transition between the flashing appearance and normal appearance.

The DockingWindow.TabFlashColor property specifies the color used to tint the tab for its flash effect.

Flashing is best used to grab the end user's attention and let them know that a tab should be clicked. Watch the DockSite.WindowActivated event to see when the docking window is activated. At that point, set the TabFlashMode property back to None to disable flashing.

ToolWindowContainer Title Font

The ToolWindowContainer control has several properties that can be set to alter its title font appearance:

Properties like these should never be set directly on specific instances of container controls since containers are created and destroyed dynamically at run-time with layout changes. Instead, if you wish to change these properties, use an implicit Style that targets ToolWindowContainer in your application's Resources:

<Style TargetType="docking:ToolWindowContainer">
	<Setter Property="TitleFontFamily" Value="Verdana" />
	<Setter Property="TitleFontSize" Value="14" />
	<Setter Property="TitleFontWeight" Value="Bold" />
</Style>

That implicit Style will update all instances of the container within your application.

In This Article