Windows Ribbon for WinForms, Part 20 – QuickAccessToolbar

3 בדצמבר 2009

5 תגובות

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.


image


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


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.OnExecute +=
                    new OnExecuteEventHandler(_ribbonQuickAccessToolbar_OnExecute);
}

 


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_OnExecute(PropertyKeyRef key, PropVariantRef currentValue, IUISimplePropertySet commandExecutionProperties)
{
    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_OnExecute(PropertyKeyRef key, PropVariantRef currentValue, IUISimplePropertySet commandExecutionProperties)
{
    // 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.


Saving and loading ribbon settings:




private Stream _stream;

void _buttonSave_OnExecute(PropertyKeyRef key, PropVariantRef currentValue,
                           IUISimplePropertySet commandExecutionProperties)
{
    // save ribbon QAT settings
    _stream = new MemoryStream();
    _ribbon.SaveSettingsToStream(_stream);
}

void _buttonOpen_OnExecute(PropertyKeyRef key, PropVariantRef currentValue,
                           IUISimplePropertySet commandExecutionProperties)
{
    // 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.


That’s it for now,
Arik Poznanski.

kick it on DotNetKicks.com Shout it

הוסף תגובה
facebook linkedin twitter email

כתיבת תגובה

האימייל לא יוצג באתר. (*) שדות חובה מסומנים

5 תגובות

  1. Jody13 במאי 2010 ב 7:03

    Would there by chance be any means to dynamically add buttons to an existing group within an existing tab? My users may create filters and I'd like to generate buttons for as many filters as they might create.

    להגיב
  2. arik13 במאי 2010 ב 18:13

    Unfortunately no.
    The Windows Ribbon Framework doesn't support dynamic buttons in its tabs.
    The only dynamic features would be:
    - Galleries, provides a way to supply items dynamically, specifically, In-Ribbon gallery might be helpful.
    - Application Modes
    - Contextual Tabs
    Note: Both application modes and contextual tabs show changing UI, but the UI was predefined in compile time.

    להגיב
  3. Anonymous4 בנובמבר 2010 ב 17:13

    This might be a stupid question, but what is the CommandName command for? The command defined by CustomizeCommandName is indeed executed when I click the 'More commands…' button, but when is the CommandName command supposed to be executed? I've clicked anywhere and everywhere on my ribbon, but this command is never getting executed.

    Thanks alot.

    להגיב
  4. arik4 בנובמבר 2010 ב 21:17

    Every ribbon control is bounded to a command (hence needs the CommandName attribute). The command holds resources for the control, for example tooltip text.

    להגיב
  5. Anonymous26 בנובמבר 2010 ב 21:11

    It is great to see that the QAT can be modified manually as you state in this article; however would it be possible to retrieve them too? I'm trying to make an actual Customize dialog, so I need the current items as well.

    I tried:

    Dim itemssource = RibbonQAT.ItemsSource
    Dim item As Object
    itemssource.GetItem(0, item)

    But 'item' is of type 'System.__ComObject' and it seems impossible to convert it to 'GalleryCommandPropertySet' or something else at all. Could you give me a direction as to how to get this work?

    Thanks.

    להגיב