WP7 WrapPanel in depth

by WindowsPhoneGeek

In this article I will talk about the WrapPanel control which comes with the Silverlight for Windows Phone 7 Toolkit.

One of the new controls in the Silverlight Toolkit is  WrapPanel. It enables users to position child elements sequentially from left to right or top to bottom.  When elements extend beyond the panel edge, they are positioned in the next row or column.

To begin using WrapPanel first  add a reference to  the Microsoft.Phone.Controls.Toolkit.dll  assembly which is installed with the toolkit and you can find it in :
       C:\Program Files (x86)\Microsoft SDKs\Windows Phone\v7.0\Toolkit\Nov10\Bin\Microsoft.Phone.Controls.Toolkit.dll.

You will also need to add the "toolkit" prefix declaration. Make sure that your page declaration includes the "toolkit" namespace:

       xmlns:toolkit="clr-namespace:Microsoft.Phone.Controls;assembly=Microsoft.Phone.Controls.Toolkit"

Visual Structure

Note: A WrapPanel contains a collection of UIElement objects, which are in the Children property!

In the most common scenario WrapPanel as the name says will wrap controls, any controls which cannot fit on the first line/column will be wrapped to next line/column and so forth.

Key Properties

• ItemHeight

      ItemHeight is a dependency property of type double. Gets or sets the height of the layout area for each item that is contained in a WrapPanel. The default value is      Double.NaN.

• ItemWidth

      ItemWidth is a dependency property of type double.Gets or sets the width of the layout area for each item that is contained in a WrapPanel. The default value is Double.NaN.

• Orientation

      Orientation is a dependency property of type Orientation. Gets or sets the direction in which child elements are arranged. The default is System.Windows.Controls.Orientation.Horizontal.

Sample Usage

Here is a simple example of how to use this Panel in Horizontal and Vertical Orientation mode. We will arrange 5 items i n a WrapPanel. The code is as follows:

<TextBlock Text="Horizontal Panel"/>
<toolkit:WrapPanel ItemHeight="100" ItemWidth="100"  Height="300">
    <Rectangle Fill="Aqua" Height="80" Width="80"/>
    <Rectangle Fill="Pink" Height="80" Width="80"/>
    <Rectangle Fill="Green" Height="80" Width="80"/>
    <Rectangle Fill="YellowGreen" Height="80" Width="80"/>
    <Rectangle Fill="Red" Height="80" Width="80"/>
</toolkit:WrapPanel>
<TextBlock Text="Vertical Panel"/>
<toolkit:WrapPanel ItemHeight="100" ItemWidth="100" Orientation="Vertical" Height="300">
    <Rectangle Fill="WhiteSmoke" Height="80" Width="80"/>
    <Rectangle Fill="White" Height="80" Width="80"/>
    <Rectangle Fill="Beige" Height="80" Width="80"/>
    <Rectangle Fill="Bisque" Height="80" Width="80"/>
    <Rectangle Fill="Wheat" Height="80" Width="80"/>
</toolkit:WrapPanel>

The result can be seen at the following screen shots:

WrapPanel as ItemsPanel

Although WrapPanel is a simple component it can be used in advanced scenarios when you want to change the ItemsPanel of any particular items control. For example  you can use it in the LongListSelector, ListPicker, ListBox and other ItemsControls in order to arrange the items in suitable way:

<ListBox>
    <ListBox.ItemsPanel>
        <ItemsPanelTemplate>
            <toolkit:WrapPanel ItemWidth="100" ItemHeight="50"/>
        </ItemsPanelTemplate>
    </ListBox.ItemsPanel>
    <ListBoxItem Content="Item1"/>
    <ListBoxItem Content="Item2"/>
    <ListBoxItem Content="Item3"/>
    <ListBoxItem Content="Item4"/>
    <ListBoxItem Content="Item5"/>
    <ListBoxItem Content="Item6"/>
</ListBox>

You can find the full source code of this panel in the Silverlight for Windows Phone 7 Toolkit source code.

That was all about the Toolkit`s  WrapPanel. in depth. I hope that the article was helpful.

The full source code can be downloaded here:

You can also follow us on Twitter @winphonegeek

Comments

<ListBox>
    <ListBox.ItemsPanel>
      <ItemsPanelTemplate>
         <toolkit:WrapPanel/>
      </ItemsPanelTemplate>
    </ListBox.ItemsPanel>
<ListBox>