Details on Using Selected ATF Components

Table of Contents Components Requiring Imports Components that Import Interfaces StandardFileCommands Components with Methods that are Called CommandService Components to Derive From

This section discusses details of how to use specific ATF components, using examples to illustrate. For a general discussion, see Using ATF Components.

To use a component, the application usually needs to do one or more of the following:

• Import an interface required by component. You satisfy this by importing a component that implements the interface. In some cases, this is all you need to do to use the component. For details, see Components Requiring Imports. Usually an import is satisfied by importing a single component, but if the import attribute is [ImportMany], the application can import more than one component exporting the interface.
• Export an interface required by component. If there is no component that exports an interface that a component imports, the application needs to export and implement that interface itself. For a list of some of these components, see Components that Import Interfaces. For an example, see StandardFileCommands. Usually an import is satisfied by exporting a single component, but if the import attribute is [ImportMany] for the imported interface, the application can supply more than one component exporting the interface.
• Use methods that the component provides. For information on these, see Components with Methods that are Called. For an example, see CommandService.
• Derive from the component. Some components simply provide useful infrastructure, such as methods, and you need to derive from them. For a list of these, see Components to Derive From.

Note that because some components have multiple requirements, they may be on more than one of the lists here.

Components Requiring Imports

This table indicates what interfaces/components a component needs to import to function properly. Import components by including them in the MEF TypeCatalog. For information on how to import, see Creating a Catalog. Keep in mind that instead of using the component listed, you can create your own that exports the specified interface.

Several components import System.Windows.Forms.Form or System.Windows.Forms.MainForm (for a WinForm application) and Sce.Atf.Applications.IMainWindow. Generally speaking, these imports are satisfied by creating a MainForm.

For more details on determining what components import, see Functionality Required From Other Components.

Component	Interfaces/Components to import	Remarks
DefaultTabCommands	ICommandService/CommandService, IControlHostService/ControlHostService, IControlRegistry/ControlRegistry
PropertyEditingCommands	ICommandService/CommandService
RecentDocumentCommands	ICommandService/CommandService, IDocumentRegistry/DocumentRegistry, IDocumentService/StandardFileCommands, ISettingsService/SettingsService	This component also requires importing IDocumentClient. StandardFileCommands is one way to satisfy IDocumentService.
RenameCommand	ICommandService/ICommandService, , IContextRegistry/ContextRegistry, ISettingsService/SettingsService, IMainWindow, Form
SourceControlCommands	ICommandService/CommandService, IDocumentRegistry/DocumentRegistry, IDocumentService/StandardFileCommands, IContextRegistry/ContextRegistry, SourceControlService, IMainWindow, Form	This component also requires importing IDocumentClient. StandardFileCommands is one way to satisfy IDocumentService.
StandardEditCommands	ICommandService/CommandService, IContextRegistry/ContextRegistry
StandardEditHistoryCommands	ICommandService/CommandService, IContextRegistry/ContextRegistry
StandardFileCommands	ICommandService/CommandService, IDocumentRegistry/DocumentRegistry, IFileDialogService/FileDialogService, IStatusService/StatusService	This component also requires importing IDocumentClient. For more details, see StandardFileCommands.
StandardFileExitCommand	ICommandService/CommandService, IMainWindow, Form	For a discussion of why ICommandService is required, see Functionality Required From Other Components.
StandardLayoutCommands	ICommandService/CommandService, IContextRegistry/ContextRegistry
StandardLockCommands	ICommandService/CommandService, IContextRegistry/ContextRegistry
StandardPrintCommands	ICommandService/CommandService, IContextRegistry/ContextRegistry	StandardPrintCommands does not currently work with Direct2D.
StandardSelectionCommands	ICommandService/CommandService, IContextRegistry/ContextRegistry
StandardShowCommands	ICommandService/CommandService, IContextRegistry/ContextRegistry
StandardViewCommands	ICommandService/CommandService, IContextRegistry/ContextRegistry, ScriptingService
TargetCommands	ICommandService/CommandService, ITargetProvider/ Deci4pTargetProvider, TcpIpTargetProvider	Note that several components derive from TcpIpTargetProvider to export ITargetProvider: X86TargetProvider, Ps3TargetProvider, and Ps4TargetProvider.
WindowLayoutServiceCommands	IWindowLayoutService/WindowLayoutService, ICommandService/CommandService, MainForm

Components that Import Interfaces

These components import interfaces that are not exported by a standard ATF components, so the application must implement and export the interface. In some cases, the interface is decorated by the [ImportMany] attribute, so the application can supply multiple exports. These interfaces are marked with as asterisk in the table.

Component	Interface(s) Imported	Remarks
RecentDocumentCommands	IDocumentClient*	Several components import IDocumentClient, such as StandardFileCommands. For an example of importing this interface, see StandardFileCommands.
SourceControlCommands	IDocumentClient*	For an example of importing IDocumentClient, see StandardFileCommands.
StandardFileCommands	IDocumentClient*	For details, see StandardFileCommands.

StandardFileCommands

This component requires:

• CommandService, DocumentRegistry, FileDialogService, and StatusService components.
• Component that exports IDocumentClient.

For an explanation of these requirements, see Functionality Required From the Application.

The ATF Simple DOM Editor Sample uses StandardFileCommands. Examining this sample's Program.cs file shows that it also includes the ATF components in its MEF catalog to meet the other import requirements: CommandService, DocumentRegistry, FileDialogService, and StatusService (link to source).

This sample also provides an Editor component that exports and implements the IDocumentClient interface. Here is the Editor component class declaration (link to source):

[Export(typeof(IDocumentClient))]
[Export(typeof(Editor))]
[Export(typeof(IInitializable))]
[PartCreationPolicy(CreationPolicy.Shared)]
public class Editor : IDocumentClient, IControlHostClient, IInitializable

Here is Editor's implementation of IDocumentClient (link to source):

#region IDocumentClient Members

/// <summary>
/// Gets information about the document client, such as the file type and file
/// extensions it supports, whether or not it allows multiple documents to be open, etc.</summary>
public DocumentClientInfo Info
{
    get { return DocumentClientInfo; }
}
...
/// <summary>
/// Closes the document and removes any views of it from the UI</summary>
/// <param name="document">Document to close</param>
public void Close(IDocument document)
{
    EventSequenceContext context = Adapters.As<EventSequenceContext>(document);
    m_controlHostService.UnregisterControl(context.ListView);
    context.ControlInfo = null;

    // close all active EditingContexts in the document
    foreach (DomNode node in context.DomNode.Subtree)
        foreach (EditingContext editingContext in node.AsAll<EditingContext>())
            m_contextRegistry.RemoveContext(editingContext);

    // close the document
    m_documentRegistry.Remove(document);
}

#endregion

Components with Methods that are Called

Component	Remarks
CommandService	For more information, see CommandService.

CommandService

This component doesn't require any other components, but is required by some other components, such as StandardFileCommands and StandardFileExitCommand.

This component allows the user to add commands to an application that are triggered by menu items, buttons, and other controls by calling CommandService methods. This process is described generally in Registering Commands and in more detail in Registering Menus and Commands. For the full discussion of how commands are used in ATF, see Commands in ATF.

Components to Derive From

Some components supply useful methods, but users must override them in their own component that derives from the ATF component. For instance, many samples use HelpAboutCommand to display a Help dialog.

Component	Remarks
HelpAboutCommand	Many of the samples use this component. In ATF Simple DOM Editor Sample for instance, see its HelpAboutCommand.cs file.