QuickAccessToolbar

QuickAccessToolbar

Windows Ribbon for WinForms library now supports working with the ribbon quick access toolbar. The result of this post is a yet another sample, “17-QuickAccessToolbar”, found on the project site.

What is Quick Access Toolbar (QAT)? Quick access toolbar resides on the left of the window title. The user can save their common ribbon commands he wants to easily access. A user can add a Ribbon Button (or ToggleButton or CheckBox) to the QAT by right clicking it and select “Add to Quick Access Toolbar”.

Since Windows 8 the user can also add a ComboBox, DropDownGallery, SplitButtonGallery and InRibbonGallery to the QAT. Best practice for the new controls since Windows 8 is, that they are unchecked in the markup file. They can set to check state by user or code after these new controls are populated with items or commands in the code behind.

The application developer can specify a set of “default buttons” (In the above image: new, open and save). This is done using ribbon markup. Also, the application developer can add commands dynamically using code.

One more feature of the ribbon is the ability to save and load the list of commands. Using this feature to save and load the settings between application sessions provides the user with a consistent UI experience.

More details can be found at Quick Access Toolbar on MSDN.

Using QuickAccessToolbar – Ribbon Markup Following is an example of a views section that uses QuickAccessToolbar:

<Application.Views>
  <Ribbon>
    <Ribbon.QuickAccessToolbar>
      <QuickAccessToolbar CommandName=‘cmdQAT‘ CustomizeCommandName=‘cmdCustomizeQAT‘>
        <QuickAccessToolbar.ApplicationDefaults>
          <Button CommandName=“cmdButtonNew“ ApplicationDefaults.IsChecked=“true“ />
          <Button CommandName=“cmdButtonOpen“ ApplicationDefaults.IsChecked=“false“ />
          <Button CommandName=“cmdButtonSave“ ApplicationDefaults.IsChecked=“false“ />
        </QuickAccessToolbar.ApplicationDefaults>
      </QuickAccessToolbar>
    </Ribbon.QuickAccessToolbar>
    <Ribbon.Tabs>
      <Tab CommandName=“cmdTabMain“>
        <Group CommandName=“cmdGroupFileActions“ SizeDefinition=“ThreeButtons“>
          <Button CommandName=“cmdButtonNew“ />
          <Button CommandName=“cmdButtonOpen“ />
          <Button CommandName=“cmdButtonSave“ />
        </Group>
      </Tab>
    </Ribbon.Tabs>
  </Ribbon>
</Application.Views>

As you can see, the QuickAccessToolbar element defines two command names. The first, identified by the attribute “CommandName”, is the command for the actual quick access toolbar. The second, identified by the attribute “CustomizeCommandName” is the command for the button “More Commands…” which you can see in the image above on the menu. The “More Commands…” button is optional, but if specified, can be used to open an application defined dialog for selecting more commands into the QAT.

Another thing you can see in the markup is the use of QuickAccessToolbar.ApplicationDefaults element which let the developer specify which items will be in the QAT popup menu. Every item can be marked with IsChecked attribute, in which case the item will appear on the QAT.

Using QuickAccessToolbar – Code Behind Initialization:

private Ribbon _ribbon;
private RibbonQuickAccessToolbar _ribbonQuickAccessToolbar;

public Form1()
{
    InitializeComponent();

    _ribbon = new Ribbon();
    _ribbonQuickAccessToolbar = new RibbonQuickAccessToolbar(_ribbon,
                                        (uint)RibbonMarkupCommands.cmdQAT,
                                        (uint)RibbonMarkupCommands.cmdCustomizeQAT);

    // register to the QAT customize button
    _ribbonQuickAccessToolbar.ExecuteEvent += 
                    new new EventHandler<ExecuteEventArgs>(_ribbonQuickAccessToolbar_ExecuteEvent);
}

Note that the customize QAT button is optional so if you didn’t declare it you should use the other constructor of RibbonQuickAccessToolbar class.

Handling the customize QAT button (“More Commands…”):

void _ribbonQuickAccessToolbar_ExecuteEvent(object sender, ExecuteEventArgs e)
{
    MessageBox.Show(“Open customize commands dialog..”);
}

The application developer should probably load a dialog that allows the user to select commands and then set them by manipulating the commands list.

Manipulating commands list:

void _buttonNew_ExecuteEvent(object sender, ExecuteEventArgs e)
{
    // changing QAT commands list 
    UICollection<QatCommandPropertySet> itemsSource = _ribbonQuickAccessToolbar.QatItemsSource;
    itemsSource.Clear();
    itemsSource.Add(new QatCommandPropertySet() 
                    { CommandID = (uint)RibbonMarkupCommands.cmdButtonNew });
    itemsSource.Add(new QatCommandPropertySet() 
                    { CommandID = (uint)RibbonMarkupCommands.cmdButtonOpen });
    itemsSource.Add(new QatCommandPropertySet() 
                    { CommandID = (uint)RibbonMarkupCommands.cmdButtonSave });
}

Older version:

void _buttonNew_ExecuteEvent(object sender, ExecuteEventArgs e)
{
    // changing QAT commands list 
    IUICollection itemsSource = _ribbonQuickAccessToolbar.ItemsSource;
    itemsSource.Clear();
    itemsSource.Add(new GalleryCommandPropertySet() 
                    { CommandID = (uint)RibbonMarkupCommands.cmdButtonNew });
    itemsSource.Add(new GalleryCommandPropertySet() 
                    { CommandID = (uint)RibbonMarkupCommands.cmdButtonOpen });
    itemsSource.Add(new GalleryCommandPropertySet() 
                    { CommandID = (uint)RibbonMarkupCommands.cmdButtonSave });
}

This code is very similar to the code for manipulating the command list of a gallery.

Read QAT commands list: The commands id’s are in the list _checkedCommands.

!Note:
Only checked commands are in QAT.QatItemsSource or QAT.ItemsSource

      UICollection<QatCommandPropertySet> qatitemsSource = QAT.QatItemsSource;
      List<uint> _checkedCommands = new List<uint>();
      foreach (QatCommandPropertySet propSet in qatitemsSource)
      {
           uint id = propSet.CommandID;
           _checkedCommands.Add(id);
      }

Older version:

      IUICollection qatitemsSource = QAT.ItemsSource;
      List<uint> _checkedCommands = new List<uint>();
      uint count;
      object item;
      qatitemsSource.GetCount(out count);
      for (uint i = 0; i < count; i++)
      {
           qatitemsSource.GetItem(i, out item);
           IUISimplePropertySet simple = item as IUISimplePropertySet;
           PropVariant variant;
           simple.GetValue(ref RibbonProperties.CommandID, out variant);
           uint id = (uint)variant.Value;
           _checkedCommands.Add(id);
      }

Add a checked command to the QAT:

       UICollection<QatCommandPropertySet> qatitemsSource = QAT.QatItemsSource;
       qatitemsSource.Add(new QatCommandPropertySet()
           { CommandID = Cmd.cmdSensorsInRibbon });

Older version:

       IUICollection qatitemsSource = QAT.ItemsSource;
       qatitemsSource.Add(new GalleryCommandPropertySet()
           { CommandID = Cmd.cmdSensorsInRibbon });

Saving and loading ribbon settings:

private Stream _stream;

void _buttonSave_ExecuteEvent(object sender, ExecuteEventArgs e)
{
    // save ribbon QAT settings 
    _stream = new MemoryStream();
    _ribbon.SaveSettingsToStream(_stream);
}

void _buttonOpen_ExecuteEvent(object sender, ExecuteEventArgs e)
{
    // load ribbon QAT settings 
    _stream.Position = 0;
    _ribbon.LoadSettingsFromStream(_stream);
}

You can save the settings in any .NET stream object, usually it should be saved into a file or the registry.

The settings which are saved are: QAT commands list, ribbon QuickAccessToolbarDock property and ribbon Minimized property.