SandRibbon User Guide

Customization

Back to Table of Contents

Fixed Customization

We use the term fixed customization to refer to the set of full-fledged controls on the quick access toolbar that are created at design time, or programmatically added. These will normally be buttons. When fixed customization is active the user is able to control the visibility of these commands through the chevron menu next to the quick access toolbar. When dropped down, the menu lists all the controls with their text and a check mark if they are currently visible. When unchecked the controls are hidden, but not removed, from the toolbar.

This mode is useful for smaller applications that do not require arbitrary cloning of controls onto the quick access toolbar but do have some commonly-used commands to show there. To hide a control by default, change its Visible property at design time like you normally would. The user can then choose to show them again at runtime.

Fixed customization is enabled when the Customization property of your RibbonManager is set to Fixed or Full.

Introducing Shortcuts

Version 1.6 of SandRibbon introduced full user customization, as seen in Office. This refers to the ability of the user to add shortcuts to arbitrary ribbon controls to the quick access toolbar. This is achieved with the Shortcut class, which you do not typically use directly but is a special kind of button that serves as a shortcut to another item (which may or may not be a button). The shortcut automatically reflects the enabled and checked states of its target, and also updates its image and dropdown properties like a clone of the original.

To create a shortcut to an item at design time, right-click it and choose Create Shortcut. The shortcut appears in the quick access toolbar by default but can be moved to any container that accepts a normal button. At runtime, use the AddShortcut and RemoveShortcut methods of your quick access toolbar. Note that persistence of shortcuts created at runtime (either programmatically or by the user) will not work unless full customization is enabled at design time (see below).

The Button, Gallery and MenuItem controls all support the creation of shortcuts. These account for the vast majority of clickable controls seen on ribbon layouts. The link between a control and its shortcut is provided by the ShortcutBinding class, but you will not need to use this unless developing your own controls for the ribbon, in which case you specify the type of ShortcutBinding-derived class to use for your control by overriding its ShortcutBindingType property..

Full Customization

When full customization is on, the user can right-click on a control in the ribbon and, if that control supports creating a shortcut (most do) there will be an option to add it to the quick access toolbar. The option will be disabled if there is already a shortcut to that item. The user can subsequently remove the shortcut by right-clicking it and choosing the remove option.

Full customization is enabled when the Customization property of your RibbonManager is set to Full.

Standard Shortcuts

In Office 2007, the user has full customization abilities and is therefore able to right-click arbitrary ribbon controls and add shortcuts to them to their quick access toolbar. However, the designers noticed that there were a small selection of commands that the user would be most likely to want to add. They therefore implemented a scheme whereby when the chevron by the quick access toolbar is dropped down, a menu shows a list of common commands available for adding. Commands already added are checked.

In SandRibbon, we expose this functionality with the StandardItems property of the QuickAccessToolBar. This currently cannot be configured at design time, but you simply assign an array of controls to it at runtime and those controls become your "standard shortcuts" available for adding to the toolbar. If the StandardItems property has been set, the user can create shortcuts in this manner regardless of the user-customization level that has been set.

Persisting Ribbon State

Every SandRibbon item has a potential Guid property to uniquely identify it in a layout. This property is only used when you have enabled user customization. Use the Customization property of your RibbonManager to control the customization experience of the user.

The complete state of your ribbon layout can be obtained at any time with a call to the GetState method on your RibbonManager. The best place to call this is in the Closing event of the form your ribbon layout is on. The string returned from that method can be persisted to the storage medium of your choice and read back later. To restore a layout, call the SetLayout method from the Load event of your form, passing the same string back.

Information included in serialized ribbon state includes the recent documents list, the position of the quick access toolbar, whether the ribbon is minimized, the size of resizable galleries, visibility of quick access toolbar commands (fixed or full mode) and the shortcuts created to other ribbon commands (full mode only).