Core ATF Frameworks

These frameworks typically define a few interfaces and provide classes or components that implement them.

You can modify or replace these components to suit your own purposes, but you may want to keep components general enough so that you can use them in other applications.

Nearly all the components mentioned here are in the Sce.Atf.Applications namespace. For a description of the main ATF namespaces, see ATF Namespaces.

Table of Contents Application Shell Framework Document Framework Commands Adaptation Framework Instancing Framework Property Editing Framework Context Framework Document Object Model (DOM) Framework

Application Shell Framework

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

• ControlHostService: provides a dock in which to hold controls, such as menus and toolbars. Its 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: displays currently available application commands to the user in menus and toolbars and provides keyboard shortcuts. Its interface is ICommandService. See CommandService Component for more information.
• StatusService: adds a status bar at the bottom of the main form. Its interface is IStatusService. For a further discussion, see SettingsService Component.
• SettingsService: manages 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.

As an example of 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.

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.

The Document Framework contains the following interfaces:

• IDocument: the interface for application documents, which provides read-only and dirty properties. This is in the Sce.Atf namespace.
• IDocumentService: the interface for 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.
• IDocumentRegistry: the interface to the document registry. The document registry holds 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.
• IDocumentClient: opens, closes, and displays 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.

Here are the Document Framework components (services):

• StandardFileCommands: implements 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 component in the application.
• AutoDocumentService: opens documents from the previous application session or creates a new empty document when an application starts.
• RecentDocumentCommands: adds recently opened documents to the application's File > Recent Documents submenu.
• DocumentRegistry: tracks the open documents in an application. It can retrieve the active document or most recently active document of a given type.
• MainWindowTitleService: updates the main dialog's title to reflect the current document and its state, i.e., modified or not.

For a further discussion, see Documents in ATF.

Commands

An application usually needs to add custom commands for its menus, buttons, and other controls.

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.

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.

ICommandClient is the interface you implement so that CommandService calls your command code back when the user clicks on your command's menu item or icon in a tool strip. ICommandClient also determines whether a command can be performed.

Several ATF components add sets of commands to an application:

• StandardFileCommands: add standard File commands.
• StandardSelectionCommands: add standard selection commands.
• 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.

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

Adaptation Framework

The Adaptation Framework allows supporting different kinds of data models and managed data stores, such as a DOM or other CLR objects, by converting objects to other types. An adapter for A converts something of a different type than A to the same type as A. Adapters implement the IAdapter interface.

The adaptable interface, IAdaptable, obtains adapters to other types. You don't have to implement the interface on a particular type. You can use IAdaptable to extend type casting. This works for CLR types and DOMs.

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

• These controls can be decorated with 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.

AdapterCreator is a useful class that produces adapters of the given type T.

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

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 typing text onto a page, 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 CanCopy() and Copy(), CanInsert() and Insert(), CanDelete() and Delete() methods. A context should implement this interface if it allows editing objects.

The Instancing Framework's main component is StandardEditCommands, which provides editing commands.

Two parts of ATF use the Instancing Framework:

• StandardEditCommands uses IInstancingContext to implement copy, cut, paste, or delete operations.
• Drag and drop operations use the Instancing Framework to insert objects into a context.

Miscellaneous commands, such as grouping commands, also use the Instancing Framework to delete all the objects in a group or insert objects.

The Instancing Framework's component StandardEditCommands references the Context Framework to access context information, such as the active context.

The StandardEditCommands component 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 and be undone and redone.

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. Drag and drop operations also use the IDataObject interface.

Property Editing Framework

The Property Editing Framework works with contexts that allow properties to be edited by controls. ATF offers a variety of property editor controls to edit object properties of various types.

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.)

The following are the Property Editing Framework components to edit properties:

• PropertyEditor: edit object values and attributes using the ATF PropertyGrid, which is a two-column editing control.
• GridPropertyEditor: edit object values and attributes using the ATF GridControl, a spreadsheet-style editing control.
• PropertyEditingCommands: provide property editing commands in a context menu that can be used inside property editor controls like PropertyGrid.

Property Editing Framework components use the Context Framework to get the current context.

ATF property editors first check if the active context implements IPropertyEditingContext. If not, they determine if the ISelectionContext interface is implemented, and, if so, operate in standard .NET fashion, using ICustomTypeDescriptor or reflection to get object properties.

PropertyEditingCommands operates in a similar way. It provides the property operation commands Reset All and Reset Current in a context menu that appears when the user right-clicks a property editing control. PropertyEditingCommands can be used with ATF property editors or with custom property editors.

The Property Editing Framework components access the Context Framework using the IContextRegistry interface. The Context Framework can be replaced with a custom framework.

Context Framework

The Context Framework tracks and works with application contexts.

A context is 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. IContextRegistry maintains 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, i.e., can be performed.

All ATF components access the registry using IContextRegistry.

An application may include Editor, Command, and Application View modules, which all need context information. These modules can access the Context Framework with IContextRegistry.

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:

• 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. Note that this context could operate on many different kinds of data; this is true of other contexts as well.
• 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.
• IValidationContext: Useful for marking when the user begins and ends logical commands. Validators can wait to check constraints until after an ending event, so the validator can allow invalid states as data changes, but before validation ends, it can raise an exception if a constraint is not satisfied. Observers of the data can respond efficiently: instead of responding to every change in data, they can wait for validation and then update in one operation. Operations can also be cancelled.
• ISelectionContext: Distills 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. It also provides filtering: you can get the last selected object of a certain type. It has events detecting before and after a selection changes. It has an efficient method for determining if a selection contains an object.
• IPropertyEditingContext: Allow property editing components to get properties and items with properties, enabling property editing controls to display objects and their properties.
• IObservableContext: Allow observers of list and tree data to track changes. If an application finds that the active context implements IObservableContext, it can implement an editable view that stays in sync with the data. If applications do not find IObservableContext, they can assume the view is read-only and still consume data.
• ITransactionContext: Useful for implementing transactions on data. ITransactionContext simplifies editor design. It allows transactions to be cancelled at any time before calling the End() method. Different modules can contribute to an operation without having to know about each other, and if an exception occurs in one module, the whole transaction can be rolled back.
• IInstancingContext: For contexts that can instance objects: instancing requires the ability to copy, insert, and delete items. This interface integrates well with the Windows clipboard, because it uses System.Windows.IDataObject, which is used by the Windows Cut, Copy, Paste, Delete, and drag and drop commands. IInstancingContext should be used by any code that wants to create new instances, such as "Group"/"Ungroup" commands.
• ILockingContext: Support read-only documents and lockable objects. ILockingContext determines whether an object is locked, so the object cannot be changed or deleted.
• IHistoryContext: Enable implementing "Undo"/"Redo" commands. It tracks what has changed since the document was last saved.

ContextRegistry and IContextRegistry and most of the context interfaces mentioned here are in the Sce.Atf.Applications namespace. IValidationContext, IObservableContext, ITransactionContext, and ILockingContext are in Sce.Atf.

Document Object Model (DOM) 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. ATF does not require that applications use a DOM, but a DOM is an excellent way to represent application data.

Application data is stored in a tree of DOM nodes, 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 DOM node types are defined in the XML Schema Definition (XSD) language, but types can be defined in other languages as well.

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 like 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 enable you to define a C# API for your DOM data—separating game and application data from the code that operates on it.

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 node adapters for unique naming, reference tracking, implementing transactions, and name lookup.
• DOM node adapters to decouple the data storage (in DOM nodes) from how data is used.

The Sce.Atf.Dom namespace defines the ATF Document Object Model. 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.
• Create and manage repositories and collections of DOM objects, which 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 can 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.

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.