SandRibbon for WPF User Guide
Extending the Ribbon
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. The ApplicationPopup class is just like an ordinary popup, only it contains a few 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 replace the recent documents display entirely, assign a different control to the popup with 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.
Menu items placed in the application popup function just like any other, except that where they contain a popup, that popup will open over the recently-used documents list in the right-hand side of the popup.
<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>
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>
You can create as many of these contexts as you like. Note that each context has a textual reference. This reference is used for simplicity later to assign certain ribbon tabs to that 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>
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. 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"].Enabled = true;
}
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. 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 start to disappear, but the user can still access them through its chevron button. The button can also be used by the user to change the position of the toolbar or to minimize the ribbon.
SandRibbon version 1.0 does not currently support customization of the quick access toolbar, but will do so in a future release.
<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 Color Schemes
The color scheme in use depends on which SandRibbon resource dictionary is loaded. By default the Blue scheme is loaded. At design time, you can specify a different color scheme by including one in the resources for your window, by adding it to the merged dictionaries collection. Here is an example of specifying a different color scheme for a window:
<Window ... > <Window.Resources> <ResourceDictionary> <ResourceDictionary.MergedDictionaries> <ResourceDictionary Source="/Divelements.SandRibbon;component/Rendering/Silver.xaml" /> </ResourceDictionary.MergedDictionaries> </ResourceDictionary> </Window.Resources> <TextBox /> </Window>
The window attributes and the rest of the window (including the ribbon) have been omitted from the above example for clarity. The example simply shows applying a different color scheme to all ribbon controls within. Possible values are Silver, Blue, Black and System.
At runtime, SandRibbon offers a helper function to make this a bit easier. Just call the static SetColorScheme method on the Ribbon class, passing the object on which to set the scheme (usually your window) and a member of the RibbonColorScheme enumeration corresponding to the above color schemes. SandRibbon will then automatically load the appropriate resource dictionary and merge it for you.
private void OnButtonClick(object sender, EventArgs e)
{
Divelements.SandRibbon.Ribbon.SetColorScheme(this, Divelements.SandRibbon.RibbonColorScheme.Black);
}