Creating a Three-Column Silverlight ListBox

Author: Victor Gaudioso

Expression Newsletter, subscribe now to get yours.

About the Author: Victor Gaudioso, a Microsoft Silverlight Ambassador and recent Microsoft Most Valuable Professional (MVP) nominee, is an independent Windows Presentation Foundation / Silverlight / Surface developer, instructor (classroom / video tutorials / written articles), published author (Foundation Blend 2: Building Applications in WPF and Silverlight(2008),Foundation Blend 3 with Silverlight(2009)), and public speaker.

Victor produces video tutorials on his personal blog, and recently co-founded the first Los Angeles Silverlight user group (LASLUG) with Microsoft.

You can follow Victor on Twitter @victorgaudioso or send him an email at wpfauthor@gmail.com.

Recently my boss approached me and said, “Hey, remember that UserControl that holds the financial information? We want to have it in three columns.” I thought to myself, oh, okay simple enough; I will just find the property in Blend’s Properties panel that sets how many columns a ListBox will have. Of course, I had never used this property before, but this was the first time that anyone had ever asked me to make a ListBox contain more than one column. With that, I created a new ListBox in Blend and then looked through the Properties panel for this multi-column property. Much to my surprise, such a property didn’t exist. After a little research, I found that a ListBox does not support multi-columns. After a little more research and a bunch of failed attempts, I came up with a way to use the WPF WrapPanel to make a three column ListBox. And, it actually wasn’t too difficult to do. My problem now? Well, the project I was working on was a Silverlight project, not a WPF project, and the current release of Silverlight does not contain a WrapPanel. So now my clever solution was not a solution at all. After a bit more research, I found that the Silverlight Toolkit does have a WrapPanel. So, I was able to use that to make a three column Silverlight ListBox. Today, I am going to show you how to use the Silverlight Toolkit WrapPanel to create a three column ListBox.

Assumptions

This article assumes that you are a web developer that has Blend 3 and Silverlight 3 installed. Further, this article assumes you have an Internet connection and have installed software before. Finally, this article assumes you have a basic knowledge of Silverlight and the ability to create a standard ListBox using the Blend 3 toolbar.

Create the project

Open Blend and click File > New Project.
When the New Project dialog box appears select:
1. Silverlight for the Project Type
2. Then select the Silverlight 3 Application + Website template
3. Name the Project SilverlightThreeColListBox
4. Click OK as I am doing in Figure 1.
  Figure 1. Use these settings when creating your Silverlight project in Blend.

Blend will then create the new project for you. The first thing you need to do is to create your ListBox that we can then tweak out. Do that now.

Create the ListBox

Click and hold down the Button tool in the toolbar until you see the other options appear.
Click the ListBox control as I am doing in Figure 2.
Figure 2. Select the ListBox control from the toolbar.
Draw a ListBox out on the Artboard about 300 display units wide and 215 display units tall as I have done in Figure 3.
Figure 3. Draw a ListBox out on the Artboard.

Install the Silverlight Toolkit

Now that you have your ListBox it is time to start tweaking it to use the Silverlight Toolkit WrapPanel. But before you do that you need to install the Toolkit. Do that now:

Open a web browser and navigate to http://www.codeplex.com/Silverlight.
Click the Download Now button on the upper right corner of the page.
When prompted click the I Agree button to agree to the usage license.
Save the file named Silverlight_3_Toolkit_October_2009.msi to your hard drive (make a mental note of where it is being saved).
When it has finished downloading, click Open (if you are not given this option navigate to where you have it saved on your hard drive and double-click it).
Now go through the installation process. It is straightforward, and if you have ever installed any software before this should not be a problem for you.

Add a Reference to the Silverlight Toolkit Controls Dll

Now that you have installed the Silverlight Toolkit, you need to add the Assembly Reference to your project so your project can make use of all that it has to offer: namely the WrapPanel. Switch back to Blend and do that now.

In the Projects panel, right-click on the References directory and then click Add Reference, as I am doing in Figure 4.
Figure 4. Add a Reference in Blend’s Projects panel.
Blend will then give you a Windows Explorer window. Use it to navigate to C:\Program Files (x86)\Microsoft SDKs\Silverlight\v3.0\Toolkit\Oct09\Bin.
Double-click the System.Windows.Controls.Toolkit.dll, as I am doing in Figure 5:
Figure 5. Add the System.Windows.Controls.Toolkit.dll to your project.

Create a ListBox Items Panel Template

Now that you have the DLL, you will have access to the Silverlight Toolkit WrapPanel. Now all you need to do is tweak your ListBox to use it. Do that now!

In the Objects and Timeline panel, right-click the ListBox.
Click Edit Additional Templates> Edit Layout of Items (ItemsPanel) > Create Empty, as I am doing in Figure 6.
Figure 6. Create an Empty ItemsPanel.
When the Create ItemsPanelTemplate Resource dialog box appears name the new Panel Template ThreeColListBoxPanel like I have done in Figure 7.
Figure 7. Name the new Panel Template ThreeColListBoxPanel.
Click OK.

Blend then creates the Panel Template for you. You can see in the Objects and Timeline panel the default panel that it provides for you is a StackPanel, as this is the default panel for a ListBox (see Figure 8).

Figure 8. Blend creates a StackPanel as the default PanelTemplate.

This is the panel that we are going to replace with the Silverlight Toolkit WrapPanel. Let’s do that now:

In the Objects and Timeline panel, select the StackPanel.
Click Delete.
Click on the Asset Library tool in the toolbar (it is the second to last tool on the toolbar).
In the search field, type wrap and you should see the Silverlight Toolkit WrapPanel, as I do in Figure 9.
Figure 9. If you added the Silverlight Toolkit reference correctly, you will see the WrapPanel in the Asset Library.
The WrapPanel will now become the very last tool on the toolbar (called the Last Used Tool).
Double-click the Last Used tool (now showing the WrapPanel) and you will see a WrapPanel in your Objects and Timeline panel like I have in Figure 10.
Figure 10. When you double click the WrapPanel it will now be in your objects and Timeline panel.
Now you need to get out of the Panel Template and return to the scope of the UserControl. You can do this by clicking the Return to Scope icon, as I am doing in Figure 11.
Figure 11. Click the Return to Scope icon to stop editing the Panel Template.

Add ListBoxItems to the ListBox

Now it is time to start to populate the ListBox with ListBoxItems. To do this:

Go to the Objects and Timeline panel and Right-click the ListBox.
Click Add ListBoxItem, as I am doing in Figure 12.
Figure 12. Add a ListBoxItem.

Now, to save time, I like to just select the newly created ListBoxItem in the Objects and Timeline panel and press Control+C to copy and Control+V to paste. I do this until I have about five ListBoxItems. Do this and your project should look like what I have in Figure 13.

Figure 13. Your ListBox should now have five ListBoxItems.

But wait, did you notice that the fifth ListBoxItem was created outside of the ListBox (and not in view)? This is happening because, if a ListBox has content that is larger than its container, it will simply add a Scrollbar, either horizontally, vertically, or both if needed. We need to change the ListBox to not have any vertical scrollbars.

Select the ListBox in the Objects and Timeline panel.
Go to the Properties panel.
In the search box near the top of the Properties panel, type the word “horizontal”.
You will then see the HorizontalScrollBars dropdown.
Click the dropdown and then click Disabled, as I am doing in Figure 14.
Figure 14. Set the HorizontalScrollbars property Disabled.

You will notice that right away, your ListBox wraps its content so it now has three columns! See Figure 15.

Figure 15. Once you set the HorizontalScrollBar property to Disabled the ListBox will then wrap its content into three columns.

If your ListBox shows four columns simply use the selection tool (Shortcut: A key) and resize your ListBox to be a little less wide and your ListBox will show three columns.

You can now add more ListBoxItems so that you have a fully populated three column ListBox, as I have in Figure 16.

Figure 16. A fully populated three column ListBox.

Summary

So you have done it! That is, you have created a new Silverlight 3 project with a ListBox. You then installed the Silverlight Toolkit and then placed a reference to the System.Windows.Controls.Toolkit.dll into your project. You then created a new Item Panel Template and then used the Silverlight Toolkit WrapPanel as your new Panel. You then set the HorizontalScrollBar property of your ListBox to Disabled. This allowed you to have a three column ListBox. Look for my next article on how to create a ListBox DataTemplate that allows you to specify exactly how a ListBox will present its content.