Log In
Home
Support
Demos
Documentation
Blogs
Training
Webinars
[Expand]General Information
[Collapse]WinForms Controls
  Prerequisites
 [Expand]What's Installed
 [Expand]Build an Application
 [Collapse]Controls and Libraries
  [Expand]Forms and User Controls
  [Expand]Messages, Notifications and Dialogs
  [Expand]Editors and Simple Controls
  [Expand]Ribbon, Bars and Menu
  [Expand]Application UI Manager
  [Collapse]Docking Library
   [Expand]Panels and Panel Containers
    Header Buttons
   [Collapse]Managing Dock Panels in Code
     Creating and Destroying Dock Panels
     Showing and Hiding Dock Panels
     Docking Panels Programmatically
     Controlling Dock Operations
     Controlling Resizing Operations
    Saving and Restoring the Layout of Dock Panels
   [Expand]Examples
  [Expand]Data Grid
  [Expand]Vertical Grid
  [Expand]Pivot Grid
  [Expand]Tree List
  [Expand]Chart Control
  [Expand]Diagrams
  [Expand]Gauges
  [Expand]Map Control
  [Expand]Scheduler
  [Expand]Spreadsheet
  [Expand]Rich Text Editor
  [Expand]Spell Checker
  [Expand]Form Layout Managers
  [Expand]Navigation Controls
  [Expand]Printing-Exporting
  [Expand]PDF Viewer
   Reporting
  [Expand]Snap
  [Expand]TreeMap Control
 [Expand]Common Features
  Get More Help
 [Expand]API Reference
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Document Server
[Expand]Reporting
[Expand]Report Server
[Expand]Dashboard
[Expand]eXpressApp Framework
[Expand]CodeRush
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation

Creating and Destroying Dock Panels

A dock panel is a control that can be docked to a form (or user control) or to other dock panels. This topic describes how dock panels can be created and destroyed via code. Please refer to the Dock Panels topic for basic information on dock panels.

This document contains the following subsections:

Expanded Creating Dock Panels

To create a docking application, you need to create the dock manager and dock panel(s). The dock manager component provides centralized control over the behavior of dock panels. Each dock panel must belong to a specific dock manager.

When a dock manager is created, its DockManager.Form property must be initialized (via the dock manager's constructor or directly). This property must refer to the form (or user control) which will display the dock panels owned by the dock manager. If this property is set to null no dock panels can be created. At design time when a dock manager is dropped onto a form, this property is automatically initialized.

To create dock panels the following methods can be used:

DockManager.AddPanel Creates and docks a panel on a form or makes it floating.
DockPanel.AddPanel Creates and docks a panel to another panel.

Expanded Creating and Docking Panels to the Form

Use the DockManager.AddPanel method to create a panel and dock it to the form or make it floating. The DockManager.AddPanel method takes a dock parameter of the DockingStyle type which specifies which side of the form the created panel is docked to.

Docking Style Description
DockingStyle.Float The panel will float.
DockingStyle.Fill The DockManager.AddPanel method will not create a panel. null is returned.

A dock panel cannot be created and docked to the form using the DockingStyle.Fill style, that is a panel cannot occupy the form entirely. It can only be docked to the form's edge or float. To create a control with the Fill dock style that will display other visual controls in the center of your form, you can use the System.Windows.Forms.Panel or XtraTabControl controls, for instance.

DockingStyle.Left, DockingStyle.Right, DockingStyle.Top, DockingStyle.Bottom The panel is docked to the corresponding edge of the form (user control).

Expanded Example 1

The following example demonstrates how to create a dock manager and a panel. The panel is docked to the top edge of the form.

The result is shown below:

Expanded Creating and Docking Panels to Other Panels

The DockPanel.AddPanel method can be used to create and dock a new panel to the current panel. Panels docked to other panels form split containers or tab containers. A split container is a dock panel which displays its child panels side by side (either vertically or horizontally). A tab container, which is also a dock panel, displays child panels within its tab pages. Unlike regular dock panels, which have no children, split and tab containers are created and destroyed automatically as a result of docking panels to and undocking them from other panels.

The DockPanel.AddPanel method's behavior is determined by the current panel's type:

  • If the DockPanel.AddPanel method is called for a regular (non-container) panel, this method will create a new split container which will contain the current panel and the newly created one.
  • If the DockPanel.AddPanel method is called for a split container or a tab container, it will append a new child to this container which will contain the newly created panel.
By default the DockPanel.AddPanel method creates a split container when it's called for a regular panel. To transform a split container into a tab container, the container's DockPanel.Tabbed property can be set to true. Similarly setting this property to false transforms the tab container into a split container. To access a container that owns a specific panel, the panel's DockPanel.ParentPanel can be used.

Expanded Example 2

The following code demonstrates how to create a split container by docking a panel to another panel and then transforming this container into a tab container.

In this code the container created is accessed via the DockPanel.ParentPanel property of panel1. The panel2.ParentPanel would give the same result since panel1 and panel2 both belong to the same container.

The result of this code is shown below:

Note that containers are automatically destroyed when they contain only one panel, for instance a container contains only two panels and one of these panels is undocked. In this case, the DockPanel.ParentPanel property of the container's children will return null immediately after the container is destroyed.

Expanded Adding Visual Controls to Dock Panels

Each dock panel has a caption and a client area within which visual controls can reside. If a dock panel serves as a split container or tab container, the client area displays the container's child panels.

If a dock panel is neither a split container nor a tab container, the panel's client area can display various visual controls (buttons, editors, tree views, etc). In this case, the dock panel's client area is represented by a control of the ControlContainer type and this can be accessed via the DockPanel.ControlContainer property. Use this property's Controls collection to maintain (add, remove or access) the visual controls displayed within the panel.

Expanded Example 3

In the following example a split container consisting of two dock panels is created. A PropertyGrid control is placed on the first panel, a ListBox control is placed on the second.

The image below shows the result of running the above code:

For performance reasons do not add visual controls to the dock panel's Controls collection. Instead add these controls directly to the Controls collection of the DockPanel.ControlContainer object.

Expanded Destroying Dock Panels

To destroy a specific panel, you can use the panel's Dispose method or, alternatively, call the dock manager's DockManager.RemovePanel method. When a panel is destroyed, all its child panels are destroyed as well. If a panel displays visual controls, they will also be destroyed.

Expanded Example 4

The following code destroys the currently active panel:

To remove a specific child from a container panel, you can use the DockPanel.RemovePanel method. This permits only a child of the container panel to be destroyed. If the panel passed as the method's parameter is not owned by the container panel, the panel will not be destroyed.

The dock manager's DockManager.Clear method allows you to destroy all the panels owned by the dock manager.

Expanded See Also

How would you rate this topic?​​​​​​​