Implementing the UI Automation Selection Control Pattern

System_CAPS_ICON_note.jpg 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 ISelectionProvider, including information about events and properties. Links to additional references are listed at the end of the topic.

The SelectionPattern control pattern is used to support controls that act as containers for a collection of selectable child items. The children of this element must implement ISelectionItemProvider. For examples of controls that implement this control pattern, see Control Pattern Mapping for UI Automation Clients.

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

  • Controls that implement ISelectionProvider allow either single or multiple child items to be selected. For example, list box, list view, and tree view support multiple selections whereas combo box, slider, and radio button group support single selection.

  • Controls that have a minimum, maximum, and continuous range, such as the Volume slider control, should implement IRangeValueProvider instead of ISelectionProvider.

  • Single-selection controls that manage child controls that implement IRawElementProviderFragmentRoot, such as the Screen Resolution slider in the Display Properties dialog box or the Color Picker selection control from Microsoft Word (illustrated below), should implement ISelectionProvider; their children should implement both IRawElementProviderFragment and ISelectionItemProvider.

Color picker with yellow highlighted.
Example of Color Swatch String Mapping

  • Menus do not support SelectionPattern. If you are working with menu items that include both graphics and text (such as the Preview Pane items in the View menu in Entity with relative path '../Token/' can not be found, for source topic '{"project_id":"3fedad16-eaf1-41a6-8f96-0c1949c68f32","entity_id":"449c3068-a5d6-4f66-84c6-1bcc7dd4d209","entity_type":"Article","locale":"en-US"}'.) and need to convey state, you should implement IToggleProvider.

The following properties, methods, and events are required for the ISelectionProvider interface.

Required membersTypeNotes
CanSelectMultiplePropertyShould support property changed events using AddAutomationPropertyChangedEventHandler and RemoveAutomationPropertyChangedEventHandler.
IsSelectionRequiredPropertyShould support property changed events using AddAutomationPropertyChangedEventHandler and RemoveAutomationPropertyChangedEventHandler.
InvalidatedEventEventRaised when a selection in a container has changed significantly and requires sending more addition and removal events than the InvalidateLimit constant permits.

The IsSelectionRequired and CanSelectMultiple properties can be dynamic. For example, the initial state of a control might not have any items selected by default, indicating that IsSelectionRequired is false. However, after an item is selected, the control must always have at least one item selected. Similarly, in rare cases, a control might allow multiple items to be selected on initialization, but subsequently allow only single selections to be made.

Providers must throw the following exceptions.

Exception TypeCondition
ElementNotEnabledExceptionIf the control is not enabled.
InvalidOperationExceptionIf the control is hidden.

UI Automation Control Patterns Overview
Support Control Patterns in a UI Automation Provider
UI Automation Control Patterns for Clients
Implementing the UI Automation SelectionItem Control Pattern
UI Automation Tree Overview
Use Caching in UI Automation