Core ATF Frameworks

These frameworks are the building blocks for ATF applications. They provide their capabilities by defining interfaces—and classes and components that implement them. This section tells you the key interfaces and classes in each framework. Many of these classes are Managed Extensibility Framework (MEF) components.

You can modify or replace these classes to suit your own purposes, but you may want to keep classes general enough so that you can use them in more than one application.

Nearly all the classes mentioned here are in the Sce.Atf.Applications namespace. For a description of the main ATF namespaces, see ATF Namespaces. You can also find a survey of representative and useful ATF classes, grouped by namespace, at Class Survey.

Each section here cites corresponding sections in the ATF Programmer's Guide where you can go to learn more about the topic.

Table of Contents Application Shell Framework Document Framework Commands Framework Managed Extensibility Framework Adaptation Framework Instancing Framework Context Framework Property Editing Framework Document Object Model Framework

Application Shell Framework

The Application Shell Framework consists of the core application services and interfaces needed for applications with a GUI:

• ControlHostService: Provide a dock in which to hold controls, such as menus and toolbars. This component's interface is IControlHostService. The docking control allows moving windows around on the dock, and the current window configuration can be saved. For details, see ControlHostService Component.
• CommandService: Display currently available application commands to the user in menus and toolbars and provide keyboard shortcuts. Its interface is ICommandService. See CommandService Component for more information.
• StatusService: Add a status bar at the bottom of the main form. This component implements the IStatusService interface. For more details, see StatusService Component.
• SettingsService: Manage user-editable settings (preferences) and the persistence of these application settings. Its interface is ISettingsService. To learn more, see SettingsService Component.

These services are all components, so you don't need to configure them. Using these components saves you the trouble of developing these common capabilities yourself.

You can add other ATF components to the application to implement single-instance applications (SingleInstanceService), unhandled exception recovery (UnhandledExceptionService), user feedback (UserFeedbackService), and automatic version update (VersionUpdateService). All these components are independent and can be omitted or replaced.

For customization, you can add a System.Windows.Forms.ToolStripContainer to present command toolbars to the user.

The Application Shell framework can also be used with Windows Presentation Foundation (WPF) applications. There are versions of these components and interfaces for both WinForms and WPF. SettingsService does not interact with a GUI, so it can be used with both WinForms and WPF.

For more details on the Application Shell framework, see ATF Application Basics and Services.

Document Framework

A document is a file that an application opens and a user can edit in some fashion. A document's contents could vary from unformatted text to graphics in a scene created by a level editor.

The Document Framework enables components in an application to track documents that a user is working on and track which document is active. It includes interfaces and components for working with application documents.

First, the interfaces:

• IDocument: The interface for application documents, which provides read-only and dirty properties. This is in the Sce.Atf namespace. For more information, see IDocument Interface.
• IDocumentService: Provide standard document services, such as Open, Close, Save, and Save As, and to determine whether or not a document has a title. Notifications allow components to track what the user is doing with the document. Any application managing documents uses IDocumentService. For details, see IDocumentService Interface.
• IDocumentRegistry: The interface to the document registry. The document registry holds open documents, provides notifications when a document is added or removed, tracks the most recently active document and the open document contexts, and filters by document type. To learn more, see IDocumentRegistry Interface and DocumentRegistry Component.
• IDocumentClient: Open, close, and display open documents. Applications should implement a document client for each document type that they can read or write, because this client works with the actual document data. For details, see IDocumentClient Interface.

Here are the Document Framework components (services):

• StandardFileCommands: Implement File menu commands that modify the document registry: New, Open, Save, SaveAs, Save All, and Close. New and Open commands are created for each IDocumentClient object in the application. For more information, see StandardFileCommands Component.
• AutoDocumentService: Open documents from the previous application session or create a new empty document when an application starts. To learn more, see AutoDocumentService Component.
• RecentDocumentCommands: Add recently opened documents to the application's File > Recent Documents submenu.
• DocumentRegistry: Track the open documents in an application. It can retrieve the active document or most recently active document of a given type. For more information, see Document Registry and Services and DocumentRegistry Component.
• MainWindowTitleService: Update the main dialog's title to reflect the current document and its state, i.e., modified or not. For more information, see MainWindowTitleService Component.

For a further discussion of documents, see Documents in ATF.

You can use the ATF Document Object Model (DOM) to store document data. For more information, see Document Object Model Framework.

Commands Framework

An application usually needs to add custom commands for its menus, buttons, and other controls. That's the purpose of the Commands Framework.

The CommandService component (or a custom component like it) is a service to handle commands in menus and toolbars. CommandService implements the ICommandService interface, which contains methods to register and unregister commands, display context menus, and process keyboard shortcuts. For more information on what CommandService does, see Registering Menus and Commands.

The CommandInfo class provides information about a command, such as user interface name and keyboard shortcut. This class also sets up information for common commands, such as the standard File and Edit menu item commands. For more details, see CommandInfo Class.

ICommandClient is the interface you implement so that CommandService calls your command code back when the user clicks on your command's menu item, tool button, or icon in a tool strip. ICommandClient also determines whether a command can be performed. To learn more, see Creating Command Clients.

Several ATF components add sets of commands to an application:

• StandardFileCommands: Add standard File menu commands: Save, Save As, Save All, and Close. For more information, see StandardFileCommands Component.
• StandardSelectionCommands: Add standard selection commands: Select All, Deselect All, and Invert Selection.
• StandardShowCommands: Add standard Show menu item commands: Show Selected, Hide Selected, Show Last Hidden, Show All, and Isolate.
• PropertyEditingCommands: Provide property editing commands that can be used in property editor controls, such as a property grid. For more on property editing, see Property Editing Framework.

To get more information on these command components and others that add commands, see Using Standard Command Components.

These components' code also demonstrates how to add commands to an application.

For a full discussion on using commands, see Commands in ATF.

Managed Extensibility Framework

ATF uses Microsoft's Managed Extensibility Framework to create components that you can easily add to your applications. To learn more, see MEF with ATF. For a list of useful components, see Important ATF Components.

Adaptation Framework

The Adaptation Framework converts objects to other types. Adaptation is the process of allowing an object of one type to behave like another type. This means the object can use the API of another type: its methods, properties, and events—with its own data. You can think of adaptation as dynamic casting.

An adapter for an object A to type T is an object that has all the behavior and data of A and also behaves like an object of type T. In this case, A is the adaptee of the adapter. An object can be its own adapter.

Adapters implement the IAdapter interface. Adaptees implement the IAdaptable interface, which obtains an adapter for a given type. For more information on these and other adaptation interfaces, see General Adaptation Interfaces.

The D2dAdaptableControl class represents a base control with control adapters. An adapted control can simulate other controls, such as a circuit control, by adding control adapters. D2dAdaptableControl has the following advantages:

• These controls can be decorated with control adapters to add new behavior. You can add functionality from outside the control without using inheritance. You can implement all the new functionality, such as label editing, in the adapter.
• To add a new feature, just add an adapter—you don't have to derive from a standard control class. This allows you to easily augment standard controls such as CanvasControl, GraphControl, CircuitControl, StatechartControl, TimelineControl, CurveControl, TreeControl, and PropertyGrid.

For more information about adaptable controls and control adapters, see Control Adapters.

The Adaptation Framework's interfaces and controls are in the Sce.Atf.Adaptation and Sce.Atf.Controls.Adaptable namespaces.

For general information on adaptation, see Adaptation in ATF.

Instancing Framework

The Instancing Framework works with object instances that can be edited, i.e., copied, inserted, or deleted. It enables inserting objects, such as pasting from a clipboard, or dropping a circuit element onto a canvas. The Instancing Framework allows making copies or clones of objects and deleting instances.

The Instancing Framework's key interface is IInstancingContext. It provides the CanCopy() and Copy(), CanInsert() and Insert(), CanDelete() and Delete() methods. IInstancingContext uses the System.Windows.Forms.IDataObject interface, allowing integration with the Windows clipboard, so that data can be both exported from and imported into ATF applications from other applications. A context should implement this interface if it allows editing objects. For more information, see IInstancingContext and IHierarchicalInsertionContext Interfaces.

Several parts of ATF use the Instancing Framework:

• StandardEditCommands uses IInstancingContext to implement copy, cut, paste, or delete operations. For more details, see StandardEditCommands and Instancing.
• Drag and drop operations use the Instancing Framework to insert objects into a context. Drag and drop operations also use the IDataObject interface.
• Miscellaneous commands, such as grouping commands, use the Instancing Framework to delete all the objects in a group or insert objects into a group.

The Instancing Framework's component StandardEditCommands also references the Context Framework to access context information, such as the active context. StandardEditCommands determines whether the active context implements the IInstancingContext interface. StandardEditCommands provides the Edit menu commands Cut, Copy, Paste, and Delete, using the IInstancingContext and (if available) ITransactionContext interfaces to perform the operations. Using ITransactionContext allows commands to be performed as transactions so they can be undone and redone.

To learn more about using instancing, see Instancing In ATF.

Context Framework

The Context Framework tracks and works with application contexts.

A context is the environment or interrelated conditions in which something exists or occurs. A context has a "logical view" of some kind of application data that is presented to a user for viewing or editing. ATF has a variety of contexts, supporting various capabilities. A context can be very general, working with different kinds of data. For more on contexts, see What is a Context.

Application components need context information to track what the user is doing, so that they perform the correct operation on the correct object. Application components can use the Context Framework to track documents currently in the system, check whether a path has changed, update a tab (from inactive to active, for example), undo the last command, keep track of the currently selected objects, and so on.

A context registry tracks the active contexts in the application. ATF's ContextRegistry component implements the IContextRegistry interface to access the context registry. IContextRegistry tracks active and open contexts, so you can obtain the active context or the most recently active context. IContextRegistry also has events to track context changes. IContextRegistry makes it easy for applications to track what the user is working on and what is currently active. For example, a command can use IContextRegistry to check whether or not a command is doable. For more information, see Context Registry.

Each context type has an associated interface indicating what it can do. Context interfaces are designed to perform common application tasks, such as getting the current selection or determining when data has changed. They are designed to be easy to implement and are specific to a particular task.

The main context interfaces are:

• IHistoryContext: Track what has changed since the document was last saved to enable implementing "Undo"/"Redo" commands.
• IInstancingContext: For contexts that can instance objects, that is, copy, insert, and delete items. For information on instancing, see Instancing Framework.
• ILayoutContext: For contexts that support positioning and sizing items. It contains methods for getting and setting item bounding rectangles and for determining which item bounds can be set.
• ILockingContext: Determine whether an object is locked, so the object cannot be changed or deleted.
• IObservableContext: Allow observers of list and tree data to track changes, so they can implement an editable view that stays in sync with data.
• IPropertyEditingContext: Allow property editing components to get properties and items with properties, enabling property editing controls to display objects and their properties. For more information, see Property Editing Framework.
• ISelectionContext: Distill what it means to have a selection in a context. It provides methods for getting the objects in a selection, setting the selection, and getting the last selection.
• ITransactionContext: Useful for implementing transactions on data and simplifies editor design. It allows transactions to be cancelled at any time before finalizing.
• IValidationContext: Context provides events for marking when the user begins and ends logical commands, so event listeners can perform validation.
• IViewingContext: For contexts where items can be viewed. Its methods check whether objects are or can be made visible, or are framed or can be framed in the current view.

For more information on these interfaces and where they are used, see Context Interfaces.

ILockingContext, IObservableContext, ITransactionContext, and IValidationContext are in the Sce.Atf namespace.

For more details on contexts, see ATF Contexts.

Property Editing Framework

The Property Editing Framework edits properties using controls. For each property, a property value editor provides an appropriate value editing control for that property's data type. ATF offers a large variety of property value editors and value editing controls for various types. For an overview of property editing, see Using Properties in ATF.

Because a property editor shows properties for a selection, it depends on the current context. Property editors can only be used when there is a selection and the active context allows properties to be edited. ATF uses the context to determine which property editors are appropriate.

If a context allows property editing, it implements one of these interfaces in the Property Editing Framework:

• IPropertyEditingContext: Interface for contexts in which properties can be edited by controls.
• ISelectionContext: Interface for selection contexts to get the current selection and be notified when the selection changes. (Also in the Context Framework.)

For more information on these contexts, see Selection Property Editing Context.

The Property Editing Framework offers components to edit properties:

• PropertyEditor: Edit object values and attributes using the ATF PropertyGrid, which is a two-column editing control. Using this component, you can see and edit properties of only one selected item.
• GridPropertyEditor: Edit object values and attributes using the ATF GridControl, a spreadsheet-style editing control. With this component, you can see and edit properties of all selected items.
• PropertyEditingCommands: Provide property editing commands, such as Reset All and Reset Current, in a context menu that can be used inside property editor controls like PropertyGrid.

For more information on these components, see Property Editor Components.

The Property Editing Framework components access the Context Framework using the IContextRegistry interface, which allows them to get the current context.

For a detailed discussion of property editing, see Property Editing in ATF.

Document Object Model Framework

The Document Object Model (DOM) Framework provides a powerful, flexible, and extensible mechanism for loading, storing, validating, and managing changes to large amounts of application or game data, independently of application code. Although ATF does not require that applications use a DOM, a DOM is an excellent way to represent application data.

Application data is stored in a tree of DOM nodes (DomNode class), with each DOM node having attributes and child DOM nodes. The DOM node attributes store primitive types of data, like integers and strings, or arrays of these types. The attributes and children available on a particular DOM node depend on the DOM node's type. Typically application data types and their corresponding DOM node types are defined in the XML Schema Definition (XSD) language, but types can be defined in other languages as well. To learn more about DomNodes, see DomNodes and DOM Metadata Classes.

The ATF DOM differs from conventional XML DOM implementations by converting document data to primitive type values and arrays, which makes it much more suitable for representing data, such as large triangle meshes. In addition, if your application's data can be stored as an XML document, you gain a lot by using ATF's DOM and Schema/XML support.

The DOM architecture also includes the concept of DOM node adapters (DOM adapters, for short), which use adaption to allow you to define a C# API for your DOM data—separating game and application data from the code that operates on it. For more details, see DOM Adapters.

The ATF DOM offers these advantages:

• Simple managed data store design.
• Easy and powerful DOM data adaptation, with notification events for each DOM node.
• Optional DOM adapters for unique naming, reference tracking, implementing transactions, and name lookup.
• DOM adapters to decouple the data storage (in DOM nodes) from how data is used.

The ATF Document Object Model is in the Sce.Atf.Dom namespace. Classes in this namespace include features to:

• Load and register XML schema type definition files that define the application's data types.
• Use schema metadata objects to define DOM data types for the application's data types.
• Create and manage repositories and collections of DOM objects that contain the actual application data.
• Load and store DOM data, either in XML or in any format you define. The ATF DOM provides built-in support for XML data storage and retrieval.
• Implement and register DOM adapters to create dynamic object APIs to the underlying DOM node objects.
• Define and manage DOM annotations in the schema to add custom properties or additional information to data types. For example, you could add an annotation to indicate the control to use to edit a data type or to specify a rendering proxy.
• Add constraints to DOM data to update a set of output data based on an input, such as a user action. For example, update a transformation matrix each time a 3D object is scaled or rotated.
• Validate data in the DOM.

For an introduction to the DOM, see DOM in a Nutshell. See the ATF Programmers Guide: Document Object Model (DOM) for details on using the ATF DOM to manage application data, downloadable from ATF Documentation.