Quick Access Toolbar

The ribbon's Quick Access Toolbar (QAT) can be displayed either above the ribbon (in the window's title bar) or below the ribbon depending on the end user's preference. It provides quick access to the most commonly used commands in your application.

A ribbon quick access toolbar above and below the ribbon

Defining a Quick Access Toolbar

The quick access toolbar can be defined in XAML or code-behind by assigning a RibbonQuickAccessToolBar control instance to the Ribbon.QuickAccessToolBarContent property.

The items to be displayed in the toolbar are assigned to the RibbonQuickAccessToolBar.Items collection. Since the control derives from ItemsControl, items may alternatively be bound into the controls's ItemsSource property.

To make it easy for users to add or remove common items from the toolbar, additional items can be assigned to the RibbonQuickAccessToolBar.CommonItems property. These common items can be accessed from a customization menu to add or remove that item from the Items collection.

This code sample shows how to define the quick access toolbar items for a ribbon.

xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui"
...
<actipro:RibbonContainerPanel>
	<actipro:Ribbon>

		<actipro:Ribbon.QuickAccessToolBarContent>
			<actipro:RibbonQuickAccessToolBar>

				<!-- Common items can be added to the Items collection from a customize menu -->
				<actipro:RibbonQuickAccessToolBar.CommonItems>
					<actipro:BarButton Key="Undo" Command="{Binding UndoCommand}" SmallIcon="{StaticResource UndoIcon}" />
					<actipro:BarButton Key="Redo" Command="{Binding RedoCommand}" SmallIcon="{StaticResource RedoIcon}" />
					<actipro:BarButton Key="Save" Command="{Binding SaveCommand}" SmallIcon="{StaticResource SaveIcon}" />
				</actipro:RibbonQuickAccessToolBar.CommonItems>

				<!-- Only the following items are displayed -->
				<actipro:BarButton Key="Save" Command="{Binding SaveCommand}" SmallIcon="{StaticResource SaveIcon}" />
				<actipro:BarButton Key="Cut" Command="{Binding CutCommand}" SmallIcon="{StaticResource CutIcon}" />
				<actipro:BarButton Key="Copy" Command="{Binding CopyCommand}" SmallIcon="{StaticResource CopyIcon}" />
				<actipro:BarButton Key="Paste" Command="{Binding PasteCommand}" SmallIcon="{StaticResource PasteIcon}" />

			</actipro:RibbonQuickAccessToolBar>
		</actipro:Ribbon.QuickAccessToolBarContent>
		...

	</actipro:Ribbon>
</actipro:RibbonContainerPanel>

XAML Support

Defining the quick access toolbar in XAML may require duplicating some control definitions if the same control is defined, by default, in both the quick access toolbar and the ribbon. Duplication may also be required if a control currently displayed in the quick access toolbar is also included in the common items.

MVVM Support

The quick access toolbar may also be defined by setting the Ribbon.QuickAccessToolBarContent property to a view model that generates a RibbonQuickAccessToolBar control via the ribbon's ItemContainerTemplateSelector.

The optional companion MVVM Library defines a RibbonQuickAccessToolBarViewModel class that is intended to be used as a view model for a RibbonQuickAccessToolBar control, and the BarControlTemplateSelector class in the library generates a RibbonQuickAccessToolBar for that view model.

Customizing the Toolbar Theme

The RibbonQuickAccessToolBar instance can be customized by setting a ControlTheme to the Ribbon.QuickAccessToolBarTheme property. This ControlTheme is applied to the control when it is added to the ribbon.

Quick Access Toolbar Mode

The toolbar visibility can be toggled or completely hidden from the user. The RibbonQuickAccessToolBarMode property gets and sets the toolbar mode. It takes an enumeration of type RibbonQuickAccessToolBarMode.

Toggle Visibility

Setting the mode to Visible will show the toolbar in the desired location and setting the mode to Hidden will hide it from the user interface.

The user can toggle visibility from various menus on the ribbon, like the Options Button.

The Ribbon.QuickAccessToolBarModeChanged event is raised when the mode changes.

Disabling the Toolbar

By default, all ribbons have a quick access toolbar. If the toolbar will not be used, set the Ribbon.QuickAccessToolBarMode mode to RibbonQuickAccessToolBarMode.None. This will prevent the toolbar-related commands from appearing in ribbon menus.

Quick Access Toolbar Location

The toolbar can be located either above or below the ribbon. The Ribbon.QuickAccessToolBarLocation property gets and sets the location of the toolbar. It takes an enumeration of type RibbonQuickAccessToolBarLocation.

The Ribbon.QuickAccessToolBarLocationChanged event is raised when the location changes.

External Host

When the location is set to RibbonQuickAccessToolBarLocation.Above, most users expect the toolbar to be displayed in a titebar. The Ribbon Window supports this feature automatically. For custom scenarios when not using Ribbon Window, the location of the toolbar host can be defined by placing a RibbonQuickAccessToolBarHost control anywhere within the visual tree of the ribbon's ancestor TopLevel and setting the Ribbon.AllowExternalQuickAccessToolBarHost property to true.

Hiding the Customize Button

The RibbonQuickAccessToolBar.IsCustomizeButtonVisible property can be set to false to hide the customize button that appears next to the QAT.

Customizing the Customize Button's Menu

Ribbon supports dynamic customization of the Customize button's menu at run-time.

See the Menu Customization topic for a section with additional details on customizing the default menu.

Persisting End-User Run-Time Item Customizations

Ribbon includes a very flexible framework for supporting multiple forms of end-user customization. If end-user customization is allowed, users will expect those customizations to persist between application sessions.

See the Serialization topic for details on how to persist the state of the quick access toolbar to be restored later.

Key Tips

Key tips for controls in the quick access toolbar are auto-generated, beginning with numbers. In some cases, the numbers might conflict with a ribbon tab that also uses a key tip beginning with a number. In this scenario, the KeyTipTextPrefix property can be set to an unused character like 'Q', which will prefix the auto-generated key tip text, thereby removing the conflict.

See the Key Tips topic for additional details on key tips in general.