Using Controls in ATF

Table of Contents Controls ControlHostService Control Groups Registering Controls Control Behavior WinForms and WPF Topics in this section

Controls

You can use any .NET control or derived .NET control in an ATF application. ATF also offers a large set of additional controls to supplement the standard .NET controls. These include utility controls for editing numbers and file paths, tree and list controls, and palettes. ATF also offers special purpose controls that are useful for game development applications, such as timeline and curve controls. For more information on these controls, see ATF Custom Controls.

ControlHostService

The ControlHostService component is responsible for handling client controls in the application's main form. ControlHostService automatically manages docking, pinning, and show/hide behavior for controls registered with this service. ControlHostService implements the IControlHostService interface. For more information, see ControlHostService Component.

ControlHostService also implements IControlRegistry, which tracks active controls, noting when controls are activated or deactivated. This interface provides:

• ActiveControl property.
• Controls property listing open controls ControlInfo objects with control information.
• Events before and after an active control change.
• Events for a control being added or removed.

Control Groups

Top-level controls are controls that are immediate children of your application's main form and are docked to that main form. Top-level controls make up the main palettes, editors, panels, and document windows of your application.

Control groups determine the appearance and initial docking location for top-level controls in an application's main form. Controls may be on the top, bottom, left, right, or center of the main form, or can float, free of the dock. Top-level controls in any position other than center permanent can be undocked, hidden, and then shown and docked again by the user.

Multiple controls in the same position are overlapped and displayed with tabs. Center controls always have tabs, even if there is only one. Tabs are shown with name labels, and you can also specify an icon for the tab when you register the control.

All the control group identifiers are listed in the StandardControlGroup enumeration. For details, see ATF Control Groups.

Registering Controls

All controls must be registered with ControlHostService. Only top-level controls need to be directly registered with ControlHostService, although all controls must either be themselves registered or have a registered control as a parent.

ControlHostService implements IControlHostService, which contains methods to register, unregister, and show controls.

You can register a control with a ControlInfo object for WinForms or a ControlDef object for WPF. These classes provide information about a control: its name for a control title, description for a tooltip, group, initial location in the dock, and an optional image appearing on a control tab.

For more information about the control information classes, see ControlInfo and ControlDef Classes.

To learn more about control registration, see Registering Controls.

Control Behavior

Define registered control behavior with the methods in the IControlHostClient interface. Control behavior includes what actions should occur, if any, when the control gains or loses focus (activated or deactivated), or is closed. The class on which you implement this interface is called the control client. You can define the client to be the same class as the one in which you register the control, or some other class. You specify the client when you register the control.

For details, see Creating Control Clients.

WinForms and WPF

The IControlHostService interface differs slightly for WinForms and WPF, and their ControlHostService components also differ. To register a control, use a ControlInfo object in WinForms and a ControlDef object in WPF. Though these components and interfaces differ somewhat, both offer comparable capability.

The IControlHostClient interfaces are also very similar for both. For details, see Creating Control Clients.

Topics in this section