Document Management
The ActiproSoftware.Windows.DocumentManagement namespace contains several classes that can be used for storing document references and maintaining recent document lists.
These classes are used by controls in our Bars (RecentDocumentControl) and Ribbon (RecentDocumentMenu) products to manage recent documents within an application menu.
Document References
The IDocumentReference interface provides the base requirements for a document reference. A document reference is simply a reference to a document that contains the Uri to the document, along with the document's display name, the DateTime that it was last opened, and whether it is a pinned recent document.
Some extended properties are also available for specifying icons (large/small) and a description of the reference. These properties may be used by products such as Bars's RecentDocumentControl when on a Backstage.
The DocumentReference class is a simple implementation of the IDocumentReference interface.
Recent Document Management
The RecentDocumentManager is a class that can manage a list of document references that point to recently-opened documents.
The manager class filters down the contained document references from its Documents collection into its FilteredDocuments collection.
The filtered collection will contain up to a maximum number of document references that you specify. That collection will also be sorted in descending date/time of the last time the document was opened, by examining the IDocumentReference.LastOpenedDateTime property. Further logic is applied so that if the document reference's IsPinnedRecentDocument property is true, it will have higher priority for staying on the list and not being filtered out, even if another more recently-opened document reference that wasn't pinned would normally have caused it to be filtered out.
The RecentDocumentManager class has these important members:
| Member | Description |
|---|---|
| Deserialize Method | Deserializes the Documents collection from the data in an XML string. The XML string must have been created by a previous call to Serialize. |
| Documents Property | Gets the collection of IDocumentReference objects that are being managed. Add/remove the document references to be managed via this collection. |
| FilteredDocuments Property | Gets the read-only collection of filtered documents that should be used for a recent documents list. The collection sorts the contained documents by date/time and pinned states and returns up to MaxFilteredDocumentCount documents. |
| GetDocumentReference Method | Returns an existing IDocumentReference from the Documents collection, if any, that matches the specified Uri. |
| MaxDocumentCount Property | Gets or sets the maximum number of documents to return in the Documents collection. This collection is how many documents total are being tracked. |
| MaxFilteredDocumentCount Property | Gets or sets the maximum number of documents to return in the FilteredDocuments collection. |
| NotifyDocumentOpened Method | Provides a helper method for easily updating an existing document reference's last-opened date/time. If no existing document reference with the specified Uri exists, a new DocumentReference is created. There are three overloads for this method, which each take incrementally more information for populating a new DocumentReference if needed. |
| RebindFilteredDocuments Method | Rebinds the FilteredDocuments collection. The FilteredDocuments collection is automatically re-bound when the Documents collection is changed. However, if you update the last-opened date/time or pinned flag for an IDocumentReference, you must call this method manually to rebind the FilteredDocuments collection. |
| Serialize Method | Serializes the Documents collection to an XML string. Use the Deserialize method to load the serialized data later. |
In many cases where a simple DocumentReference is used to track a document or if you don't wish to track the reference at all and just let the RecentDocumentManager do it completely for you, the use of the NotifyDocumentOpened method is recommended. That method provides a way to update the last-opened date time for a document in one line of code and will create a new reference as needed.
Persisting Recent Document Lists
The recent document list managed by a RecentDocumentManager can be easily persisted to an XML string. This XML string in turn can be saved to a settings file, database, or any other sort of storage mechanism you use for keeping user data.
Call RecentDocumentManager.Serialize to obtain the serialized data and later on, call RecentDocumentManager.Deserialize to restore the serialized data.