SandRibbon for WPF User Guide

Getting Started

Back to Table of Contents

Using SandRibbon with XAML

The examples herein will mostly assume you are using XAML to configure your ribbon. Once you have added a reference to the SandRibbon assembly from your application you simply need to define its namespace in any XAML files in which you will use ribbon controls. Just add the xmlns:sr namespace attribute to your top-level element like so:

<Window ... xmlns:sr="clr-namespace:Divelements.SandRibbon;assembly=Divelements.SandRibbon">

The ellipsis above represents other attributes of your Window which have been removed for clarity.

Ribbon Elements

A ribbon user interface usually consists of many controls and components that come together to provide your application with a great look and feel. The top-level control you will use is the Ribbon class. The ribbon itself has a collection of tabs that are shows as child controls, and properties for configuration of the ribbon itself. You can assign your application's icon to the ribbon for display in the application button, and it exposes the selected tab. The ribbon can also be programmatically minimized.

Within a ribbon are usually several RibbonTab class instances. These are added to the Tabs collection of the ribbon. Each ribbon tab has text associated with it. Your application will typically have a Home tab first, followed by several other tabs devoted to normal tasks in your user interface.

Lastly, within a ribbon tab are several RibbonGroup class instances which collect the ribbon controls on each tab into groups. The Home tab in Microsoft Word, for example, has Clipboard, Font, Paragraph, Styles and Editing groups.

The following is an example of defining a ribbon with the first three tabs from Word, with the first tab fully populated with groups (the groups themselves are not yet populated with controls though). This will produce a simple interface like the one shown above.

<sr:Ribbon>
	<sr:RibbonTab Text="Home">
		<sr:RibbonGroup Header="Clipboard">
		</sr:RibbonGroup>
		<sr:RibbonGroup Header="Font">
		</sr:RibbonGroup>
		<sr:RibbonGroup Header="Paragraph">
		</sr:RibbonGroup>
		<sr:RibbonGroup Header="Styles">
		</sr:RibbonGroup>
		<sr:RibbonGroup Header="Editing">
		</sr:RibbonGroup>
	</sr:RibbonTab>
	<sr:RibbonTab Text="Insert" />
	<sr:RibbonTab Text="Page Layout" />
</sr:Ribbon>

Using RibbonWindow

We supply a special window class, RibbonWindow, with SandRibbon so you can get the custom-shaped forms like Office provides. These windows are just like regular windows except they assume a custom shape when required, and support Aero Glass when running in Windows Vista automatically. You can use RibbonWindow instead of Window throughout your application, regardless of whether the window actually contains a ribbon. Along with its normal Title property you can also specify an ApplicationName, which the window displays next to its normal title.

If you do choose to display a ribbon in your ribbon window (as you usually will) you need to do it in a slightly special way. Because a ribbon is integrated into the chrome of your window you don't include it along with the rest of the window content, instead you specify it for the Ribbon property of the window itself.

To use RibbonWindow, first create a normal window then, once you have included the SandRibbon namespace as shown above, change the root element from Window to sr:RibbonWindow. You'll also need to go into your codebehind file and change the class definition so it inherits Divelements.SandRibbon.RibbonWindow, to match.

<sr:RibbonWindow x:Class="DemoApplication.Window2"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
	xmlns:sr="clr-namespace:Divelements.SandRibbon;assembly=Divelements.SandRibbon"
    Title="My Window" ApplicationName="Acme Application" Height="300" Width="300"
    >
	<sr:RibbonWindow.Ribbon>
		<sr:Ribbon>
			<sr:RibbonTab Text="Home">
				<sr:RibbonGroup Header="Clipboard">
				</sr:RibbonGroup>
				<sr:RibbonGroup Header="Font">
				</sr:RibbonGroup>
				<sr:RibbonGroup Header="Paragraph">
				</sr:RibbonGroup>
				<sr:RibbonGroup Header="Styles">
				</sr:RibbonGroup>
				<sr:RibbonGroup Header="Editing">
				</sr:RibbonGroup>
			</sr:RibbonTab>
			<sr:RibbonTab Text="Insert" />
			<sr:RibbonTab Text="Page Layout" />
		</sr:Ribbon>
	</sr:RibbonWindow.Ribbon>

	<TextBox Margin="30" />
</sr:RibbonWindow>

Note that the content of the window is simply the TextBox. Normally you might use a Grid or DockPanel to layout further elements in your window. The ribbon itself is not specified as part of the content, but is assigned to the Ribbon property so SandRibbon can embed it into the titlebar.

Next: Ribbon Controls