Manage Dock Panels in Code
- 14 minutes to read
This topic describes code operations that you can perform on DockLayoutManager‘s items.
Create Docked Panels
Call the DockControllerBase.AddPanel method to create a new docked LayoutPanel.
The following example creates and docks a panel at the right edge of the DockLayoutManager.
If you pass the DockType.None as the type parameter, the created LayoutPanel instance is not displayed. In this case, you can call any of the following methods to display the panel:
- DockControllerBase.Dock
Moves a panel to groups (LayoutGroup, TabbedGroup, FloatGroup or AutoHideGroup), positions an item next to another panel or group, or merges the panel to a tabbed group.
- DockControllerBase.Insert
Inserts a dock item into a group at the specified position.
The following code sample inserts a layoutPanel1 into layoutGroup1 in the third position:
Create Floating Panels
Approach 1
Call the AddPanel(Point, Size) method to create a floating panel with the specified size and in the specified location.
Approach 2
- Create an instance of the FloatGroup class.
Add it to a DockLayoutManager.FloatGroups collection.
Remove a LayoutPanel
Call the DockControllerBase.RemovePanel method to remove the specified LayoutPanel:
Move Panels
Approach 1
Call any of the DockControllerBase.Dock methods to move a dock panel next to the specified dock panel.
The following code sample moves the layout panel to the left side of the layoutgroup1:
//Add a layout panel to an existing LayoutGroup.
dockLayoutManager.DockController.Dock(layoutPanel1, layoutGroup1, DockType.Left);
Depending on the target LayoutGroup‘s Orientation property value and the type parameter of the DockControllerBase.Dock method, the panel that you move is docked either to the LayoutGroup or next to it.
Approach 2
Call the DockControllerBase.Insert method to insert a panel into any LayoutGroup descendant (TabbedGroup, AutoHideGroup or FloatGroup). The method parameters allow you to specify the target layout item and position.
The following code sample inserts a layoutPanel1 into layoutGroup1 in the third position:
Move a Panel to a TabbedGroup
Approach 1
Set the DockControllerBase.Dock method’s type parameter to Fill to move a dock panel into the specified TabbedGroup.
The following code sample docks the layoutPanel1 as the last tab of the tabbedGroup1:
Approach 2
Call the DockControllerBase.Dock method to dock a LayoutPanel to another LayoutPanel that is already in the TabbedGroup. Use the method’s type parameter to specify the relative position of the LayoutPanel that you move.
The following code sample docks the layoutPanel1 to the right of the layoutPanel2 that is in placed inside a TabbedGroup:
Merge Two LayoutPanels into a TabbedGroup
Call a DockControllerBase.Dock method and set its type parameter to DockType.Fill to merge two LayoutPanels into a TabbedGroup:
If the target LayoutPanel is already in a TabbedGroup, the LayoutPanel that you dock is appended to this TabbedGroup.
Move a Panel to a FloatGroup
Call the DockControllerBase.Dock or DockControllerBase.Insert method to add a LayoutPanel to a FloatGroup. The Insert method allows you to define the position of the LayoutPanel within the FloatGroup.
The following code sample adds a layoutPanel1 to the floatGroup‘s right:
The following code sample adds a layoutPanel1 to the floatGroup and moves the panel to the left (first position):
Move a Panel to an Auto-Hide Group
Use the following methods to move a LayoutPanel to an existing AutoHideGroup: DockControllerBase.Dock/DockControllerBase.Insert.
//Adds a LayoutPanel to the left edge of the FloatGroup
dockLayoutManager.DockController.Dock(layoutPanel1, autoHideGroup, DockType.Left);
//Adds a LayoutPanel to the left edge of the FloatGroup
dockLayoutManager.DockController.Insert(autoHideGroup, layoutPanel1, 0);
Move Layout UI Items
You can use any of the LayoutController.Move methods to move a layout UI item into a layout group.
The following code sample moves the item1 inside group1:
dockLayoutManager1.LayoutController.Move(item1, group1, DevExpress.Xpf.Layout.Core.MoveType.InsideGroup);
You can move layout UI items only when the BaseLayoutItem.AllowMove property is true.
Convert a Panel to a Floating Panel
Call the DockControllerBase.Float method to make an existing panel floating.
The following code sample converts the layoutPanel1 to a floating panel:
Convert a LayoutPanel to an Auto-Hidden Panel
Approach 1
Call the DockControllerBase.Hide method to make an existing LayoutPanel auto-hidden:
//Hides a LayoutPanel at the nearest edge of the DockLayoutManager
dockLayoutManager.DockController.Hide(layoutPanel1);
//Hides a LayoutPanel within the specified AutoHideGroup
dockLayoutManager.DockController.Hide(layoutPanel1, autoHideGroup);
//Hides a LayoutPanel at the specified edge of the DockLayoutManager
dockLayoutManager.DockController.Hide(layoutPanel1, Dock.Left);
Approach 2
- Create an instance of the AutoHideGroup class.
- Set the AutoHideGroup.DockType property to place the AutoHideGroup at a specified side of the DockLayoutManager.
Add it to a DockLayoutManager.AutoHideGroups collection.
Close a Layout Panel
Call the DockControllerBase.Close method to close an existing panel.
You can use the DockLayoutManager.ClosedPanels collection to access the closed panels.
Your users can use the Closed Panel Bar to access closed panels. Refer to the following topic for more information on how to customize the Closed Panel Bar‘s visibility and appearance: Visual Elements: Closed Panel Bar
Customize Closing Behavior
Use the DockLayoutManager.ClosingBehavior and BaseLayoutItem.ClosingBehavior properties to specify whether a panel should be closed or removed when you use the DockControllerBase.Close method.
The DockLayoutManager.ClosingBehavior property determines the close behavior for all panels in DockLayoutManager.
The BaseLayoutItem.ClosingBehavior property determines the close behavior for the specified panel.
The DockLayoutManager.ClosingBehavior property determines a panel’s close behavior only if the BaseLayoutItem.ClosingBehavior is set to Default.
Restore a Layout Panel
Approach 1
Call the DockControllerBase.Restore method to restored a panel to its previous position:
Approach 2
Call the DockControllerBase.Dock or DockControllerBase.Insert method to restore a panel in a new location.
dockLayoutManager.DockController.Dock(layoutPanel1, layoutGroup1, DockType.Right);
dockLayoutManager.DockController.Insert(layoutGroup2, layoutPanel1, 0);
Hide a Layout Panel
To hide a panel, set its Visibility property to Hidden or Collapsed. When this property is Hidden, the panel is hidden but the space for the panel is reserved in its parent element. Set the Visibility property to Collapsed to hide the panel and not reserve space for it in its parent element.
layoutPanel1.Visibility = Visibility.Hidden;
layoutPanel1.Visibility = Visibility.Visible;
You cannot use the DockControllerBase.Restore method to restore the hidden LayoutPanel.
Activate a Panel
Set a panel’s IsActive inherited property to true, to activate this panel.
The following code sample creates a new DocumentPanel and activates it when it is created:
<Window ...
xmlns:dxdo="http://schemas.devexpress.com/winfx/2008/xaml/docking">
<Grid>
<dxdo:DockLayoutManager x:Name="lmManager">
<dxdo:LayoutGroup Orientation="Horizontal">
<dxdo:LayoutPanel>
<Button Content="Explore" Click="Button_Click" />
</dxdo:LayoutPanel>
<dxdo:DocumentGroup x:Name="dcgExplorer">
<dxdo:DocumentPanel x:Name="paneDocument1" Caption="Document 1">
<RichTextBox />
</dxdo:DocumentPanel>
<dxdo:DocumentPanel x:Name="paneDocument2" Caption="Document 2">
<RichTextBox />
</dxdo:DocumentPanel>
</dxdo:DocumentGroup>
</dxdo:LayoutGroup>
</dxdo:DockLayoutManager>
</Grid>
</Window>
using DevExpress.Xpf.Docking;
// ...
public partial class MainWindow : Window {
private void CreateDocumentPanel(string name) {
DocumentPanel modulePanel = new DocumentPanel() {
Caption = name,
IsActive = true
};
dcgExplorer.Add(modulePanel);
modulPanel.Content = new Uri(@"Forms\TableDesignWindow.xaml", UriKind.Relative);
}
private void Button_Click(object sender, RoutedEventArgs e){
CreateMdiChild("Test");
}
}
To activate a panel/item, you can also use the following members:
| Member | Description |
|---|---|
| ActiveDockItem | Gets or sets the active dock item. This is a dependency property. |
| Activate(BaseLayoutItem) | Activates the specified item. For a LayoutControlItem object, this method focuses the associated control. |
| AllowActivate | Gets or sets whether the item can be activated. This is a dependency property. |
| DockItemActivating | Fires before a dock item is activated, and allows you to prevent this action. |
| DockItemActivated | Fires after a dock item has been activated. |
Expand/Hide Auto-Hidden Panels
Use the AutoHideExpandState to specify a state of the LayoutPanel that is added to an AutoHideGroup.
Disable a DocumentGroup’s Tab Change
When a user selects a tab, the DockItemActivating event is fired. You can use this event to prevent a user from changing a tab:
<dxdo:DockLayoutManager DockItemActivating="DockLayoutManager_DockItemActivating">
<dxdo:LayoutGroup>
<dxdo:DocumentGroup>
<dxdo:DocumentPanel Caption="Document1" />
<dxdo:DocumentPanel Caption="Document2" />
</dxdo:DocumentGroup>
</dxdo:LayoutGroup>
</dxdo:DockLayoutManager>
void DockLayoutManager_DockItemActivating(object sender, ItemCancelEventArgs e) {
if (/*Your conditions here*/) {
e.Cancel = true;
e.Handled = true;
}
}
Access Existing Layout Panels
The following code sample returns all LayoutPanels that exist in the DockLayoutManager instance:
var panels1 = dockLayoutManager.GetItems().Where(x => x is LayoutPanel);
// or
var panels2 = dockLayoutManager.GetItems().OfType<LayoutPanel>();
You can also call the DockLayoutManagerExtension.GetItems method to get all the panels within the DockLayoutManager instance:
public static class DockLayoutManagerExtension {
// ...
public static BaseLayoutItem[] GetItems(this DockLayoutManager container);
// ...
}
Dock Item Commands
The DockLayoutManager includes the DockControllerCommand class that contains the following set of dock panel commands:
| Command | Description |
|---|---|
| Activate | Activates a specific dock item. |
| Close | Closes a specific dock item. |
| Dock | Docks a floating or an auto-hidden dock item. |
| Float | Makes the specified item floating. |
| Hide | Enables the auto-hide functionality for the item/panel and hides it at a corresponding edge of the DockLayoutManager container. |
| Restore | Restores a closed (hidden) panel at its previous dock position. |
You can also use the CloseCommand property to close a layout item.
The following code sample associates the Close command with a button. When a user clicks the button, the active dock panel is closed:
<Button Command="dxdo:DockControllerCommand.Close" CommandTarget="{Binding ElementName=dockManager1}"
CommandParameter="{Binding ElementName=dockManager1, Path=ActiveDockItem }">
Available Methods
| Method | Description |
|---|---|
| Activate(BaseLayoutItem) | Activates the specified item. |
| Activate(BaseLayoutItem, Boolean) | Activates the specified item and moves focus to it. |
| AddDocumentGroup(DockType) | Creates a DocumentGroup, and docks it to the DockLayoutManager container (root group). |
| AddDocumentPanel(DocumentGroup) | Adds a new DocumentPanel to the specified DocumentGroup. |
| AddDocumentPanel(Point, Size) | Adds an empty floating DocumentPanel. |
| AddDocumentPanel(Point, Size, Uri) | Adds a new floating DocumentPanel and loads the contents of a Window, Page or UserControl defined in the specified XAML into the DocumentPanel. |
| AddDocumentPanel(DocumentGroup, Uri) | Adds a new DocumentPanel to the specified DocumentGroup and loads the contents of a Window, Page or UserControl defined in the specified XAML into the DocumentPanel. |
| AddItem(BaseLayoutItem, BaseLayoutItem, DockType) | Adds a newly created item to the specified target item. This member supports the internal infrastructure, and is not intended to be used directly from your code. |
| AddPanel(Point, Size) | Creates a floating panel with the specified size and displays it at the specified location. |
| AddPanel(DockType) | Creates a LayoutPanel and docks it at the specified side of the DockLayoutManager container (root group). |
| Close(BaseLayoutItem) | Closes the specified item. |
| CloseAllButThis(BaseLayoutItem) | Closes all items except the specified one within this item’s container. |
| CreateNewDocumentGroup(DocumentPanel, Orientation) | Creates a new DocumentGroup and moves the specified DocumentPanel to it. |
| CreateNewDocumentGroup(LayoutPanel, Orientation) | Creates a new DocumentGroup and moves the specified LayoutPanel to it. |
| Dock(BaseLayoutItem, BaseLayoutItem, DockType) | Docks the first item to the second item using the specified dock type. |
| Dock(BaseLayoutItem) | Docks the specified item. This method is in effect for newly created, floating, auto-hidden or closed(hidden) items. |
| Float(BaseLayoutItem) | Makes the specified item floating. |
| Hide(BaseLayoutItem, Dock) | Enables the auto-hide functionality for the item/panel and hides it at the specified edge of the DockLayoutManager container. |
| Hide(BaseLayoutItem, AutoHideGroup) | Enables the auto-hide functionality for the item/panel and hides it within the specified AutoHideGroup group. |
| Hide(BaseLayoutItem) | Enables the auto-hide functionality for the item/panel and hides it at a corresponding edge of the DockLayoutManager container. |
| GetChildrenCount() | Gets the number of all nested child items. |
| Insert(LayoutGroup, BaseLayoutItem, Int32) | Inserts the specified item into the specified group at a specific position. |
| Insert(Int32, BaseLayoutItem) | Inserts the specified item at the specified position. |
| MoveToDocumentGroup(DocumentPanel, Boolean) | Moves the specified DocumentPanel to the previous or next DocumentGroup. |
| MoveToDocumentGroup(LayoutPanel, Boolean) | Moves the specified LayoutPanel to the previous or next DocumentGroup. |
| Remove(BaseLayoutItem) | Removes the specified item from the collection. |
| RemoveItem(BaseLayoutItem) | Removes the specified item. This member supports the internal infrastructure, and is not intended to be used directly from your code. |
| RemovePanel(LayoutPanel) | Removes any connection of the specified panel with the DockLayoutManager. |
| Rename(BaseLayoutItem) | Starts dock item renaming. |
| Restore(BaseLayoutItem) | Restores a closed (hidden) panel at its previous dock position. |
| ScrollNext() | Scrolls forward through tab headers corresponding to the group’s child items. This property is in effect if the current group represents child items as tabs. |
| ScrollPrev() | Scrolls backward through tab headers corresponding to the group’s child items. This property is in effect if the current group represents child items as tabs. |
Available Events
| Event | Description |
|---|---|
| BeforeItemAdded | Fires before an item is added to the current DockLayoutManager object. |
| DockItemActivated | Fires after a dock item has been activated. |
| DockItemActivating | Fires before a dock item is activated, and allows you to prevent this action. |
| DockItemClosed | Fires after a dock item has been closed (hidden). |
| DockItemClosing | Fires before a dock item is closed (hidden), and allows you to prevent this action. |
| DockItemCollapsed | Fires after a visible auto-hidden dock panel has slid away. |
| DockItemEndDocking | Fires after a dock item has been dropped, and allows you to prevent this action. |
| DockItemExpanded | Fires after a hidden auto-hidden dock panel has slid out. |
| DockItemHidden | Fires after a dock item has been made auto-hidden. |
| DockItemHiding | Fires before a dock item is auto-hidden, and allows you to prevent this action. |
| DockItemRestored | Fires after a dock item has been restored from the closed (hidden) state. |
| DockItemRestoring | Fires before a dock item is restored from the closed (hidden) state, and allows you to prevent this action. |
| DockItemStartDocking | Fires when a docking operation starts, and allows you to prevent this operation. |
| DockOperationCompleted | Occurs immediately after a dock operation within the current DockLayoutManager is completed. |
| DockOperationStarting | Occurs whenever a docking operation within the current DockLayoutManager is performed. |
| ItemIsVisibleChanged | Fires when the item’s IsVisible property is changed. |
| LayoutItemActivated | Fires after a layout item has been activated. |
| LayoutItemActivating | Fires when a layout item is about to be activated. |
| LayoutItemEndRenaming | Fires when layout item renaming is completed. |
| LayoutItemHidden | Fires when a layout item is hidden. |
| LayoutItemMoved | Fires after a layout item has been moved to a new position. |
| LayoutItemRestored | Fires when a hidden layout item is restored (added to the layout). |
| LayoutItemSelectionChanged | Fires after the layout item’s selection state has changed. |
| LayoutItemSelectionChanging | Fires when the layout item’s selection state is about to be changed. |
| LayoutItemSizeChanged | Fires after a layout item‘s width/height has changed. |
| LayoutItemStartRenaming | Fires when layout item renaming is initiated. |
| MDIItemActivated | Fires when an MDI child document has been activated. |
| MDIItemActivating | Fires before an MDI child panel is activated. |
| RequestUniqueName | Allows you to provide unique names for layout items, whose names conflict with existing names. |
| ShowingMenu | Fires before showing a context menu, and allows it to be customized. |
| ShowInvisibleItemsChanged | Fires when the value of the DockLayoutManager.ShowInvisibleItems property is changed. |
| UnMerge | Allows you to undo bars customizations performed via the DockLayoutManager.Merge event. |