Back to Devexpress

Manage Dock Panels in Code

wpf-15540-controls-and-libraries-layout-management-dock-windows-managing-dock-panels-in-code.md

latest41.2 KB
Original Source

Manage Dock Panels in Code

  • Sep 27, 2022
  • 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.

csharp
dockLayoutManager.DockController.AddPanel(DockType.Right);
vb
dockLayoutManager.DockController.AddPanel(DockType.Right)

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.

csharp
dockLayoutManager.DockController.Dock(layoutPanel1, layoutGroup1, DockType.Right);
vb
dockLayoutManager.DockController.Dock(layoutPanel1, layoutGroup1, DockType.Right

View Example: Dock a Panel to Another Panel in Code

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:

csharp
dockLayoutManager.DockController.Insert(layoutGroup1, layoutPanel1, 2);
vb
dockLayoutManager.DockController.Insert(layoutGroup1, layoutPanel1, 2)

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.

csharp
dockLayoutManager.DockController.AddPanel(new Point(0, 0), new Size(100, 100));
vb
dockLayoutManager.DockController.AddPanel(new Point(0, 0), new Size(100, 100))

Approach 2

  1. Create an instance of the FloatGroup class.
  2. Add it to a DockLayoutManager.FloatGroups collection.

Remove a LayoutPanel

Call the DockControllerBase.RemovePanel method to remove the specified LayoutPanel:

csharp
dockLayoutManager.DockController.RemovePanel(layoutPanel1);
vb
dockLayoutManager.DockController.RemovePanel(layoutPanel1)

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:

csharp
//Add a layout panel to an existing LayoutGroup.
dockLayoutManager.DockController.Dock(layoutPanel1, layoutGroup1, DockType.Left);
vb
'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:

csharp
dockLayoutManager.DockController.Insert(layoutGroup1, layoutPanel1, 2);
vb
dockLayoutManager.DockController.Insert(layoutGroup1, layoutPanel1, 2)

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:

csharp
dockLayoutManager.DockController.Dock(layoutPanel1, tabbedGroup1, DockType.Fill);
vb
dockLayoutManager.DockController.Dock(layoutPanel1, tabbedGroup1, DockType.Fill)

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:

csharp
dockLayoutManager.DockController.Dock(layoutPanel1, layoutPanel2, DockType.Right);
vb
dockLayoutManager.DockController.Dock(layoutPanel1, layoutPanel2, DockType.Right)

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:

csharp
dockLayoutManager.DockController.Dock(layoutPanel1, layoutPanel2, DockType.Fill);
vb
dockLayoutManager.DockController.Dock(layoutPanel1, layoutPanel2, DockType.Fill)

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:

csharp
dockLayoutManager.DockController.Dock(layoutPanel1, floatGroup, DockType.Right);
vb
dockLayoutManager.DockController.Dock(layoutPanel1, floatGroup, DockType.Right)

The following code sample adds a layoutPanel1 to the floatGroup and moves the panel to the left (first position):

csharp
dockLayoutManager.DockController.Insert(floatGroup, layoutPanel1, 0);
vb
dockLayoutManager.DockController.Insert(floatGroup, layoutPanel1, 0)

Move a Panel to an Auto-Hide Group

Use the following methods to move a LayoutPanel to an existing AutoHideGroup: DockControllerBase.Dock/DockControllerBase.Insert.

csharp
//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);
vb
'Add a LayoutPanel to the left edge of the FloatGroup
dockLayoutManager.DockController.Dock(layoutPanel1, autoHideGroup, DockType.Left)

'Add 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:

csharp
dockLayoutManager1.LayoutController.Move(item1, group1, DevExpress.Xpf.Layout.Core.MoveType.InsideGroup);
vb
dockLayoutManager1.LayoutController.Move(item1, group1, DevExpress.Xpf.Layout.Core.MoveType.InsideGroup)

View Example

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:

csharp
dockLayoutManager.DockController.Float(layoutPanel1);
vb
dockLayoutManager.DockController.Float(layoutPanel1)

Convert a LayoutPanel to an Auto-Hidden Panel

Approach 1

Call the DockControllerBase.Hide method to make an existing LayoutPanel auto-hidden:

csharp
//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);
vb
'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

  1. Create an instance of the AutoHideGroup class.
  2. Set the AutoHideGroup.DockType property to place the AutoHideGroup at a specified side of the DockLayoutManager.
  3. Add it to a DockLayoutManager.AutoHideGroups collection.

Close a Layout Panel

Call the DockControllerBase.Close method to close an existing panel.

csharp
dockLayoutManager.DockController.Close(layoutPanel1);
vb
dockLayoutManager.DockController.Close(layoutPanel1)

View Example: Create closed (hidden) panels

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:

csharp
dockLayoutManager.DockController.Restore(layoutPanel1);
vb
dockLayoutManager.DockController.Restore(layoutPanel1)

Approach 2

Call the DockControllerBase.Dock or DockControllerBase.Insert method to restore a panel in a new location.

csharp
dockLayoutManager.DockController.Dock(layoutPanel1, layoutGroup1, DockType.Right);

dockLayoutManager.DockController.Insert(layoutGroup2, layoutPanel1, 0);
vb
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.

csharp
layoutPanel1.Visibility = Visibility.Hidden;

layoutPanel1.Visibility = Visibility.Visible;
vb
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:

xaml
<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>
csharp
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");
        }
    }
vb
Imports DevExpress.Xpf.Docking

Public Partial Class MainWindow
    Inherits Window
    Private Sub CreateDocumentPanel(ByVal name As String)
        Dim modulePanel As DocumentPanel = New DocumentPanel() With {
            .Caption = name,
            .IsActive = True
        }
        dcgExplorer.Add(modulePanel)
        modulPanel.Content = New Uri("Forms\TableDesignWindow.xaml", UriKind.Relative)
    End Sub

    Private Sub Button_Click(ByVal sender As Object, ByVal e As RoutedEventArgs)
        CreateMdiChild("Test")
    End Sub
End Class

To activate a panel/item, you can also use the following members:

MemberDescription
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:

xaml
<dxdo:DockLayoutManager DockItemActivating="DockLayoutManager_DockItemActivating">
    <dxdo:LayoutGroup>
        <dxdo:DocumentGroup>
            <dxdo:DocumentPanel Caption="Document1" />
            <dxdo:DocumentPanel Caption="Document2" />
        </dxdo:DocumentGroup>
    </dxdo:LayoutGroup>
</dxdo:DockLayoutManager>
csharp
void DockLayoutManager_DockItemActivating(object sender, ItemCancelEventArgs e) {
    if (/*Your conditions here*/) {
        e.Cancel = true;
        e.Handled = true;
    }
}
vb
Private Sub DockLayoutManager_DockItemActivating(ByVal sender As Object, ByVal e As ItemCancelEventArgs)
    e.Cancel = True
    e.Handled = True
End Sub

Access Existing Layout Panels

The following code sample returns all LayoutPanels that exist in the DockLayoutManager instance:

csharp
var panels1 = dockLayoutManager.GetItems().Where(x => x is LayoutPanel);
// or
var panels2 = dockLayoutManager.GetItems().OfType<LayoutPanel>();
vb
Dim panels1 = dockLayoutManager.GetItems().Where(Function(x) TypeOf x Is LayoutPanel)
`... or 
Dim panels2 = dockLayoutManager.GetItems().OfType(Of LayoutPanel)()

You can also call the DockLayoutManagerExtension.GetItems method to get all the panels within the DockLayoutManager instance:

csharp
public static class DockLayoutManagerExtension {
    // ...
    public static BaseLayoutItem[] GetItems(this DockLayoutManager container);
    // ...
}
vb
Imports System.Runtime.CompilerServices

Module DockLayoutManagerExtension <Extension()>
    Function GetItems(ByVal container As DockLayoutManager) As BaseLayoutItem()
End Module

Dock Item Commands

The DockLayoutManager includes the DockControllerCommand class that contains the following set of dock panel commands:

CommandDescription
ActivateActivates a specific dock item.
CloseCloses a specific dock item.
DockDocks a floating or an auto-hidden dock item.
FloatMakes the specified item floating.
HideEnables the auto-hide functionality for the item/panel and hides it at a corresponding edge of the DockLayoutManager container.
RestoreRestores 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:

xaml
<Button Command="dxdo:DockControllerCommand.Close" CommandTarget="{Binding ElementName=dockManager1}" 
        CommandParameter="{Binding ElementName=dockManager1, Path=ActiveDockItem }">

View Example

Available Methods

MethodDescription
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

Run Demo: Dock Layout Manager - Events Demo

EventDescription
BeforeItemAddedFires before an item is added to the current DockLayoutManager object.
DockItemActivatedFires after a dock item has been activated.
DockItemActivatingFires before a dock item is activated, and allows you to prevent this action.
DockItemClosedFires after a dock item has been closed (hidden).
DockItemClosingFires before a dock item is closed (hidden), and allows you to prevent this action.
DockItemCollapsedFires after a visible auto-hidden dock panel has slid away.
DockItemEndDockingFires after a dock item has been dropped, and allows you to prevent this action.
DockItemExpandedFires after a hidden auto-hidden dock panel has slid out.
DockItemHiddenFires after a dock item has been made auto-hidden.
DockItemHidingFires before a dock item is auto-hidden, and allows you to prevent this action.
DockItemRestoredFires after a dock item has been restored from the closed (hidden) state.
DockItemRestoringFires before a dock item is restored from the closed (hidden) state, and allows you to prevent this action.
DockItemStartDockingFires when a docking operation starts, and allows you to prevent this operation.
DockOperationCompletedOccurs immediately after a dock operation within the current DockLayoutManager is completed.
DockOperationStartingOccurs whenever a docking operation within the current DockLayoutManager is performed.
ItemIsVisibleChangedFires when the item’s IsVisible property is changed.
LayoutItemActivatedFires after a layout item has been activated.
LayoutItemActivatingFires when a layout item is about to be activated.
LayoutItemEndRenamingFires when layout item renaming is completed.
LayoutItemHiddenFires when a layout item is hidden.
LayoutItemMovedFires after a layout item has been moved to a new position.
LayoutItemRestoredFires when a hidden layout item is restored (added to the layout).
LayoutItemSelectionChangedFires after the layout item’s selection state has changed.
LayoutItemSelectionChangingFires when the layout item’s selection state is about to be changed.
LayoutItemSizeChangedFires after a layout item‘s width/height has changed.
LayoutItemStartRenamingFires when layout item renaming is initiated.
MDIItemActivatedFires when an MDI child document has been activated.
MDIItemActivatingFires before an MDI child panel is activated.
RequestUniqueNameAllows you to provide unique names for layout items, whose names conflict with existing names.
ShowingMenuFires before showing a context menu, and allows it to be customized.
ShowInvisibleItemsChangedFires when the value of the DockLayoutManager.ShowInvisibleItems property is changed.
UnMergeAllows you to undo bars customizations performed via the DockLayoutManager.Merge event.

See Also

Dock UI Items

Dock Layout Manager: Get Started