Click here to Skip to main content
16,020,519 members
Articles / Desktop Programming / Windows Forms

Windows Ribbon for WinForms, Part 19 – RecentItems

Rate me:
Please Sign up or sign in to vote.
5.00/5 (12 votes)
23 Mar 2010Ms-PL2 min read 26.5K   1.1K   20   4
In this article, I'll present how to work with the ribbon recent items control.

This series of CodeProject articles is based on a series of posts I've first published on my blog.

Windows Ribbon for WinForms library now supports working with recent items in the application menu. The result of this post is a yet another sample, "16-RecentItems", found on the project site.

image

What are recent items?

Recent items are items in a list which appears in the application menu. They doesn't have to be file names, and they doesn't have to be recent, although it is recommended.

Every item has three properties:

  • Label - Item name, usually file name without path.
  • Label Description - Item tooltip, usually full filename path.
  • Pinned - Boolean that indicates whether the recent item should not be removed from the list.

More details can be found at Recent Items on MSDN.

Using RecentItems - Ribbon Markup

Commands section:

XML
<Application.Commands>
  ...
  <Command Name="cmdRecentItems" Id="1005" 
                LabelTitle="Recent Items" />
</Application.Commands>

Views section:

XML
<Application.Views>
  <Ribbon>
    <Ribbon.ApplicationMenu>
      <ApplicationMenu CommandName="cmdApplicationMenu">
        <ApplicationMenu.RecentItems>
          <RecentItems CommandName="cmdRecentItems" EnablePinning="true" MaxCount="7" />
        </ApplicationMenu.RecentItems>
        ...
      </ApplicationMenu>
    </Ribbon.ApplicationMenu>
  </Ribbon>
</Application.Views>

Things to note:

  • The "Recent Items" label can be changed to whatever you need (e.g., "Days of the week").
  • Setting the EnablePinning attribute to false will hide the pins from the application menu.
  • The MaxCount attribute specifies how many items to display on the application menu.

Using RecentItems - Code-Behind

Initialization:

C#
private Ribbon _ribbon;
private RibbonRecentItems _ribbonRecentItems;

List<RecentItemsPropertySet> _recentItems;

public Form1()
{
    InitializeComponent();

    _ribbon = new Ribbon();
    _ribbonRecentItems = new RibbonRecentItems(_ribbon, 
                            (uint)RibbonMarkupCommands.cmdRecentItems);

    _ribbonRecentItems.OnExecute += 
           new OnExecuteEventHandler(_recentItems_OnExecute);
}

private void Form1_Load(object sender, EventArgs e)
{
    _ribbon.InitFramework(this);

    InitRecentItems();
}

private void InitRecentItems()
{
    // prepare list of recent items
    _recentItems = new List<recentitemspropertyset />();
    _recentItems.Add(new RecentItemsPropertySet()
                     {
                         Label = "Recent item 1",
                         LabelDescription = "Recent item 1 description",
                         Pinned = true
                     });
    _recentItems.Add(new RecentItemsPropertySet()
                     {
                         Label = "Recent item 2",
                         LabelDescription = "Recent item 2 description",
                         Pinned = false
                     });

    _ribbonRecentItems.RecentItems = _recentItems;
}

RibbonRecentItems is the helper class for working with the recent items feature. It has a property named RecentItems of type IList<RecentItemsPropertySet>. This property contains the list of the recent items. Note that it is the user's responsibility for providing this list and update it when needed (add / remove items, change pinned state).

Responding to a click on an item:

C#
void _recentItems_OnExecute(PropertyKeyRef key, PropVariantRef currentValue, 
                  IUISimplePropertySet commandExecutionProperties)
{
    if (key.PropertyKey == RibbonProperties.RecentItems)
    {
        // go over recent items
        object[] objectArray = (object[])currentValue.PropVariant.Value;
        for (int i = 0; i < objectArray.Length; ++i)
        {
            IUISimplePropertySet propertySet = objectArray[i] as IUISimplePropertySet;

            if (propertySet != null)
            {
                PropVariant propLabel;
                propertySet.GetValue(ref RibbonProperties.Label, 
                                     out propLabel);
                string label = (string)propLabel.Value;

                PropVariant propLabelDescription;
                propertySet.GetValue(ref RibbonProperties.LabelDescription, 
                                     out propLabelDescription);
                string labelDescription = (string)propLabelDescription.Value;

                PropVariant propPinned;
                propertySet.GetValue(ref RibbonProperties.Pinned, 
                                     out propPinned);
                bool pinned = (bool)propPinned.Value;

                // update pinned value
                _recentItems[i].Pinned = pinned;
            }
        }
    }
    else if (key.PropertyKey == RibbonProperties.SelectedItem)
    {
        // get selected item index
        uint selectedItem = (uint)currentValue.PropVariant.Value;

        // get selected item label
        PropVariant propLabel;
        commandExecutionProperties.GetValue(ref RibbonProperties.Label, 
                                            out propLabel);
        string label = (string)propLabel.Value;

        // get selected item label description
        PropVariant propLabelDescription;
        commandExecutionProperties.GetValue(ref RibbonProperties.LabelDescription, 
                                            out propLabelDescription);
        string labelDescription = (string)propLabelDescription.Value;

        // get selected item pinned value
        PropVariant propPinned;
        commandExecutionProperties.GetValue(ref RibbonProperties.Pinned, 
                                            out propPinned);
        bool pinned = (bool)propPinned.Value;
    }
}

I know, some explanations are in order. The OnExecute event is called on two occasions:

  1. When the user clicks on one of the items.
  2. When the user changes the pinned status of several items and then closes the menu (either by selecting one of the items or by clicking outside the menu).

When the user clicks on an item, the currentValue argument contains the index of the selected item and the commandExecutionProperties argument contains the properties of the selected item. The above code shows how to extract them.

When the user changes the pinned status of several items, the currentValue argument contains the new status of the items. It is the user's responsibility to update the items in their own list. Otherwise, the user's change won't appear the next time he opens the menu.

That's it for now.

License

This article, along with any associated source code and files, is licensed under The Microsoft Public License (Ms-PL)


Written By
Software Developer (Senior) Verint
Israel Israel
Arik Poznanski is a senior software developer at Verint. He completed two B.Sc. degrees in Mathematics & Computer Science, summa cum laude, from the Technion in Israel.

Arik has extensive knowledge and experience in many Microsoft technologies, including .NET with C#, WPF, Silverlight, WinForms, Interop, COM/ATL programming, C++ Win32 programming and reverse engineering (assembly, IL).

Comments and Discussions

 
GeneralMerging Pin
Patrick Blackman23-Mar-10 2:27
professionalPatrick Blackman23-Mar-10 2:27 
GeneralRe: Merging Pin
Arik Poznanski23-Mar-10 2:33
Arik Poznanski23-Mar-10 2:33 
Can you elaborate what do you mean by toolbar/menu merging?
Arik Poznanski

GeneralRe: Merging Pin
Patrick Blackman23-Mar-10 12:07
professionalPatrick Blackman23-Mar-10 12:07 
GeneralRe: Merging Pin
Arik Poznanski23-Mar-10 22:28
Arik Poznanski23-Mar-10 22:28 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.