SandDock User Guide

Programmatic Control

Back to Table of Contents

Showing and Hiding Windows

Because SandDock by default allows the user to close any open tool window, your interface needs to provide a way for them to open them again. All windows support methods to do this with various degrees of control.

The easiest way of showing a window it using its Open() method. This will open the tool window at its last approximate position, and it equivalent to the Visual Studio functionality when you use the View menu. If a window cannot be opened at the exact position it was (i.e. its neighbour is no longer there) it will be opened in as close a position as possible. If the window is already visible but collapsed, it will pop up.

To programmatically hide a window, call its Close method. The window will be removed from view and depending on its CloseAction property, it may also be disposed.

Tracking Active Windows

SandDockManager exposes two events for tracking active windows. It is important you use these instead of the Enter and Leave events of your windows because those events do not take in to account floating windows.

The DockControlActivated event fires when the focus enters any window that is part of your layout, including tabbed documents. You can use this event to enable and disable parts of your user interface that correspond to individual windows; i.e. clipboard commands in the Edit menu. Visual Studio has this behaviour; all commands change availability depending on whether focus is in a document, your solution explorer, the properties window etc.

The ActiveTabbedDocumentChanged event is an easier way to keep track of your documents if your user interface is not complex enough to warrant changing command availability even when switching between tool windows. This is more like the traditional MDI paradigm, where commands are made available based simply on which child form had the focus last.

If you are using the DockControlActivated event to keep track of the active window, you may need to store a reference to the control passed to the method handling this event. If you are using the ActiveTabbedDocumentChanged event you can make a call to SandDockManager.ActiveTabbedDocument, which always stores the last tabbed document to have the focus. Be aware that if you have enabled floating documents (see Advanced Topics) this property may not be accurate and you should use DockControlActivated instead.

Remember that the user can close all windows if they like so your interface should support a state where no window is active.

Docking and Floating

The OpenDocked() method opens a window docked to one of the edges of your container, or in the middle. If the window is already docked in that position the method will simply return. If the window is already visible but collapsed, it will pop up.

The OpenFloating() method causes a window to undock from its existing parent and appear in a window floating above your container. If the window is already floating the method will simply return. You can optionally supply a rectangle in screen coordinates for the window to appear at.


There are three renderer classes supplied with SandDock. You can change the active renderer by assigning an instance of one of them to the Renderer property of your SandDockManager. If you change the renderer at runtime, you should always dispose of the old one afterwards.

You can inherit from any of the supplied renderers or even RendererBase to completely customise the way that SandDock draws its visual components. A detailed explanation of how to do this is beyond the scope of this document, but refer to the class library reference for documentation on each of the methods and properties you may want to override.

Layout Serialization

If you have a SandDock layout that your user will be customising at runtime, you will want to ensure their settings are saved between runs of your application. SandDockManager supports two methods for this, GetLayout and SetLayout. The former returns a string containing all information needed to reconstruct the current window layout, and should be called in the Closing event of your form. You can persist this string to any medium, but an XML file is common. The latter takes the string returned from GetLayout and restores the window positions, and should be called in the Load event of your form.

You may have windows whose state you do not want to persist, and in this case you can set their PersistState property to false. It is rare that you will need to do this, but you may have temporary windows showing in your user interface whose state is not important from one session to the next. This is an advanced property and is not shown in the property grid at design time.

Tabbed document layout is not persisted by default. Restoring a persisted SandDock layout will not affect your tabbed documents unless you set the SerializeTabbedDocuments property on your SandDockManager to true. If this is set, you need to make sure all your documents are created and have their Manager property set before calling SetLayout.

You can alternatively opt to load your windows as and when SandDock needs them in a call to SetLayout. For more details on this, see the Delay Loading Windows section in Advanced Topics.

Actions Menu

SandDock contains several means by which your user can activate a context menu relating to a given window. These include right-clicking on a window tab, clicking on the window options button, dragging a document tab to a non-docking area and pressing the Alt-Minus keyboard combination while focus is in the window. When any of these events occur, SandDock fires the ShowControlContextMenu event of your SandDockManager.

You should respond to this event in order to properly support accessibility - users need to be able to perform rudimentary docking in your interface without necessarily using the mouse. The method that handles the event is passed the relevant window and coordinates at which to show the menu. Your application is responsible for displaying and responding to menu items.

Next: Advanced Topics