The code below corresponds to this article, however more up to date code may be available at a WPF C# Ribbon Control Library. Current code version herein is version 1.0.0.9.
Introduction
This article introduces the Quick Access Toolbar (QAT, pronounced c-a-t) as part of the larger project, a WPF C# Ribbon Control Library. The QAT is a required component as stipulated by the Microsoft Office User Interface (UI) Guidelines. The QAT provides document wide commands always at a single click, regardless of the current ribbon or otherwise.
IMPORTANT INFORMATION: To use this code you must agree to the licensing agreement and guidelines as set out by Microsoft. Part of these guidelines includes the requirement that you MUST have other components which are currently NOT part of this library; I in no way imply or otherwise that this library is sufficient for qualification for the Microsoft Office UI license. Ensuring you have these other components is YOUR responsibility. By downloading the source code or by using the source code you have agreed to follow download and follow the Microsoft required guidelines.
Background
"The Quick Access toolbar, which sits in the title bar, serves as a repository of most used functions, regardless of which application is being used, such as save, undo/redo and print. The Quick Access toolbar is fully customizable similar to toolbars in previous Office versions. Any command available in the entire Office application can be added to the Quick Access toolbar, including commands not available in the Ribbon and macros. Keyboard shortcuts for any of the commands on the toolbar are also fully customizable, similar to previous Office versions." --- Wikipedia, Microsoft Office 2007.
Using the Code
Using the control is relativily straight forward, and does not necesserily require the use of the RibbonController as included in the library dll (all though it is recommended). Please note however that an application using this QAT must contain all the required UI elements as set out in the Microsoft guidelines, therefore it is not allowable to use this component on its own.
The control has two main parts; a button panel and a drop down menu. The button panel contains all the quick access buttons added to the control, and resizes to fit accordingly (including the border and background). Each button in the control is styled automatically by RibbonStyleHandler and behaves exactly how the equivalent ribbon button does, including when a user clicks the button the button click is translated to the appropriate ribbon control. The translated QAT button clicks therefore only need to be handled once, i.e. by the original RibbonController / RibbonBar code. The drop down menu displays a menu of common controls which can be added to the QAT and provides access to the customization dialog (see below).
Setting Default QAT Items
Applies to implementations using RibbonController included in the library.
The RibbonControlBase class is inherited from by all RibbonBar and children controls. RibbonControlBase implements a property IsDefaultQuickAccessButton, which when set to true adds the automatically generated button to the QAT when .resetToDefault(RibbonController controller) is called upon the valid QAT object. Note however that the control with the IsDefaultQuickAccessButton property must be added as a child (indirectly or directly) of the RibbonController prior to calling .resetToDefault(RibbonController controller) or the control will not be added until the user resets the QAT via the customization dialog.
Setting Default QAT Drop-down Menu Items
Applies to implementations using RibbonController included in the library.
Similarly to IsDefaultQuickAccessButton, the IsDefaultQuickAccessMenuButton menu property may be used to set the default items in the drop down menu; note that clicking these items does not fire the clicked event, but rather add them to the QAT button panel.
Adding Items at Runtime to the QAT
This is typically performed by the user by right-clicking and selecting 'Add to Quick Access Menu' on any Ribbon component. While mostly automatic, the RibbonController and QuickAccessToolbar must be linked via the AddToQuickAccessToolbarEvent of RibbonController. The following lines of code must be placed in the resulting event handler;
RibbonControlBase rcb = (RibbonControlBase)sender;
quickAccessToolbar.Buttons.Add(rcb.getQAButton());
Note however that the user may also add buttons to the QAT via the customization dialog, however no code is required to support this. It is necessery to capture the CustomiseQuickAccessToolbarEvent event of both RibbonController and QuickAccessToolbar and open the dialog in the resulting event handler.
QuickAccessToolBarConfigurationWindow w =
new QuickAccessToolBarConfigurationWindow(quickAccessToolbar, ribbonController);
w.HelpIconSource = new BitmapImage(new Uri(Environment.CurrentDirectory
+ @"\\Standard Icons\help_icon.png", UriKind.RelativeOrAbsolute));
w.ConfigIconSource = new BitmapImage(new Uri(Environment.CurrentDirectory
+ @"\\Standard Icons\config.png", UriKind.RelativeOrAbsolute));
w.ShowDialog();
QAT Customization Dialog
For increased ease of use (both end-user and developer) a default customize QAT dialog is provided, which allows simple customisation of the QAT via a list of all commands per RibbonBar or per RibbonController. Controls for adding and removing from the QAT are provided as well as commands for re-ordering the QAT's members. The control currently does not support document specific QAT configurations, however that will be included in a later release. Neither does the control currently maintain state from one application run to the next.
Points of Interest
RibbonControlBase includes several useful methods for dealing with QAT buttons; in particular getQAButton() and getQAButtons(). getQAButton() returns a QuickAccessButton that is linked to the control; i.e. when the image on the control is updated, that of the button is correspondingly, as with Text, SubMenu, and click events. getQAButtons() returns a list of all valid QuickAccessButtons for the called upon RibbonControlBase object and its children (recursively); including children with unusual children topologies (e.g. RibbonThreeRowsLayout.
Known Bugs
The following is a list of bugs I am currently aware of; please leave a comment if you see any others;
- Customization list inccorectly populating contents of
RibbonGroupBoxes when the box is minimized.
Future Work
The following tasks are still being undertaken or being started
- Fix drop down menu
- Restyling
- State maintenance, including per document state
History
Version 1.0.0.3 - Initial build of Quick Access Toolbar.*
Required by Microsoft Office UI Guidelines.
Additional Licensing Notes
Please feel free to use this in your work, however please be aware that a modified The Code Project Open License (CPOL) is in use; basically it is the same as the standard license except that this code must not be used for commercial or not-for-profit commercial use without prior authorisation. Please see license.txt or license.pdf in the included source and demo files.
