Recent Documents

A RecentDocumentControl is a control that is intended to be used within a backstage.

Screenshot

A RecentDocumentControl shown in a backstage

Recently opened documents are listed in a sorted order and can be clicked to open them. Hovering the mouse over a document provides its full path.

Clicking on a document's Pin button will toggle the pinned state of the document. When pinned, the document will not fall off the list if there are other unpinned documents that have been opened more recently.

Adding to a Backstage

The RecentDocumentControl can be added to a Backstage as content for a RibbonBackstageTabItem.

When a RecentDocumentControl is included in a RibbonBackstageTabItem, it is recommended to leave the RecentDocumentControl.UseLargeSize property at the default value of true. This will enable the control to take advantage of the additional space afforded on a backstage and render similar to Office with large icons and descriptions.

Managing the Recent Document List

The recent document list is managed by adding instances of RecentDocumentItem to the RecentDocumentControl.Items property or setting RecentDocumentControl.ItemsSource to an enumerable of RecentDocumentItem instances.

Caution

Only instances of RecentDocumentItem should be added to the Items or ItemsSource properties. Otherwise, exceptions can be thrown while attempting to process the items.

See the "Recent Documents" Bars Ribbon QuickStart of the Sample Browser application for an example of adapting a collection of view models to a collection of RecentDocumentItem.

The following key properties are available for RecentDocumentItem:

Property Name	Description
LargeIcon	An `object` that is displayed for the document when RecentDocumentControl.UseLargeSize is `true`.
SmallIcon	An `object` that is displayed for the document when RecentDocumentControl.UseLargeSize is `false`.
IsPinned	Indicates if the document is pinned to the top of the list.
LastOpenedDateTime	The date and time when the document was last opened. Documents are sorted so the most recently opened documents appear at the top.
Location	A `Uri` indicating the location of the document.

Processing Document Clicks

When the end user clicks on a document listed in the RecentDocumentControl, the RecentDocumentControl.OpenCommand will be executed with the corresponding RecentDocumentItem passed as the command parameter.

In the code that handles the execution of the command, use the command parameter (which is a RecentDocumentItem) to determine which document to open. Since the associated RecentDocumentControl.OpenCommand might be raised in scenarios unrelated to opening a recent document, it is generally safe to assume that if no command parameter is passed, the command was not raised by the RecentDocumentControl and the default action for the command (e.g., browse for a file with an Open File dialog) should be invoked.

Grouping

The RecentDocumentControl supports grouping documents based on RecentDocumentItem.LastOpenedDateTime . Set the AllowGrouping property to false to disable this functionality (defaults to true).

When grouping is allowed, all pinned documents will appear at the top. Unpinned documents will be grouped based on how recently they were last accessed. Each group label is defined by a localizable String resource value. The following groups are available:

Group	Resource key	Description
Pinned	`UIRecentDocumentGroupPinnedText`	Pinned documents.
Today	`UIRecentDocumentGroupTodayText`	Documents last accessed on the current day.
Yesterday	`UIRecentDocumentGroupYesterdayText`	Documents last accessed on the previous day.
Older	`UIRecentDocumentGroupOlderText`	Documents last accessed two or more days ago.
Future	`UIRecentDocumentGroupFutureText`	Documents last accessed at a date chronologically after the current date.

See the Customizing String Resources topic for additional details on working with string resources.

Customizing Column Text

When the RecentDocumentControl.UseLargeSize property is set to true, document data is displayed in columns. The text displayed for these columns can be customized by setting the DateTimeColumnText and/or NameColumnText properties to the desired value.

Each of these properties are initialized to a localizable String resource value. The following resources are configured:

Resource key	Description
`UIRecentDocumentControlDateTimeColumnText`	The text displayed for DateTimeColumnText. The default value is `"Last opened"`.
`UIRecentDocumentControlNameColumnText`	The text displayed for NameColumnText. The default value is `"Name"`.