Customizing the QAT

Actipro Ribbon supports complete run-time customization of the Quick Access ToolBar (QAT) by the end user via the use of context menus and also Customize QAT dialog windows.

Ribbon has built-in support for all customization capabilities found in Office. You can even clone an entire Group and place it in the QAT.

Quick Tips

Many more details on configuring all aspects of QAT customization at described below but here are some quick tips to get you started.

By default, end-user QAT customization is enabled. This means that auto-generated context menus for controls that support QAT customization will have items that let them be added to and removed from the QAT. You can disable this default behavior by setting the Ribbon.IsQuickAccessToolBarCustomizationEnabled property to false.

However, if you keep that true, certain control types will be able to be added to or removed from the QAT by default. Most ribbon controls support this behavior by default and other controls do not. The CloneService.CanCloneToQuickAccessToolBarProperty attached property can be assigned to any control to configure whether it does support QAT customization.

There are many other QAT customization features and options described in the sections below, including adding common QAT items, displaying a Customize QAT dialog, and more.

All About Cloning

When controls are added to the QAT, other than at design-time, they are generally added as a clone of another existing control. The clone is essentially a duplicate deep copy of a control, with all its dependency property and item collections copied.

The CloneService is the class the provides management and tracking of clones. All of the built-in QAT customization features described below harness the CloneService to support modification of the QAT.

CloneService Important Members

The CloneService class has some important members that you can use to help track clones if you need them.

Cloning Events

Several CloneService attached events occur during the clone creation/disposal lifecycle.

Using the Id Property to Mark Duplicate Controls with the Same Functionality

Controls of the same type and functionality should only be able to be added to the QAT once. Say you had an Open menu item on the application menu but also in a menu for a popup button that appears on the Home tab of your ribbon. In this scenario both menu items perform the same command and should be treated as identical controls for the purposes of dealing with QAT customization. If you add one of the controls to the QAT (which creates a clone of that control), when you show a context menu for the other control, it should have its Add to Quick Access Toolbar menu item disabled. This can be accomplished via the use of the Id property.

The RibbonControlService defines the attached Id property. It is also defined on all the ribbon control base classes. The use of the Id property is completely optional but in cases where you have multiple instances of controls with the same functionality in your ribbon, it should be used.

In the scenario described above, you could set the Id of both Open menu items to FileOpen. When Ribbon examines your controls to determine if they have already been added to the QAT, it will see that both menu items are the same control type (a Button) and they both have the same Id. That is how it will determine that they have the same functionality.

Determining Which Controls Can Be Cloned to the QAT

The CloneService.CanCloneToQuickAccessToolBarProperty attached property can be assigned to any control to allow it to be added to the QAT by the end user. This property defaults to false in general but for most ribbon controls, it defaults to true. Therefore you probably will never need to worry about setting it.

Controls eligible for cloning to the QAT must also have a RibbonControlService.LabelProperty attached property defined. Note that this property is also more readily available on all ribbon controls via the Label property. The label is used to help represent the control in the Options window's QAT items lists (see below).

Customizing the QAT Via Context Menus

The fastest way to customize the QAT at run-time is to use context menus on ribbon controls. If the Ribbon.IsQuickAccessToolBarCustomizationEnabled property is set to true, the default, Ribbon will automatically add appropriate menu items to context menus for ribbon controls.

A control's context menu showing the Add to Quick Access Toolbar menu item

Ribbon controls that are not in the QAT will have an Add to Quick Access Toolbar menu item. Clicking an add menu item will create a clone of the control and add it to the QAT. This functionality is even available for Group controls.

Ribbon controls that are in the QAT will have a Remove from Quick Access Toolbar menu item. Clicking the remove menu item will remove the control from the QAT, and if it is a clone, will dispose the tracking of the clone.

Showing Common QAT Items on the QAT's Customize Menu

The QAT's Customize button menu can optionally show a list of common items that can be added to the QAT. If any are already listed on the QAT, they will appear checked.

The Quick Access ToolBar's Customize menu, showing some common QAT items

You may define the template common QAT controls by adding them to the Ribbon.QuickAccessToolBarCommonItems collection. The controls in this collection are never directly used, however they will appear in the list of common QAT items in the QAT Customize button's menu. When an unchecked common QAT control menu item is clicked, a clone of the control will be created and added to the QAT.

It is imperative that the controls defined in the QuickAccessToolBarCommonItems collection have Id properties (see info on Id property in a section above) set on them. For instance, the Save button is defined explicitly on the QAT at design-time, but also in the QuickAccessToolBarCommonItems collection, and on the application menu. All three places should have the Id property set to something like File.Save so that Ribbon knows they are identical controls in terms of functionality.

Displaying a 'More Commands'/'Customize Quick Access Toolbar' Item on Auto-Generated Control Context Menus

A More Commands menu item can be added to the QAT Customize button's menu and a Customize Quick Access Toolbar menu item can be added to any auto-generated ribbon control context menus.

A control's context menu showing the Customize Quick Access Toolbar menu item

Set the Ribbon.IsCustomizeQuickAccessToolBarMenuItemVisible property to true to enable the addition of these menu items.

These menu items all trigger the RibbonCommands.CustomizeQuickAccessToolBar command. Add a handler for that command in your application, and in your handler, show an Options window with its Customize QAT page displayed.

Implementing an Options Window With Complete QAT Customization Functionality

We've implemented a demo Options window in the Sample Browser's Document Editor QuickStart for Ribbon. This window uses a UserControl in the Sample Browser's Ribbon Common folder called CustomizeQat. The CustomizeQat control contains all the functionality needed to get the QAT customization functionality working like in the screenshot below.

A sample Options window that has complete QAT customization capabilities

The full source for the window and UserControl are in the Sample Browser project. We encourage you to copy the CustomizeQat control to your own project and to modify it as necessary. But it provides out-of-the-box functionality like what you find in Office.

Using the CustomizeQat UserControl in Your Application

To use the CustomizeQat control in your own application, simply copy it to your project. Then add it to your project's Options window. When the Options window is created, be sure to set its Ribbon property to an instance of the Ribbon to customize. This is how the control knows to bind itself to a Ribbon.

When your Options window's OK button is pressed, you must call CustomizeQat.Save to persist the changes into the Ribbon's QAT. If the Options window was closed without the OK button being pressed, you must call CustomizeQat.Cancel to properly dispose any ununsed clones that were created while the customization was occurring.

CustomizeQat UserControl Implementation Info

Although you generally won't need to change the contents of the CustomizeQat control, here is a quick overview of how it works in case you do.

First, a static method on the RibbonControlCustomizationCategory class provides a default list of RibbonControlCustomizationCategory objects. There is one category for the application menu and one for each the tabs that are defined on the Ribbon. This list is bound to the Choose commands from combobox in the screenshot above.

When a selection is made in that combobox, the listbox below it is populated by binding it to the results of a call to RibbonControlCustomizationCategory.GetControls. This method returns a list of all the controls contained within that category's source object (application menu, tab, etc.). This is a recursively created list so even menu items on ribbon control popups will be included. The list is a collection of RibbonControlReference objects, which contain references to the source object that they represent.

The list on the right contains the items currently in the QAT. It also is bound to a list of RibbonControlReference objects that was created by a call to RibbonControlCustomizationCategory.GetQuickAccessToolBarItems.

The Add button adds a new control clone of the selected item in the available controls list to the QAT items list. The Remove button removes the selected QAT item from the list. The mover buttons on the right allow you to reorder controls in the QAT items list.

Upon a call to the CustomizeQat.Save method, the RibbonControlCustomizationCategory.SetQuickAccessToolBarItems method is executed, which updates the Ribbon's QAT with the items designated in the QAT items list.

Persisting Customized QAT Items in User Settings

The current items and their order can be persisted to an XML string via a single method call to Ribbon.SerializeQuickAccessToolBarItems. You can save this string to your user settings mechanism before your application closes.

When the user starts up the application again, get the XML string and pass it to Ribbon.DeserializeQuickAccessToolBarItems to restore the user's QAT customizations.

The DeserializeQuickAccessToolBarItems method returns a collection of Exception objects. Under normal circumstances, this collection will be empty, indicating that there were no problems when deserializing the saved data. However, if a problem did occur and one or more items could not be reloaded, there will be one related Exception entry in this collection for each item that could not be reloaded. This will help you debug what the problem is while still allowing other items to be successfully loaded.