Creating Control Clients

Table of Contents IControlHostClient interface Activate Method Deactivate Method Close Method Topics in this section

The control client specifies the control's behavior, if any, when the control gains or loses focus, or is closed. You can implement this interface in the same class in which you call RegisterControl() or in a separate class.

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

IControlHostClient interface

A control client implements the IControlHostClient interface, which consists of these methods for WinForms:

void Activate(Control control);
void Deactivate(Control control);
bool Close(Control control);

These are the methods for WPF, which are almost the same, except that the parameter is object rather than Control, and Close() has an extra parameter:

void Activate(object control);
void Deactivate(object control);
bool Close(object control, bool mainWindowClosing);

Activate Method

The Activate() method notifies the client that its control is activated, that is, gains focus. Activation occurs when the control gets focus, or the control's parent "host" control gets focus.

Use this method to update other objects or perform operations that should occur when the control gains input focus. A common use of this method is to notify command clients that the context has changed by the control being activated.

Use the ICommandService.SetActiveClient() method to switch the command client when the control gains focus, as in this example from the OutputService component:

public void Activate(Control control)
{
    if (m_commandService!= null)
        m_commandService.SetActiveClient(this);
}

For information about command clients, see Creating Command Clients.

This example from the ATF Simple DOM Editor Sample shows a document control setting the active document and context when it is activated:

void IControlHostClient.Activate(Control control)
{
    EventSequenceDocument document = control.Tag as EventSequenceDocument;
    if (document != null)
    {
        m_documentRegistry.ActiveDocument = document;

        EventSequenceContext context = document.As<EventSequenceContext>();
        m_contextRegistry.ActiveContext = context;
    }
}

For a discussion of contexts, see the topics in ATF Contexts.

Deactivate Method

Deactivate()'s purpose is to notify the client that its control is deactivated, that is, loses focus. Deactivation occurs when another control gets focus or the control's "host" control loses focus.

In this example from the OutputService component, the active command client is set to null when the output control is deactivated:

public void Deactivate(Control control)
{
    if (m_commandService != null)
        m_commandService.SetActiveClient(null);
}

Close Method

This method requests permission to close the client's control. It returns true if the control can close, or false to not close. For WPF, the mainWindowClosing parameter is true if the application's main window is closing.

If true is returned, ControlHostService calls UnregisterControl(). The application has to call RegisterControl() again if it wants to re-register this control.

This method is not called when the user toggles control visibility by using Windows® menu commands.

This sample, from the editor common code of ATF Win Forms App Sample and ATF Wpf App Sample, allows the control to close if its document can be closed:

bool IControlHostClient.Close(Control control)
{
    bool closed = true;

    WinGuiCommonDataDocument document = control.Tag as WinGuiCommonDataDocument;
    if (document != null)
    {
        closed = m_documentService.Close(document);
        if (closed)
            m_contextRegistry.RemoveContext(document);
    }

    return closed;
}

NOTE: If a particular control is closed when an application terminates, its control client's Close() method should usually call IDocumentService.Close(), as the previous example does. This gives the opportunity to check whether the document is dirty and offer the user the option of saving it; otherwise changes are lost. For instance, the often used StandardFileCommands component implements IDocumentService and, if the document's IDocument.Dirty property is true, its IDocumentService.Close() method asks a user whether or not the document's changes should be saved or discarded.

Topics in this section