Edit

Implementing the UI Automation Invoke Control Pattern

  • Article

Note

This documentation is intended for .NET Framework developers who want to use the managed UI Automation classes defined in the System.Windows.Automation namespace. For the latest information about UI Automation, see Windows Automation API: UI Automation.

This topic introduces guidelines and conventions for implementing IInvokeProvider, including information about events and properties. Links to additional references are listed at the end of the topic.

The InvokePattern control pattern is used to support controls that do not maintain state when activated but rather initiate or perform a single, unambiguous action. Controls that do maintain state, such as check boxes and radio buttons, must instead implement IToggleProvider and ISelectionItemProvider respectively. For examples of controls that implement the Invoke control pattern, see Control Pattern Mapping for UI Automation Clients.

Implementation Guidelines and Conventions

When implementing the Invoke control pattern, note the following guidelines and conventions:

  • Controls implement IInvokeProvider if the same behavior is not exposed through another control pattern provider. For example, if the Invoke method on a control performs the same action as the Expand or Collapse method, the control should not implement IInvokeProvider.

  • Invoking a control is generally performed by clicking or double-clicking or pressing ENTER, a predefined keyboard shortcut, or some alternate combination of keystrokes.

  • InvokedEvent is raised on a control that has been activated (as a response to a control carrying out its associated action). If possible, the event should be raised after the control has completed the action and returned without blocking. The Invoked event should be raised before servicing the Invoke request in the following scenarios:

    • It is not possible or practical to wait until the action is complete.

    • The action requires user interaction.

    • The action is time-consuming and will cause the calling client to block for a significant amount of time.

  • If invoking the control has significant side-effects, those side-effects should be exposed through the HelpText property. For example, even though Invoke is not associated with selection, Invoke may cause another control to become selected.

  • Hover (or mouse-over) effects generally do not constitute an Invoked event. However, controls that perform an action (as opposed to cause a visual effect) based on the hover state should support the InvokePattern control pattern.

Note

This implementation is considered an accessibility issue if the control can be invoked only as a result of a mouse-related side effect.

  • Invoking a control is different from selecting an item. However, depending on the control, invoking it may cause the item to become selected as a side-effect. For example, invoking a Microsoft Word document list item in the My Documents folder both selects the item and opens the document.

  • An element can disappear from the UI Automation tree immediately upon being invoked. Requesting information from the element provided by the event callback may fail as a result. Pre-fetching cached information is the recommended workaround.

  • Controls can implement multiple control patterns. For example, the Fill Color control on the Microsoft Excel toolbar implements both the InvokePattern and the ExpandCollapsePattern control patterns. ExpandCollapsePattern exposes the menu and the InvokePattern fills the active selection with the chosen color.

Required Members for IInvokeProvider

The following properties and methods are required for implementing IInvokeProvider.

Required members Member type Notes
Invoke method Invoke is an asynchronous call and must return immediately without blocking.

This behavior is particularly critical for controls that, directly or indirectly, launch a modal dialog when invoked. Any UI Automation client that instigated the event will remain blocked until the modal dialog is closed.

Exceptions

Providers must throw the following exceptions.

Exception Type Condition
ElementNotEnabledException If the control is not enabled.

See also