Document Registry and Services - kaisu1986/ATF GitHub Wiki

Table of Contents IDocumentRegistry Interface and DocumentRegistry Component IDocumentService Interface Topics in this section

ATF provides services for documents and also has a registry to keep track of documents.

The purpose of the document registry is to keep track of all the documents an application has open. A document in this context is any object implementing IDocument.

The IDocumentRegistry provides the following properties:

• ActiveDocument: get or set the active IDocument object.
• Documents: get an enumeration of all active IDocument objects.

A document is typically some kind of object, so the following methods are useful:

• GetActiveDocument<T>(): get the active document as a type T, if possible.
• GetMostRecentDocument<T>(): get the most recently active document of type T, which may not be the same as the currently active document.
• GetDocument(): get the document specified by a given URI.

Finally, these events track active document changes:

• ActiveDocumentChanging: active document is about to change.
• ActiveDocumentChanged: active document has changed.
• DocumentAdded: a document was added to the document registry's collection.
• DocumentRemoved: a document was removed from the document registry's collection.

The DocumentRegistry component implements IDocumentRegistry to track open documents. All you need to do to use this component is to add it to your application's MEF catalog. Nearly all the ATF samples use DocumentRegistry.

The IDocumentService interface provides a way to handle the UI for document handling: opening, saving, and closing documents. Its methods, which do exactly what they say, include:

• OpenNewDocument()
• OpenExistingDocument()
• Save()
• SaveAs()
• SaveAll()
• Close()
• CloseAll()

IDocumentService also contains the accompanying events for documents being saved, closed, and opened.

The IDocumentClient interface also provides Save() and Close() methods. What's the difference between these and the IDocumentService methods of the same name?

A document service provider implementing IDocumentService, such as StandardFileCommands, can deal with or provide the user interface, such as a menu item to close a document, and directly interacts with a user. When asked to close a document, the IDocumentService figures out which document is involved and calls the Close() method in the appropriate document client implementing IDocumentClient. The document client then does everything needed to actually close the document.

The StandardFileCommands component implements the IDocumentService interface. For details, see DocumentRegistry Component.