SandRibbon for WPF User Guide

Advanced Topics

Back to Table of Contents

User Customization

In Office, the ribbon is heavily customizable by the user. SandRibbon allows you to make some of this customization functionality available to your users, too. We've already covered one of the most basic aspects of customization: the ability for your users to adjust the size of the galleries in your ribbon.

Basic Customization: Shortcuts

The quick access toolbar can optionally display shortcuts to other controls on the ribbon. You may wish to have a Save button both in your application menu and on the quick access toolbar. Use the Shortcut control, which derives from Button, to create a shortcut on the quick access toolbar to another control in your ribbon:

<sr:Ribbon.ToolBar>
	<sr:ToolBar>
		<sr:Shortcut Target="{Binding ElementName=saveMenuItem}" />
	</sr:ToolBar>
</sr:Ribbon.ToolBar>

In the designer, you can create a shortcut to a ribbon item by right-clicking on it and selecting Add to Quick Access Toolbar. This functionality requires that the control has an explicit name defined in your XAML.

Shortcuts can exist amongst "real" buttons and other controls on the toolbar. You can also use the attached ToolBar.IsStandardShortcut property on some controls in your ribbon, and when set to true, they are presented as options in the quick access toolbar's dropdown menu to facilitate easy adding to and removing from the toolbar. In Word, various commands like Open, Save, Quick Print and Undo are available as standard shortcuts.

<sr:MenuItem Text="_New" Image="/Icons/32/new.png" sr:ToolBar.IsStandardShortcut="True" />

More Commands

Office exposes a "More Commands..." option within the quick access toolbar that brings up an extensive customize user interface. We do not offer this interface as part of SandRibbon because it is very application-specific, but we do offer the option to show this menu item by setting the ShowMoreCommands property on your toolbar to true. The menu item is bound to the Ribbon.MoreCommandsCommand field, so you will need to handle this command in your window to hook its activation.

Full Customization

By setting the AllowCustomize property on your ribbon to true, you can allow the user to create shortcuts themselves to virtually any controls on your ribbon and in your menus. They do this by right-clicking the controls and making use of their context menus, which appear only when full customization is enabled.

State Serialization

Now that the user can potentially alter gallery sizes, configure which of the standard shortcuts are visible on the toolbar and even add a shortcut to virtually any control on there, these settings will need to be saved from one application session to the next. We provide the SerializeState and RestoreState methods on the Ribbon class to make this easy. State information is stored in a string containing XML, so your application can store it in the medium of your choice. Call the former method in the Closing event of your window and the latter method in the Loaded event.

private void RibbonWindow_Closing(object sender, System.ComponentModel.CancelEventArgs e)
{
	string s = ribbon.SerializeState();
	// TODO save the string somewhere
}

private void RibbonWindow_Loaded(object sender, System.EventArgs e)
{
	string s;
	// TODO load the string from somewhere
	ribbon.RestoreState(s);
}

Advanced ICommand Integration

We have already covered how SandRibbon buttons and menu items can be bound to commands through the standard ICommand pattern. But what about the situation where a command is more than just enabled: what about when it can also be checked? There is no WPF support for such a concept but we have extended the commanding pattern to make it easy.

Luckily, standard WPF commanding does include the concept of a command parameter, which you can set on items designed to invoke commands. This is often not used, however, so when there has been no parameter specified we pass an instance of a class implementing ICheckableCommandParameter to your CanExecute handler. This interface exposes one property, Checked, which is of type Nullable<bool>. If you leave it alone, nothing happens, but if you set it to true or false in your CanExecute handler, the button or menu items which is querying the command will set its IsChecked property automatically. This makes SandRibbon commanding even more powerful.

Here's an example of how you might extend a CanExecute handler for the Bold command in a RichTextBox:

private void OnTextBoxCanExecute(object sender, CanExecuteRoutedEventArgs e)
{
	ICheckableCommandParameter checkable = e.Parameter as ICheckableCommandParameter;
	if (checkable != null)
	{
		if (e.Command == EditingCommands.ToggleBold)
		{
			object fontWeightValue = textBox.Selection.GetPropertyValue(FontWeightProperty);
			if (fontWeightValue != DependencyProperty.UnsetValue)
			{
				FontWeight fontWeight = (FontWeight)fontWeightValue;
				checkable.IsChecked = fontWeight == FontWeights.Bold;
			}
		}
	}
}

Localization

There are many places in SandRibbon where English language strings are displayed: in the customization menus and in tooltips, for example. We provide a class called RibbonLanguageStrings which is designed specifically to provide a container with properties for all the standard strings displayed throughout the ribbon.

To specifiy your own values for these strings, set the LanguageStrings property on your ribbon. This can be done in XAML or at runtime. Here is an example setting some of the available properties on this class, and assigning the class to a ribbon:

<sr:Ribbon>
	<sr:Ribbon.LanguageStrings>
		<sr:RibbonLanguageStrings
			ExpandTheRibbonToolTip="Make it Bigger!"
			MinimizeTheRibbonToolTip="Make it Smaller!"
			/>
	</sr:Ribbon.LanguageStrings>
</sr:Ribbon>