.NET 4.0+

WPF Layout Controls - DockPanel

by Richard Carr, published at http://www.blackwasp.co.uk/WPFDockPanel.aspx

The tenth part of the Windows Presentation Foundation Fundamentals tutorial looks at another useful layout control. This time it is the DockPanel, which snaps its child controls to its edges. This is ideal for positioning toolbars and status areas.

The DockPanel

The WPF DockPanel is a standard layout control. It allows you to snap, or dock, controls to the edges of a rectangular area. Often the child controls that are docked are other layout controls such as Grids or StackPanels. This is particularly useful for the positioning of elements such as toolbars, status bars or toolboxes, all of which tend to be placed at the top, bottom or sides of a window.

The DockPanel includes an attached property named, "Dock". You use this to specify the position of each child control. If set to Left or Right, the control is positioned at the side of the DockPanel. The width of the control can be specified or the default size can be used. If the height and vertical alignment properties for such controls are not set, the child will fill the height of the DockPanel. Similarly, controls docked to the top or bottom of the panel will fill the available width unless otherwise specified.

The order in which items are added to a DockPanel is important. Each child control takes some of the available space, which becomes unavailable to those controls defined later. For example, a toolbar docked to the top of a DockPanel takes up some of the panel's height, even if the toolbar does not stretch to fill the horizontal space. A later control docked to the left will be expanded in height to fill the area between the toolbar and the base of the panel. It will not fill the entire DockPanel's height. Switching the order of these two child controls will give a different layout.

The final child control normally behaves differently than its predecessors. By default, it will fill the unused area of the DockPanel. You can change this behaviour through the panel's properties so that the final control is docked like all of the others.

DockPanel Example

Let's create a simple example to show how DockPanels are used. Create a new WPF Application project in Visual Studio, naming the project, "DockPanelDemo". Modify the XAML of the automatically added window as shown before.

<Window x:Class="DockPanelDemo.MainWindow"
           xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
           xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
           Title="Dock Panel Demo"
           Height="200"
           Width="250">
    <DockPanel>
        <Button Content="Left" DockPanel.Dock="Left"/>
        <Button Content="Top" DockPanel.Dock="Top"/>
        <Button Content="Right" DockPanel.Dock="Right"/>
        <Button Content="Bottom" DockPanel.Dock="Bottom"/>
        <Button Content="Fill"/>
    </DockPanel>
</Window>

The DockPanel in the XAML has five child controls, all buttons with default sizes. The first is docked to the left so stretches to the full height of the DockPanel. The width is determined by the button's contents. The second button is docked to the top of the panel and stretches horizontally to fill the remaining width. The third and fourth buttons dock to the right and bottom, again stretching to fill the available unused space. The fifth button automatically fills the space not yet used by docked controls.

The results are shown below. Note the positioning of the controls based upon their order in the XAML. No docked controls overlap.

The first sample showed every possible docking position. Of course, you don't have to use every available option. You can also use the same dock option more than once, causing controls to stack next to each other, as the next example shows. Modify the XAML for the DockPanel as follows:

<DockPanel>
    <Button Content="Top 1" DockPanel.Dock="Top"/>
    <Button Content="Left 1" DockPanel.Dock="Left"/>
    <Button Content="Left 2" DockPanel.Dock="Left"/>
    <Button Content="Top 2" DockPanel.Dock="Top"/>
    <Button Content="Fill"/>
</DockPanel>

The new layout is shown below: