Lifecycle and Docking Management

The lifecycle of a docking window includes its creation, specifying initial size and/or size restrictions, providing a default open location, opening, moving to various states, docking to various locations, closing, and destruction. This topic covers how to perform all of those operations.

Tool Windows vs. Document Windows

Tool and document windows are the two varieties of docking windows that exist in the Docking/MDI product. While they both share many capabilities, they have several functional differences, and you should choose to use the appropriate kind based on your UI needs.

Tool windows are capable of being docked outside of MDI, auto-hidden to the side of a dock host, or used in the MDI area. They have no out-of-the-box restrictions on where they can go. Tool windows are typically used for scenarios where the docking window needs to support all those state locations or needs to frequently be closed and reopened. They remain registered with the dock site after they are closed, and thus can be readily reopened into the layout in their previous locations.

Document windows on the other hand can only be used within the MDI area. Since document windows are intended to have a limited lifetime, they are destroyed (unregistered from the dock site) by default when they are closed. See a section below for information on altering this behavior. Document windows are typically used for scenarios where the docking window is no longer needed after it is closed.

Creation and Destruction

When a DockingWindow has been associated with a DockSite, it is considered created. Note that at this time it may not yet be opened (accessible in the user interface).

After a docking window ceases to be managed by a DockSite, it is considered destroyed.

While being tracked by a DockSite, tool windows will be contained in its ToolWindows collection and document windows will be contained in its DocumentWindows collection.

Creating Tool Window

Use this code to create a tool window. Always use a constructor that accepts a DockSite parameter since this associates the tool window with that DockSite.

TextBox tb = new TextBox();
tb.BorderThickness = new Thickness(0);
ToolWindow window = new ToolWindow(dockSite, "MyToolWindow1", "My First Tool Window",
	new BitmapImage(new Uri("/Resources/Images/Properties16.png", UriKind.Relative)), tb);

When using the constructor in the example above, the first parameter is the DockSite that will manage the window.

The second is the value to be assigned to the Name property.

The third and fourth parameters are the title text and ImageSource respectively that will be displayed in the UI for the tool window.

The final parameter is the content that will be placed in the tool window.

Creating Document Windows

Use this code to create a document window. Always use a constructor that accepts a DockSite parameter since this associates the document window with that DockSite.

TextBox tb = new TextBox();
tb.BorderThickness = new Thickness(0);
DocumentWindow window = new DocumentWindow(dockSite, "MyDocumentWindow1", "My First Document Window",
	new BitmapImage(new Uri("/Resources/Images/TextDocument16.png", UriKind.Relative)), tb);

The same notes above regarding constructor parameters apply to document windows as well with one exception. Since document windows are not normally serialized with a layout, the Name parameter is not important to pass and may be null.

Destroying Docking Windows

Both tool and document windows may be destroyed by calling the DockingWindow.Destroy method.

This closes them out of the UI (if currently open) and removes them from their managing DockSite.

Preventing Document Windows from Auto-Destroying on Close

By default, document windows are only alive while open and will destroy themselves after being closed. This is the default because normally once a document is closed, it is no longer needed unless the end user specifically chooses to open it again, which may or may not ever occur.

You can alter this behavior by changing the DockSite.AreDocumentWindowsDestroyedOnClose property to false. When false, document windows will continue to be associated with the DockSite and will remain within its DocumentWindows collection, allowing them to be retrieved for later reopening.

Opening and Closing

When open, a docking window is accessible in the user interface. When closed, it is not.

Opening Docking Windows

Docking windows aren't added to the user interface until specifically opened. A call to the DockingWindow.Open method will restore the docking window to its previous state and location, if known. If the docking window doesn't have a prior location breadcrumb available, it will be restored to a default location based on its property settings.

Setting the IsOpen property to true is the same as calling the parameterless Open method. This property can be bound to in MVVM scenarios.

Closing Docking Windows

Docking windows can be removed from the user interface by a call to their DockingWindow.Close method.

Setting the IsOpen property to false is the same as calling the Close method. This property can be bound to in MVVM scenarios.

When closed, tool windows remain in the DockSite.ToolWindows collection until destroyed. However, when document windows are closed, by default they will be destroyed as well unless the DockSite.AreDocumentWindowsDestroyedOnClose property is set to false.

Activating and Focusing

Activating is a superset of the Open functionality. When the DockingWindow.Activate method is called, if the docking window is currently closed, it will be opened. Additionally, if it is open but in a tabbed scenario where it is not the selected tab, its tab will be selected.

The Activate method also has an overload for whether to set focus to the docking window's content.

Setting the IsActive property to true is the same as calling the parameterless Activate method. This property can be bound to in MVVM scenarios.

The LastActiveDateTime property is updated every time the docking window is activated, either programmatically or by focus moving within it. Sorting docking windows by this property value allows you to determine the sequence in which the docking windows were last active.

The DockSite.ActiveWindow tracks the currently active window. This property changes whenever a different docking window gains focus, and the DockSite.WindowActivated event is raised in response.

Default Initial Size

Docking windows default to a desired initial size of 200,200. Sometimes you may wish to set a different default initial size for docking windows. This can be done by using the DockingWindow.ContainerDockedSize property.

This example shows the property being set that will request that the ToolWindow have an initial size of 300, 150:

... <docking:ToolWindow Title="Wide" ContainerDockedSize="300,150"> ...

Minimum and Maximum Size

Docking windows default to a minimum size of 30,30 and a maximum size of positive infinity. Sometimes you may wish to designate some restrictions on size, such as a tool window's container should always try to be a minimum of 180 high. This can be done by using the DockingWindow.ContainerMinSize and ContainerMaxSize properties.

This example shows how to request a minimum container height of 180:

... <docking:ToolWindow Title="Min Height" ContainerMinSize="30,180"> ...

By setting the minimum size to the same thing as the maximum height, you can achieve a fixed size. This example shows how to request a fixed container height of 180:

... <docking:ToolWindow Title="Fixed Height" ContainerMinSize="30,180" ContainerMaxSize="10000,180"> ...

Default Locations

When a docking window is opened via calling its DockingWindow.Open method or by setting the IsOpen property to true, it will first attempt to restore to a previous location where a related breadcrumb was left. If no breadcrumb is found, it will restore to a default location instead.

This is how a default location is determined:

• First, if a WindowGroupName value is specified, the docking window will try to find another open docking window that has the same window group name.

• Second, the DockingWindow.DefaultLocationRequested event is raised with the DockingWindowDefaultLocationEventArgs.Target property initialized to the docking window found in the same window group, if any.

• Third, the DockSite.WindowDefaultLocationRequested event is raised with the same event arguments.

• Both of these events allow you to programmatically indicate the window should float (and optionally a specific floating location), or alternatively customize where the default location for the window will be. You can indicate a dock target and optional side around which it should dock. Passing null as the side will trigger an attach.

• If a dock target isn't set by an event handler, the docking window will fall back to opening in a default side specified by the ToolWindow.DefaultDockSide property. If an existing root level container is found at that side, the docking window will attach to that container.

Programmatically Changing States and Docking

It's very easy to move document and tool windows to anywhere in the layout programmatically.

State Change and Docking Members

The DockingWindow class has a number of methods that make it easy to programmatically move a docking window to another state.

The ToolWindow class defines additional methods that can be used to move a tool window to any state at either a default or target location.

The DocumentWindow class defines additional methods that can be used to move a document window to a target location.

Example: Docking to the Top of a Target

In this example we will dock the solutionExplorerToolWindow to the top of the propertiesToolWindow.

solutionExplorerToolWindow.Dock(propertiesToolWindow, Side.Top);

Example: Creating a Tabbed Group

In this example we will create a tabbed group of tool windows by "attaching" the solutionExplorerToolWindow to the propertiesToolWindow.

solutionExplorerToolWindow.Attach(propertiesToolWindow);

Example: Floating to a Location

In this example we will float the solutionExplorerToolWindow to a particular location.

solutionExplorerToolWindow.Float(new Point(100, 100));

Example: Floating and sizing to fit content

In this example we will float the solutionExplorerToolWindow to its previous location and have it size-to-content.

solutionExplorerToolWindow.SizeToContentModes = SizeToContentModes.Floating;
solutionExplorerToolWindow.Float();

Determining the Location of a Tool Window in Relation to the Workspace

The ToolWindow class has a GetCurrentSide method that returns a Side specifying where the tool window currently is in relation to the workspace, if one is in use.

If the tool window is open in a Document state, null is returned. If the tool window is open in an AutoHide state, a Side indicating the auto-hide dock side is returned. If the tool window is open in a Docked state and a workspace is in use in the dock site (no tool window inner-fill), a Side indicating the location of the tool window relative to the workspace is returned. If the tool window is open in a Docked state and the containing dock host does not has a workspace (tool window inner-fill is active), a Side indicating the location of the tool window's midpoint relative to the dock host's bounds is returned. Otherwise, if the tool window is closed, null is returned.

Programmatically Starting a Drag

It is possible to programmatically start a drag operation on DocumentWindow, ToolWindow, or ToolWindowContainer, by calling the associated DragMove method.

The only requirements are that the DocumentWindow/ToolWindow be registered with a DockSite and that the left mouse button be pressed when the method is called. This means that the method can even be called on windows that are not currently selected, in the auto-hide state, or in a standard MDI host. Also note that a InputPointerButtonEventArgs must be passed so that the related pointer can be captured.

In this example we trigger a programmatic drag on a tool window in the window variable from within an event handler for its primary pointer button being down:

window.DragMove(new InputPointerButtonEventArgs(e, InputPointerButtonKind.Primary));

Splitter Drag Kinds

Live splitting is enabled by default, meaning that when a splitter is dragged, the surrounding containers will immediately resize. This feature can be turned off by setting the DockSite.IsLiveSplittingEnabled property to false. When false, highlights are dragged instead, and the containers only resize when the splitter is dropped.

While the live splitting feature is desirable for most scenarios, if your docking window content has very complex element trees that don't measure/arrange fast, turning off live splitting will improve performance when the end user uses splitters.