SandShell for WPF Documentation

Using the WunderBar

Back to Table of Contents

Creating a WunderBar

The WunderBar class is an ItemsControl which means it can be used bound or unbound. It contains a collection of WunderBarPane objects, which have a header, an image and some contents which are displayed when the pane is selected. This documentation will assume you are using XAML to configure these objects but of course it can easily be done in code too. SandShell is geared towards XAML configuration, and the first thing you need to do is to ensure you have declared an XML namespace to represent the SandShell classes:

<Window ... xmlns:ss="http://schemas.divelements.co.uk/wpf/sandshell">

You can thereafter use the ss: prefix to instantiate SandShell classes. To create a very simple WunderBar with a few panes, all of which have headers, use the following XAML:

<ss:WunderBar>
	<ss:WunderBarPane Header="Pane One" />
	<ss:WunderBarPane Header="Pane Two" />
	<ss:WunderBarPane Header="Pane Three" />
</ss:WunderBar>

If you run your project at this point, the WunderBar will appear and you will be able to switch between the panes. You will also be able to use the chevron menu to control the number of pane buttons visible in the body of the control and to show and hide individual pane buttons.

Adding and Manipulating Panes

To add panes with the designer, right-click the WunderBar and choose the Add Pane option. In the designer you can also switch between panes as you would at runtime; by clicking their buttons.

You will want to associate an image with each pane. Use the Image property for this; the designer propertygrid presents a list of images in your project for you to choose from. Adding contents to a pane is easy: a pane contains one child, just like a window, so choose your layout container (such as a Grid) and specify it as the child of the pane. The designer will then allow you to add more children to the grid using drag and drop.

To change the order of the panes within the control, you can either manipulate the XAML by cutting and pasting or you can right-click any pane and use the Order commands to bring it forward or send it backward relative to other panes. The ShowPanes property of the WunderBar dictates how many of the panes have their buttons displayed in the main portion of the control. All remaining panes after this number have smaller buttons displayed at the bottom of the control.

Resizing and Collapsing

By default, the user is allowed to resize the WunderBar with an integral splitter control. Its size is determined by the ContentSize property. You should not attempt to assign a specific width to the control with its Width property as this is automatically determined by the ContentSize property and whether the control is collapsed or not. To disable the integral splitter, set the AllowResize property to false.

The user is also allowed to collapse the control by default. When collapsed, the control takes up very little space and the contents of the selected pane are hidden until the user clicks to reveal them in a popup. You can programmatically collapse the control using the IsCollapsed property, and prevent the user from being able to collapse it by setting the AllowCollapse property to false.

Responding to the Selected Pane

Although the contents of the selected pane are automatically presented inside the WunderBar, normally you will wish other parts of your user interface to change when the selected pane is changed too. We expose the SelectedPaneChanged event if you should need to programmatically change things based on this.

The best way, though, to control visibility of parts of your user interface that are dependent on the selected pane, is to use binding. The selected pane has the Selector.IsSelected attached property set to true, so by binding to this property (and running the value through a BooleanToVisibilityConverter) you can automatically have different parts of your application showing in response to the selected page being changed without writing any code.

Here is an example of a WunderBar with a textbox displayed next to it that is only visible when the first pane is selected.

<Window ... >
	<Window.Resources>
		<BooleanToVisibilityConverter x:Key="b2v" />
	</Window.Resources>

	<DockPanel>
		<ss:WunderBar DockPanel.Dock="Left">
			<ss:WunderBarPane Name="paneOne" Header="Pane One" />
			<ss:WunderBarPane Header="Pane Two" />
			<ss:WunderBarPane Header="Pane Three" />
		</ss:WunderBar>
		<TextBox Visibility="{Binding ElementName=paneOne, Path=(Selector.IsSelected), Converter={StaticResource b2v}}" />
	</DockPanel>
	
</Window>