SandRibbon for WPF User Guide

Getting Started

Back to Table of Contents

Creating a RibbonWindow with the Designer

SandRibbon ships with designer integration to make many tasks easier in Visual Studio 2010 and Expression Blend 4.

To create a new RibbonWindow, right-click on your project, choose Add -> New Item and pick Ribbon Window. SandRibbon installs this template into Visual Studio when the product is installed. A new XAML file will be added to your project with a preconfigured ribbon. You can change the startup window of your project to be this new window by editing your App.xaml file. Double-click to open the designer for your new window and you should see the empty window plus ribbon and statusbar looks something like the figure to the right.

Many elements in the ribbon can be created and controlled with context menus. If you right-click on the titlebar of the ribbon you will see options for creating a new ribbon tab (the default template just includes a Home tab) and creating a quick access toolbar, which many applications have. If you right-click on a ribbon tab, you will see options for creating new groups and adjusting the dynamic resizing behaviors for the tab.

The Home tab will already have one group inside it with the heading "Ribbon Group". This heading, like most properties of SandRibbon controls, can be changed in the property grid when the control is selected. You will probably want to change some of the properties of your ribbon control itself, such as the title, application name and the color or image associated with the application button.

You can place virtually any controls inside groups in the ribbon, and in the Visual Studio Toolbox you will see various SandRibbon controls as well as the standard WPF controls. Some types of controls can only be added through the context menu for a group, because they are closely associated with other panels used specifically for dynamic resizing. Right-click on your group, select Dynamic Resizing and you will see a list of choices for quickly populating the group with controls. Some of the standard WPF controls, such as the TextBox, CheckBox and Slider, are given special styles when they are used inside a ribbon to make them fit in with the general ribbon appearance.

Most of this documentation will give examples in XAML but most actions can be accomplished visually in the designer too.

Using SandRibbon with XAML

If you are using XAML only, you will need to add a project reference to the SandRibbon assembly then add an XML namespace to any XAML files in which you want to use SandRibbon controls. Add the xmlns:sr namespace attribute to your top-level element like so:

<!-- For a normal window -->
<Window ... xmlns:sr="clr-namespace:Divelements.SandRibbon;assembly=Divelements.SandRibbon">

<!-- For a ribbon window -->
<sr:RibbonWindow ... xmlns:sr="clr-namespace:Divelements.SandRibbon;assembly=Divelements.SandRibbon">

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

Creating a RibbonWindow with XAML

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 specify it as the value for the window's Ribbon property, rather than simply including it in a Grid or similar layout panel. This is because SandRibbon includes special processing for the main ribbon and integrates it inside the window chrome.

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.

Ribbon Elements Introduction

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 (ignoring the window) is the Ribbon class. The ribbon has a collection of tabs that are shown as child controls. You will use properties on the ribbon to customize the ribbon as a whole, as integrated with your application. Properties such as Title, ApplicationName, ApplicationButtonImage and ApplicationButtonColor are all used to give the ribbon a distinctive look and feel and help tie it to your product.

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. Groups mainly exist just to group similar controls together, but they also show dialog launcher buttons, designed so that your application can launch a dialog with more commands similar to those in the group. Dialog launcher buttons are shown by default, can be removed by setting the ShowDialogLauncher property to false and raise the LaunchDialog event when clicked. You can also bind a command to the buttons with the DialogLauncherCommand property.

The following is an example 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>

Next: Ribbon Controls