WeiFen Luo’s DockPanelSuite is an open source window docking library for .NET Windows Forms. There are a lot of docking window solutions out there, but most are proprietary (and expensive), and DockPanelSuite is the only open source implementation I found that was decent. It suffers from one major problem though – lack of documentation.

A bit of history

In 2002, Microsoft added the docking panel layout to Visual Studio .NET. Many commercial components were built on top of it, but only in 2006 WeiFen Luo released the first version of his free DockPanelSuite on SourceForge. Several releases followed over the years, but the documentation always consisted of a description of the library’s features, and no concrete examples.

Danilo Corallo wrote an article on CodeProject in 2006, but the samples in it are no longer compatible with the current version of DockPanelSuite. Still, some people did manage to figure out how the library works, since SharpDevelop uses DockPanelSuite as its docking library.

WeiFen Luo has since moved on to other projects (one of them being a docking library for Windows Presentation Foundation), but others have taken over and the DockPanelSuite is still alive and available from GitHub. The latest stable release, DockPanel Suite v2.7, was released on 04 Sep 2012.

Setting up

Getting started with DockPanelSuite doesn’t require much. Download the latest version from GitHub here. Inside the ZIP archive, you’ll find a DLL named WeifenLuo.WinFormsUI.Docking.dll. Copy this to a fresh .NET Windows Forms Application project and create a reference to it:

Creating a reference to the DockPanelSuite DLL

The DockPanelSuite provides you with a bunch of classes as well as a UserControl, DockPanel. You’ll need to add this control to your Toolbox. In order to so, right-click on your Toolbox and select “Choose Items…”. This gives you a long list of .NET Framework Components already installed, or available through loaded assemblies. The DockPanel won’t be there yet, so use the “Browse…” button to find WeifenLuo.WinFormsUI.Docking.dll. Finally select the DockPanel component and make sure that the checkbox next to it is checked. The new UserControl will now be added to your Toolbox.

Adding WeiFen Luo’s DockPanel UserControl to your Toolbox

You’re now good to go to create your first DockPanelSuite-enabled application.

Recipe #0: First Steps

In your new Windows Forms Application, open your main form (Form1). Drag a new instance of the DockPanel UserControl onto it, and set its Docking to Fill. Make sure that the main form’s IsMdiContainer property is set to true, as this form will act as the container for all our other dockable windows:

Your main form must be an MDI container

Now create a new form (Form2). In the form code, change the base class from Form to DockContent:

using WeifenLuo.WinFormsUI.Docking;

namespace Forms
{
  public partial class Form2 : DockContent
  {
    public Form2()
    {
      InitializeComponent();
    }
  }
}

The DockContent class adds DockPanelSuite functionality to your forms. Create some additional forms so we’ll have some windows to dock.

Now to dock some windows! Add the following code to your main form’s constructor:

public Form1()
{
  InitializeComponent();
  Form2 f2 = new Form2();
  f2.Show(dockPanel, DockState.DockLeft);
  Form3 f3 = new Form3();
  f3.Show(dockPanel, DockState.DockRight);
  Form4 f4 = new Form4();
  f4.Show(dockPanel, DockState.Document);
}

Build and run your project, and you’ll get this:

Three docked windows in DockPanelSuite

You should now be able to drag the three windows around. Click and hold a window’s title bar, drag it, and DockPanelSuite will show you where it can be docked. In our current implementation, all windows can be docked anywhere – on the top, left, right or bottom, and grouped with any other window.

Docking a window

Recipe #1: Creating and docking a window

You’ve seen it in action above, but let’s recap. To create a docking window, do:

  • Set your main form’s IsMDIContainer to true;
  • Change the base class of your form to DockContent;
  • In your main form, create an instance of your DockContent form;
  • Call the DockContent’s Show method, indicating where it must dock.

The DockContent’s Show method takes an argument of type DockState which indicates where it must dock. The possible values are:

  • DockLeft, DockRight, DockTop, DockBottom` – Dock the window in the appropriate location
  • DockLeftAutoHide, DockRightAutoHide, DockTopAutoHide, DockBottomAutoHide – Dock the window in the appropriate location, and hide it (slide it up, showing only a tab)
  • Document – Place the window in the middle of the DockPanel, as a “Document”. You can create multiple documents this way, which will be shown with little tabs at the top. If you’re writing software that allows a user to edit multiple files at the same time, this will be what you need.
  • Float – Float the window above the MDI form. It can be docked anywhere by the user later.
  • Hidden – When you want to remove a dockable window from the MDI container, but not close it, you can hide it. This value cannot be used with the Show method.

Code:

Form5 f = new Form5();
f.Show(dockPanel, DockState.DockLeft);

Recipe #2: Hiding a Dockable Window

Suppose your application has a toolbox with frequently used items docked on the left. When the user clicks the “X” on the window, it will be closed. Still, you’d rather hide it, since there’s only once instance of this toolbox available during the lifetime of the application, and there’s no need to destroy and create it all the time.

By default, DockContent items are destroyed when they are closed. You can change this though:

Hiding on close

Select your DockContent instance (your dockable form), and find the “Docking” category in its properties. The DockContent parent class has added a number of properties to your form. Set the HideOnClose property to True, and your form will no longer be destroyed on closing. In fact, its Dockstate will be set to Hidden (see recipe #1).

End?

That’s it for now. I’ll be adding more recipes soon. Meanwhile, do post your needs in the comments and I’ll add the recipes you need.