Registering Controls

Table of Contents IControlHostService Registering Controls Topics in this section

The ControlHostService component registers controls, which makes them available in the user interface. You only need to register top-level controls, although all the controls in your application must either be registered or have a registered control as a parent.

In addition to information about the control, you specify a control client that is notified when the control is activated, deactivated, or requested to close. For details, see Creating Control Clients.

IControlHostService

ControlHostService implements IControlHostService. There are different versions of this component and interface for WinForms and WPF, but both offer similar capabilities.

IControlHostService contains these methods:

• RegisterControl(): Register the control, using the information in either a ControlInfo for WinForms or ControlDef for WPF, and also specify the control client. Several RegisterControl() versions are offered as extension methods with parameters to get control information directly, rather than through a ControlInfo or ControlDef object.
• UnregisterControl() (WinForms) or UnregisterContent() (WPF): Unregister the control and its contents, that is, any child controls or other content.
• Show(): Make the control visible.

Registering Controls

You need to provide the following (or equivalent information) to register a control:

• Control: Control to be registered.
• ControlInfo or ControlDef: Describe the control's appearance in the UI, as described in ControlInfo and ControlDef Classes. This information may also be specified in parameters in RegisterControl().
• IControlHostClient: Client to be notified for activation, deactivation, and close events. To learn more, see Creating Control Clients.

IControlHostService provides several RegisterControl() methods, including convenience methods with parameters containing the information ControlInfo or ControlDef provides, so you don't need to explicitly create a ControlInfo or ControlDef object.

The order in which RegisterControl() is called in your application determines the order in which controls and groups of controls appear in the dock.???

The simplest registration method for WinForms is:

void RegisterControl(Control control, ControlInfo controlInfo, IControlHostClient client);

and for WPF:

IControlInfo RegisterControl(ControlDef definition, object control, IControlHostClient client);

This line from the ATF Simple DOM Editor Sample registers a ListView control:

m_controlHostService.RegisterControl(context.ListView, controlInfo, this);

The field m_controlHostService is an IControlHostService instance, which is imported using MEF. The argument controlInfo is a ControlInfo object containing the control's UI description. The Editor class containing this code not only registers this control, but provides an implementation of the control client, because it implements IControlHostClient. In the line above, this provides the required IControlHostClient parameter.

This longer call in the PaletteService component specifies the control information parameters and control client for a palette control:

m_controlInfo = m_controlHostService.RegisterControl(
    new PaletteContent(this),
    "Palette",
    "Creates new instances",
    Sce.Atf.Applications.StandardControlGroup.Left,
    s_paletteControl.ToString(), this);

This example in the WPF OutputService component specifies the control information parameters, including an ID, and the control client for an output control:

ControlHostService.RegisterControl(
    m_view,
    "Output".Localize(),
    "View errors, warnings, and informative messages".Localize(),
    Sce.Atf.Applications.StandardControlGroup.Bottom,
    kId.ToString(),
    this);

Topics in this section