Managing Dock Panels in Code
- 8 minutes to read
This topic describes how to manage Dock Items (perform operations such as creating, removing, docking and auto-hiding panels, and making panels floating) in code, using DockLayoutManager.DockController methods.
Creating and Removing Panels
You can create a new dock panel (LayoutPanel) by calling the DockControllerBase.AddPanel method of the DockLayoutManager.DockController. The following example shows how to create and dock a panel at the right edge of the DockLayoutManager. (This method allows you to dock a panel to any other edge as well - top, bottom or left.)
If you use DockType.None as the type parameter, the AddPanel method creates a new instance of the LayoutPanel class without displaying it anywhere. To display this panel later, use the following methods.
- DockControllerBase.Dock - Allows you to move dock items (e.g., panels) to groups (LayoutGroup, TabbedGroup, FloatGroup or AutoHideGroup), position an item next to another panel or group, and merge panels to a tabbed group.
- DockControllerBase.Insert - Allows you to insert a dock item into a group at any position.
LayoutPanel layoutPanel1 = dockLayoutManager.DockController.AddPanel(DockType.None);
dockLayoutManager.DockController.Dock(layoutPanel1, layoutGroup1, DockType.Right);
To create a floating panel, use the AddPanel(Point floatLocation, Size floatSize) method overload, which allows the float panel size and location to be specified.
You can also create a new LayoutPanel using its constructor. The panel will not appear on screen until you dock it to a DockLayoutManager. To dock a panel, you can use the DockControllerBase.Dock and DockControllerBase.Insert methods as well.
LayoutPanel layoutPanel1 = new LayoutPanel();
//Move layoutPanel1 to layoutGroup1.
dockLayoutManager.DockController.Dock(layoutPanel1, layoutGroup1, DockType.Right);
//...
//Insert layoutPanel1 in layoutGroup2 in the first position.
dockLayoutManager.DockController.Insert(layoutGroup2, layoutPanel1, 0);
You can delete a LayoutPanel in code by calling the DockControllerBase.RemovePanel method:
Moving Panels
To move a dock panel to a new position (for instance, next to another dock panel) use the DockControllerBase.Dock method. This method allows you to define the target layout item and the docking type:
//Add a layout panel to an existing LayoutGroup.
dockLayoutManager.DockController.Dock(layoutPanel1, layoutGroup1, DockType.Left);
Note
Depending on the orientation of the target LayoutGroup items and the type parameter of the Dock method, the panel being moved is docked either to the LayoutGroup or next to it.
The DockControllerBase.Dock method also allows you to add a dock panel to a TabbedGroup by setting the type parameter to DockType.Fill.
//Dock layoutPanel1 as the last tab of the TabbedGroup.
dockLayoutManager.DockController.Dock(layoutPanel1, tabbedGroup1, DockType.Fill);
The same goal can be achieved by docking a LayoutPanel to another LayoutPanel that is already in the TabbedGroup. The relative position can be specified by the type parameter:
//Dock layoutPanel1 to the right of layoutPanel2.
//It is assumed that layoutPanel2 is in a TabbedGroup.
dockLayoutManager.DockController.Dock(layoutPanel1, layoutPanel2, DockType.Right);
It is possible to merge two LayoutPanels into a TabbedGroup by using DockControllerBase.Dock and setting the type parameter to DockType.Fill:
Note
If the target LayoutPanel is already in a TabbedGroup, the docking LayoutPanel will be appended to this TabbedGroup.
You can also insert a panel into any LayoutGroup descendant (TabbedGroup, AutoHideGroup or FloatGroup) by calling the DockControllerBase.Insert method. The method parameters specify the target layout item and position.
//Inserts a panel into LayoutGroupinthe third position.
dockLayoutManager.DockController.Insert(layoutGroup1, layoutPanel1, 2);
Floating Panels
To make an existing docked panel floating, use the DockControllerBase.Float method:
Float panels are displayed within floating windows represented by FloatGroup objects. For FloatGroup objects to be displayed, they must be added to the DockLayoutManager.FloatGroups collection. The Float method in the above example automatically creates a new FloatGroup, adds it to the FloatGroups collection, and adds the LayoutPanel to this FloatGroup.
Alternatively, you can create a float group manually and add a LayoutPanelto this group. Ensure that the newly created FloatGroup is added to the DockLayoutManager.FloatGroups collection:
It is possible to use the DockControllerBase.Dock and DockControllerBase.Insert methods to add a LayoutPanel to a FloatGroup. The Insert method allows you to define the position within the FloatGroup in which the LayoutPanel is inserted:
//Use the Dock method to add a LayoutPanel to the right edge of the FloatGroup.
dockLayoutManager.DockController.Dock(layoutPanel1, floatGroup, DockType.Right);
//Use the Insert method to add a LayoutPanel to the first position in the FloatGroup.
dockLayoutManager.DockController.Insert(floatGroup, layoutPanel1, 0);
Auto-Hide
Auto-hidden panels are normally hidden from view, and appear only when hovering over the panel’s label. A panel can be auto-hidden at the top, left, bottom or right edge of the DockLayoutManager. When a panel is auto-hidden, it is placed into an AutoHideGroup object that is docked to the corresponding edge. To be displayed, an AutoHideGroup must be added to the DockLayoutManager.AutoHideGroups collection.
You can call the DockControllerBase.Hide method to make an existing LayoutPanel auto-hidden.
//Hide a LayoutPanel at the nearest edge of the DockLayoutManager.
dockLayoutManager.DockController.Hide(layoutPanel1);
//Hide a LayoutPanel within the specified AutoHideGroup.
dockLayoutManager.DockController.Hide(layoutPanel1, autoHideGroup);
//Hide a LayoutPanel at the specified edge of the DockLayoutManager.
dockLayoutManager.DockController.Hide(layoutPanel1, Dock.Left);
A panel can also be auto-hidden by creating an instance of the AutoHideGroup class manually, and adding it to a DockLayoutManager.AutoHideGroups collection. Set the AutoHideGroup.DockType property (set to Dock.Left by default) to place the AutoHideGroup at a specific edge of the DockLayoutManager.
AutoHideGroupautoHideGroup = new AutoHideGroup();
autoHideGroup.DockType = Dock.Bottom;
dockLayoutManager1.AutoHideGroups.Add(autoHideGroup);
The following methods let you add a LayoutPanel to an existing AutoHideGroup: DockControllerBase.Dock and DockControllerBase.Insert.
//Use the Dock method to add a LayoutPanel to the left edge of the FloatGroup.
dockLayoutManager.DockController.Dock(layoutPanel1, autoHideGroup, DockType.Left);
//Use the Insert method to add a LayoutPanel to the left edge of the FloatGroup.
dockLayoutManager.DockController.Insert(autoHideGroup, layoutPanel1, 0);
Panel Visibility and Closing/Restoring Panels
An existing panel can be closed by calling the DockControllerBase.Close method, and restored to its previous position using the DockControllerBase.Restore method:
dockLayoutManager.DockController.Close(layoutPanel1);
//...
//The Dock method restores a closed panel to its previous position.
dockLayoutManager.DockController.Restore(layoutPanel1);
The DockControllerBase.Close method moves a closed panel to the DockLayoutManager.ClosedPanels collection, or deletes the reference to this panel from DockLayoutManager.DockLayoutManager, depending on the DockLayoutManager.ClosingBehavior and BaseLayoutItem.ClosingBehavior properties.
DockLayoutManager.ClosingBehavior determines the close behavior for all panels in DockLayoutManager, but it is possible to override this behavior for each panel with the BaseLayoutItem.ClosingBehavior property. The DockLayoutManager.ClosingBehavior property determines a panel’s close behavior only if the BaseLayoutItem.ClosingBehavior is set to Default.
A closed panel can also be restored to a new position via the DockControllerBase.Dock method or DockControllerBase.Insert method.
dockLayoutManager.DockController.Dock(layoutPanel1, layoutGroup1, DockType.Right);
//...
dockLayoutManager.DockController.Insert(layoutGroup2, layoutPanel1, 0);
The DockLayoutManager has a Closed Panels Bar, which provides access to closed panels. Each panel added to the DockLayoutManager.ClosedPanels collection appears in the Closed Panels Bar as a button.
The position and visibility of the Closed Panels Bar can be set via the DockLayoutManager.ClosedPanelsBarPosition and DockLayoutManager.ClosedPanelsBarVisibility properties:
usingDevExpress.Xpf.Docking.Base;
//...
dockLayoutManager.ClosedPanelsBarVisibility = ClosedPanelsBarVisibility.Auto;
dockLayoutManager.ClosedPanelsBarPosition = Dock.Left;
In some cases, you may wish to manipulate panel visibility with the Visibility property. To hide a panel, set this property to Visibility.Hidden or Visibility.Collapsed. When you set this property to Visibility.Hidden, the panel is hidden, and space for the element is reserved in the layout. Using Visibility.Collapsed allows you to hide a panel without reserving space for it in the layout.
layoutPanel1.Visibility = Visibility.Hidden;
//...
layoutPanel1.Visibility = Visibility.Visible;
The Visibility property works in the same way as the UIElement.Visibility property. A LayoutPanel hidden by this property cannot be restored via the DockControllerBase.Restore method.