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]ASP.NET Core 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]CodeRush Classic
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation

Docking Panels Programmatically

Dock panels can be docked to a form (user control), other dock panels or they can float. This topic describes how to perform these docking operations in code.

To find out how to create and destroy panels, and add visual controls to panels in code, see the Creating and Destroying Dock Panels document.

The Saving and Restoring the Layout of Dock Panels topic explains how to save and restore the layout of dock panels. This can be useful if you create dock panels via code or change the layout of dock panels and then wish to revert to the saved layout.

The current topic provides the following subsections:

Expanded Docking to a Form

Dock panels can be docked to the top, left, bottom or right edge of a form (or user control), but cannot occupy the form entirely. That is a panel's dock style cannot be set to Fill when it's residing within a form.

If you need to add a control (which has its dock style set to Fill) in order to display other visual controls in the center of your form, do not use a dock panel for this purpose. Use a System.Windows.Forms.Panel, System.Windows.Forms.TabControl or XtraTabControl control instead.

Dock panels can only reside within a form which is referred to by the dock manager's DockManager.Form property. This property must always refer to a valid form (user control), otherwise panels can't be created and docked.

You can use the following methods to dock a panel to a form:
DockManager.AddPanel Creates and docks a new panel to the form.

Usage: newPanel = dockManager1.AddPanel(dockStyle);

DockPanel.DockTo method overloads which takes a dock parameter of the DockingStyle type. Allow existing panels to be docked to the form.

Usage: panel.DockTo(dockStyle); panel.DockTo(dockStyle, index);

These methods take the dockStyle parameter which specifies how a panel is docked to the form. Set it to DockingStyle.Top, DockingStyle.Left, DockingStyle.Bottom or DockingStyle.Right to dock a panel to the corresponding edge.

Setting the dockStyle parameter to DockingStyle.Float will make the panel float. If dockStyle is set to DockingStyle.Fill a panel won't be created and an existing panel won't be moved to the new position.

For information on the index parameter see below.

 

Expanded Example 1

In the following code two panels are created and docked to the form's bottom and right edges respectively:

The result is shown below:

All the visible floating panels and panels docked to the form are called root panels and these can be accessed via the DockManager.RootPanels collection. Note that this collection doesn't include visible panels which are docked to other panels (tab containers or split containers).

Each panel in this collection is identified by a zero-based unique index which is specified by the DockPanel.Index property. It defines the panel's position within the DockManager.RootPanels collection.

For panels docked to the form, the panels' indexes also defines the layout of the panels within the form. Assuming that the collection doesn't include floating panels, the panels docked to the form are indexed as follows. The panel which occupies one of the form's edges entirely has the smallest index (0). Other panels can be docked only within the region not occupied by the first panel. A panel which occupies any edge of this region entirely has an index of 1, etc.

The DockManager.AddPanel method merely adds a new panel at the end of the DockManager.RootPanels collection.

Assume that in the above example the DockManager.RootPanels collection is empty before the panels are created and docked to the form. In this case panel1 will be added at the first position in the collection, it's index will be equal to 0, and it will occupy the edge it's docked to (the bottom edge) entirely. panel2 will have an index of 1 and will occupy the corresponding (right) edge within the region not occupied by the first panel.

The following image shows a more complex example of the layout of the panels within the form.

The index of Panel 3 is 2 and thus it is docked to the corresponding (right) edge of the region not occupied by Panel 1 and Panel 2.

The DockPanel.DockTo overload which takes the index parameter simply places the specified panel within the DockManager.RootPanels collection at the position specified by the index. This panel's DockPanel.Index will be set to the specified index. The indexes of the subsequent panels in the collection will be increased by 1. As a result, the panels will be re-arranged to reflect the changes.

Expanded Example 2

The following example shows how to dock an existing panel to the form at a specific position.

Assume that two dock panels are docked to the form as follows:

To dock panel3 so that it occupies the form's left edge entirely the DockPanel.DockTo overload can be used. It's dock parameter should be set to DockingStyle.Left and its index to 0.
The result is shown below:

To move a panel to a specific position amongst the other panels within the form without changing their docking styles, the DockPanel.Index property can be changed directly. This moves the panel within the DockManager.RootPanels collection and re-arranges the panels as a result.

 

Expanded Example 3

The following example shows how to change a panel's position within the form without changing the panel's docking style.

Consider the following layout of the panels:

Setting the index of Panel 3 to 1 will undock this panel from its previous position and will dock it within the region not occupied by the panels with lower indexes (the region not occupied by Panel 1 which has an index of 0). The docking style (DockingStyle.Bottom) of Panel 3 is not changed by this code.
The result is shown below:

Expanded Docking to Another Panel

When an end-user docks a panel to another panel using drag-and-drop operations, a tab container or split container is created depending upon the point at which the drag-and-drop ends. Docking a panel to another panel via code will also create one of these 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 tab pages. Tab containers and split containers are represented by DockPanel objects. Unlike regular dock panels, split and tab containers are created and destroyed automatically as a result of docking panels to and undocking them from other panels. The containers can display only child panels and cannot display any visual controls (buttons, labels, etc).

To dock a panel to another panel via code the following methods can be used:
DockPanel.DockTo overloads which take the panel parameter of type DockPanel. These methods can be used to form new split containers and to add panels to any existing split containers and tab containers.

Usage: currentPanel.DockTo(targetPanel); currentPanel.DockTo(targetPanel, index);

The targetPanel parameter specifies the target panel. If it refers to a regular panel (neither a split container, nor a tab container), a new split container will be created and this will contain the targetPanel and currentPanel. If targetPanel refers to a split container or a tab container, currentPanel is appended as a new child to this container.

The DockTo overload which takes the targetPanel and index parameters can be used to add the current panel at a specific position within the target container. See below for information on panels' indexes.

DockPanel.DockAsTab overloads. These allow panels to be organized into tab containers.

Usage: currentPanel.DockAsTab(targetPanel); currentPanel.DockAsTab(targetPanel, index);

If targetPanel doesn't represent a tab container, a new tab container will be created and this will contain targetPanel and currentPanel. If targetPanel is a tab container, currentPanel will be appended to this container.

The DockAsTab overload which takes the index parameter can be used to place the current panel within the target tab container at a specific position. See below for information on panels' indexes.

DockPanel.AddPanel Creates a new panel and docks it to the current panel.

Usage: newPanel = panel.AddPanel();

If panel represents a regular panel (neither a split container, nor a tab container), a new split container will be created and this will contain panel and newPanel.

If panel represents a container, newPanel will be appended as a child to this container.

The index parameter of the DockPanel.DockTo and DockPanel.DockAsTab overloads specifies a zero-based integer that points to the position which the current panel is moved to within the target container. If index is set to 0 the panel will be added as the first item amongst the target container's children. Set index to 1 to add the panel as the second item, etc. Setting the index parameter to -1 appends the panel to the container.

To get the panel's position within the container use the DockPanel.Index property. It matches the value of the index parameter.

The number of panels in a container is returned by the container's DockPanel.Count property.

To get the container that owns a specific panel, use this panel's DockPanel.ParentPanel property. The container's child panels can be accessed via the DockPanel.Item indexer. If a panel belongs to a specific container which in turn belongs to another container, etc, then the DockPanel.RootPanel property can be used to get the panel's primary parent container.

 

Expanded Example 4

The following code shows how a split container can be created that consists of three panels.

Assume that three panels (panel1, panel2 and panel3) are docked to a form:

The following code docks panel2 to panel1 and this forms a split container.
Notice that these two panels now have Maximize buttons which indicate that the panels are combined into a split container:

Next, panel3 is docked to the created container in the first position. To do this, the DockPanel.DockTo overload is used which takes the index parameter:
The result of this code is displayed in the following image:

Expanded Example 5

In the following example two panels are docked to each other so that they form a tab container. Before the code starts the panels are docked as follows:

The result is shown below:

For tab containers the Boolean DockPanel.Tabbed property returns true. This property can also be used to transform a split container into a tab container and vice versa.

 

Expanded Example 6

In the following code a split container is created and then it is transformed into a tab container.

Assume that the panel1 and panel2 panels are docked to a form as follows:

In the following code the panels are combined into a split container.

To transform the split container into a tab container, the container's DockPanel.Tabbed property should be set to true:

Expanded Floating a Panel

To make a panel floating you can use the following methods:

DockPanel.MakeFloat Makes an existing panel float.

Usage: panel.MakeFloat(); panel.MakeFloat(pointScreen)

The MakeFloat overload which takes the pointScreen parameter can be used to make a panel float and move it to the specified position (which is specified in screen coordinates).

The DockManager.AddPanel overload with the dockStyle parameter set to DockingStyle.Float.

The DockManager.AddPanel overload with the floatLocation parameter of type System.Drawing.Point.

Create a new panel and float it.

Usage: dockManager1.AddPanel(DockingStyle.Float); dockManager1.AddPanel(point);

 

Expanded Example 7

The following example shows how to create a floating panel and move it to a specific position:

When a panel is floated it is placed onto a floating form which can be accessed via the DockPanel.FloatForm property. You can for instance, use this property to control the floating panel's size and position.

To change the panel's size when it's floating, you can also use the DockPanel.FloatSize property.

Expanded See Also

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