.NET 4.0+

WPF Layout Controls - WrapPanel

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

The ninth part of the Windows Presentation Foundation Fundamentals tutorial continues the description of the WPF layout controls. This instalment considers the WrapPanel, which automatically arranges its child controls into rows or columns.

The WrapPanel

The WPF WrapPanel control is another layout control that automatically arranges its children. Contained controls are organised in rows or columns, depending upon the orientation option that you select. Unlike previous layout controls we've examined, the WrapPanel does not necessarily create a tabular layout. It's quite possible for each row or column to contain controls of varying sizes and for each row to include a different number of child controls.

In the default, horizontally-orientated configuration, the first control added to a WrapPanel appears at the top-left of the allocated area. The next control is positioned to the right of the first and further controls are added to form a row. When a control is encountered that will not fit within the width of the WrapPanel it becomes the first control in the next row. This continues until all controls have been rendered or until the WrapPanel is full, at which point controls may be clipped.

WrapPanel Example

To demonstrate the use of the WrapPanel and to understand how it helps with layouts where the available screen space can change, let's create a simple example. Start Visual Studio and create a new WPF Application project. Name the project, "WrapPanelDemo". Once the project is created, replace the XAML in the automatically generated window with that shown below.

<Window x:Class="WrapPanelDemo.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        Title="WrapPanel Demo"
        Height="200"
        Width="250">
    <WrapPanel Margin="10" Background="Lavender">
        <Button Content="Button 1" Width="100" Height="25" Margin="3"/>
        <Button Content="Button 2" Width="100" Height="25" Margin="3"/>
        <Button Content="Button 3" Width="100" Height="25" Margin="3"/>
        <Button Content="Button 4" Width="100" Height="25" Margin="3"/>
    </WrapPanel>
</Window>

The above XAML defines a WrapPanel that contains four controls. The panel's background is filled with a lavender colour so that you can see its extent. It contains four buttons, which in this case have all been given the same size and margin values.

Execute the program to see the results. When the window is first loaded you should see something similar to the image below. You can see that the buttons have been added from left to right, then in rows from top to bottom.

If you resize the window to make it wider you will initially see the WrapPanel expand to fill the available space. The buttons will not be affected until there is enough room for button 3 to fit within the first row. At this point the layout is recalculated, moving button 3 to the first row and leaving button 4 as the only control in the second row:

If you widen the window further you will see that the fourth button can be moved into the first row. If you make the window smaller, the layout will keep changing until only one button can fit in each row. At this point there will be four rows of buttons and further reductions in size will clip the child controls.

Orientation

The default orientation for a WrapPanel is horizontal but you can switch to vertical using the Orientation property. A vertical WrapPanel builds a column of controls at the left edge of the panel until no further controls will fit. The next control starts a new column to the right of the first.

To demonstrate, modify the WrapPanel's XAML to set the orientation, as follows:

<WrapPanel Margin="10" Background="Lavender" Orientation="Vertical">
    <Button Content="Button 1" Width="100" Height="25" Margin="3"/>
    <Button Content="Button 2" Width="100" Height="25" Margin="3"/>
    <Button Content="Button 3" Width="100" Height="25" Margin="3"/>
    <Button Content="Button 4" Width="100" Height="25" Margin="3"/>
</WrapPanel>

Run the program and adjust the height of the window to see the results. The image below shows what happens when the height of the WrapPanel is sufficient for only three of the buttons.

NB: By default the first column is at the left of the WrapPanel. You can build columns from right to left by changing the FlowDirection property.