SandRibbon for WPF User Guide

Extending the Ribbon

Back to Table of Contents

The Application Popup

The application popup is assigned to the ribbon with its ApplicationPopup property, and is displayed when the user clicks on the application button, which is a glassy orb in the Office 2007 theme and a coloured File button in the Office 2010 theme. The ApplicationPopup class is just like an ordinary popup, only it contains a couple of extra controls. The popup itself typically only directly contains MenuItems with large images.

The pane on the right of the application popup can contain any kind of control, but by default it contains a display for your application's recently-used documents list. This list is exposed with the RecentDocuments property, which is a special class that looks after the paths to files that have been recently used. The heading for the pane is "Recent Documents" but can be customized or localized with the RecentDocumentsText property. To put your own control in the right-hand pane, completely replacing the Recent Documents display, assign your control to the RecentDocumentsControl property. If you use the default recently-used documents display, you hook the OpenDocument event on the ApplicationPopup to be notified when the user picks a document from the list.

An application popup contains two buttons at the bottom, normally used for showing application options and exiting the application. Their text can be changed from the default with the ExitText and OptionsText properties, and their images can be changed with the ExitImage and OptionsImage properties. The Exit button automatically closes the main window when clicked, and the Options button fires the ShowOptions event. The controls can be hidden altogether with the ShowOptionsButton and ShowExitButton properties.

<sr:Ribbon.ApplicationPopup>
	<sr:ApplicationPopup>
		<sr:MenuItem Text="_New" Image="/Icons/document.png" />
		<sr:MenuItem Text="_Open" Image="/Icons/folderopen.png" />
		<sr:MenuItem Text="_Save" Image="/Icons/blankcd.png" />
		<sr:MenuItem Text="Save _As" Image="/Icons/cdmusic.png" IsSplit="True">
			<sr:RibbonPopup>
				<sr:Heading>Save a copy of the document</sr:Heading>
				<sr:Menu>
					<sr:MenuItem Text="_Word Document"
						Description="Save the document in the default file format."
						Image="/Icons/cdmusic.png" />
					<sr:MenuItem Text="_Word Document"
						Description="Save the document in some other file format."
						Image="/Icons/cdmusic.png" />
				</sr:Menu>
			</sr:RibbonPopup>
		</sr:MenuItem>
		<Separator />
		<sr:MenuItem Text="_Close" Image="/Icons/error.png" />
	</sr:ApplicationPopup>
</sr:Ribbon.ApplicationPopup>

In the designer, you can add an application popup to your ribbon by simply clicking on the application button. If no popup exists, one is created, otherwise it is opened. Unfortunately the Visual Studio 2010 designer does not support designing inside popups, so you will need to define its contents using XAML, as above.

Keyboard Access

It is very important that all your buttons, menu items and other relevant controls have a means of access via the keyboard. The user can of course tab to your controls, but the ribbon user interface also supports quick access keys. Quick access keys can be applied to any control by using the KeyboardAccess.Keys attached property. You should apply them to your ribbon tabs as well as the controls within.

The quick access keys assigned to a control can be any length but will normally be one or two characters. When the user hits the Alt key, the quick access keys for top-level ribbon elements are shown. This is normally controls on the toolbar, the application button and the ribbon tabs themselves. Having chosen a ribbon tab, the quick access keys for all the controls on that tab are shown. By continuing to press keys the user quickly finds the control they want and activates it.

Quick access keys can also be assigned implicitly. If you use the underscore syntax to choose a mnemonic for a menu item or button, that automatically becomes the quick access key for the control. This is typically done only with menu items.

Creating Contextual Tabs

Along with the normal Home, Insert, etc tabs in your application you will want special contextual tabs that are only enabled when certain elements are selected or your application is in a specific state. Defining and using these is very easy. First, you need to define some editing contexts within your ribbon. These contexts have names, colors and can be enabled or disabled. To take another example from Word, you might have an editing context called Picture Tools that is only enabled when the user has selected a picture. First you need to create the editing context and assign it to the EditingContexts collection of your ribbon:

<sr:Ribbon Name="ribbon1">
	<sr:Ribbon.EditingContexts>
		<sr:EditingContext Text="Picture Tools" Reference="PICTURE" Color="Orange" />
	</sr:Ribbon.EditingContexts>

Or, using the designer, you can edit the EditingContexts property of the ribbon directly in the propertygrid using the collection editor. The Text, Reference and Color properties are all required.

You can create as many of these contexts as you like. The reference property must be unique within the ribbon and is used to associate tabs with the editing context. Now, create a new tab in your ribbon, and after setting its Text property, you will also set its EditingContextReference property. This needs to match up with the reference of the editing context to which you want it to belong. In this case we want it to belong to the picture tools context. For this example we are only specifying one tab as belonging to the editing context, but you could have any number of tabs assigned.

<sr:RibbonTab Text="Format" EditingContextReference="PICTURE">
	<sr:RibbonGroup Header="Adjust" />
</sr:RibbonTab>

In the designer, you can use the propertygrid to set the EditingContextReference of your tab. Setting the property this way, you are presented with a dropdown list of all the available editing context references for selection.

If you ran your application now, you wouldn't see your new tab. That's because you need to enable the editing context at runtime, but only when the user should have access to the controls within. Use the Activate method of an editing context to make it available, and the Deactivate method to hide it again. The Activate method takes a parameter which controls whether the first tab within the editing context is selected as part of the activation. As a test, we can add a button to the window and simply put the code to enable the editing context in its Click event.

private void OnButtonClick(object sender, EventArgs e)
{
	ribbon1.EditingContexts["PICTURE"].Activate(Divelements.SandRibbon.EditingContextActivateMode.ShowTabsAndSelect);
}

Quick Access Toolbar

You can associate a toolbar with your ribbon, which will then either be displayed in the titlebar or underneath the ribbon. To do this, create a toolbar and assign it to the ribbon's ToolBar property. You can do this in XAML or in the designer by right-clicking the ribbon and choosing Add Quick Access Toolbar. We provide a ToolBar class based on the stock WPF toolbar but with special drawing and other features to make it fit in with SandRibbon. Once a toolbar is assigned you can use the ToolBarPosition property of the ribbon to set its position.

When the toolbar is short of space its items automatically move into the menu accessible via the chevron displayed at the end. This button can also be used by the user to change the position of the toolbar, to minimize the ribbon or to access any customization features that have been enabled.

<sr:Ribbon.ToolBar>
	<sr:ToolBar>
		<sr:Button Text="Save" Image="/Icons/save.png" ToolTip="Save" NormalSize="Small" />
		<sr:Button Text="Undo" Image="/Icons/undo.png" ToolTip="Undo" NormalSize="Small" >
			<sr:RibbonPopup />
		</sr:Button>
		<sr:Button Text="Print" Image="/Icons/print.png" ToolTip="Print" NormalSize="Small" />
	</sr:ToolBar>
</sr:Ribbon.ToolBar>

Choosing the Theme and Color Schemes

The default theme used by SandRibbon is Office 2010, with the Silver colour scheme. We provide an Appearance property on the RibbonWindow to make switching between the supported themes (Office 2007 and Office 2010) and colour schemes (blue, silver, black and system) easy.

<sr:RibbonWindow ... Appearance="Office2010Blue">

Alternatively, if you are not using the RibbonWindow class you can apply a theme in code by using the static Ribbon.SetColorScheme method, which takes an element to which you wish to apply the style (typically your top-level container) and the style to apply.

private void OnButtonClick(object sender, EventArgs e)
{
	Divelements.SandRibbon.Ribbon.SetColorScheme(this, RibbonAppearance.Office2007Black);
}

Super Tooltips

SandRibbon applies special styles to the tooltips configured for its controls, making them much more flexible than standard WPF (and Windows) tooltips. The standard ToolTip property is still used, but is supplemented by attached Description, Image, HelpText and AutoSize properties. When a description is specified, the text specified in the ToolTip property becomes a heading with the description shown underneath. The tooltip for the Bold button in Word is therefore created as follows:

<sr:Button Command="EditingCommands.ToggleBold" ToolTip="Bold" sr:SuperToolTip.Description="Make the selected text bold." />

When an image is specified for a tooltip, it is shown justified to the left of the text. The size is not adjustable so ensure that the image is the correct size when specifying it.

When help text is specified it is shown underneath, with a help icon. This text may take the form of "Press F1 for more information". If it does, your handler for the F1 key will need to know if a super tooltip is open, and over what control. The SuperToolTip class exposes a static property called LastShowingOverControl which returns the control over which a SandRibbon tooltip is currently displayed. Once the tooltip has gone, the property is reset to null.

Next: Dynamic Resizing