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);
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);
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.
//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);
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);
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.
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-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.
//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.
AutoHideGroup autoHideGroup = new AutoHideGroup(); autoHideGroup.DockType = Dock.Bottom; dockLayoutManager1.AutoHideGroups.Add(autoHideGroup);
//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
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.
dockLayoutManager.DockController.Dock(layoutPanel1, layoutGroup1, DockType.Right); //... dockLayoutManager.DockController.Insert(layoutGroup2, layoutPanel1, 0);
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;