Implementing the UI Automation SelectionItem Control Pattern

Article
11/03/2006

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

The SelectionItemPattern control pattern is used to support controls that act as individual, selectable child items of container controls that implement ISelectionProvider. For examples of controls that implement the SelectionItem control pattern, see Control Pattern Mapping for UI Automation Clients

This topic contains the following sections.

Implementation Guidelines and Conventions
Required Members for ISelectionItemProvider
Exceptions
Related Topics

Implementation Guidelines and Conventions

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

Single-selection controls that manage child controls that implement IRawElementProviderFragmentRoot, such as the Screen Resolution slider in the Display Properties dialog box, should implement ISelectionProvider and their children should implement both IRawElementProviderFragment and ISelectionItemProvider.

Required Members for ISelectionItemProvider

The following properties, methods, and events are required for implementing ISelectionItemProvider.

Required members	Member type	Notes
CanSelectMultiple	Property	None
IsSelectionRequired	Property	None
GetSelection	Method	None
InvalidatedEvent	Event	Raised when a selection in a container has changed significantly and requires sending more ElementSelectedEvent and ElementRemovedFromSelectionEvent events than the InvalidateLimit constant permits.

If the result of a Select, an AddToSelection, or a RemoveFromSelection is a single selected item, an ElementSelectedEvent should be raised; otherwise send ElementAddedToSelectionEvent/ ElementRemovedFromSelectionEvent as appropriate.

Exceptions

Providers must throw the following exceptions.

Exception type	Condition
InvalidOperationException	When any of the following are attempted: RemoveFromSelection is called on a single-selection container where IsSelectionRequiredProperty = true and an element is already selected. RemoveFromSelection is called on a multiple-selection container where IsSelectionRequiredProperty = true and only one element is selected. AddToSelection is called on a single-selection container where CanSelectMultipleProperty = false and another element is already selected.

InvalidOperationException

When any of the following are attempted:

RemoveFromSelection is called on a single-selection container where IsSelectionRequiredProperty = true and an element is already selected.
RemoveFromSelection is called on a multiple-selection container where IsSelectionRequiredProperty = true and only one element is selected.
AddToSelection is called on a single-selection container where CanSelectMultipleProperty = false and another element is already selected.

Implementing the UI Automation SelectionItem Control Pattern

Implementation Guidelines and Conventions

Required Members for ISelectionItemProvider

Exceptions

See Also

Tasks

Concepts

Other Resources

Additional resources