UI Automation Support for the List Control Type
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 provides information about UI Automation support for the List control type. In UI Automation, a control type is a set of conditions that a control must meet in order to use the ControlTypeProperty property. The conditions include specific guidelines for UI Automation tree structure, UI Automation property values and control patterns.
The List control type provides a way to organize a flat group or groups of items and allows a user to select one or more of those items. The List control type has a loose restriction on what types of child elements it may contain. This enables UI Automation providers to support a well-known element for selection containers.
The UI Automation requirements in the following sections apply to all controls that implement the List control type, whether Windows Presentation Foundation (WPF), Win32, or Windows Forms. List container controls are an example of controls that implement the List control type.
Required UI Automation Tree Structure
The following table depicts the two views of the UI Automation tree that pertain to list controls and describes what can be contained in each view. The control view contains only elements that are controls, and the content view removes redundant information from the tree. For example, a text control used to label a combo box will be exposed as the ComboBox NameProperty. Because the text control is already exposed in this manner through the control view it is unnecessary to have it exposed twice; therefore it is removed from the content view. For more information on the UI Automation tree, see UI Automation Tree Overview.
| Control View | Content View |
|---|---|
| Contains the elements that correspond to controls. | Removes redundant information from the tree so that assistive technologies work with the smallest set of meaningful information to the end user. |
| List - DataItem (0 or more) - ListItem (0 or more) - Group (0 or more) - ScrollBar (0, 1 or 2) |
List - DataItem (0 or more) - ListItem (0 or more) - Group (0 or more) |
The control view for a control that implements the List control type (such as a list control) consists of:
Zero or more items within the list control (items can be based on the List Item or Data Item control types).
Zero or more group controls within a list control.
Zero, one, or two scroll bar controls.
The content view of a control that implements the List control type (such as a list control) consists of:
Zero or more items within the list control (items can be based on the List Item or Data Item control types).
Zero or more groups within the list control.
A list control must not have items that have a hierarchical relationship other than being grouped together. If the items have children in the UI Automation tree, then the list container should be based on the Tree control type.
The selectable items within the list control will be available from the descendants in the UI Automation tree of the list control. All items within the list control must belong to the same selection group. The selectable items in the list should be exposed as ListItem (instead of DataItem) control types.
Required UI Automation Properties
The following table lists the UI Automation properties whose value or definition is especially relevant to list controls. For more information on UI Automation properties, see UI Automation Properties for Clients.
| UI Automation Property | Value | Notes |
|---|---|---|
| AutomationIdProperty | See notes. | The value of this property needs to be unique across all controls in an application. |
| BoundingRectangleProperty | See notes. | The outermost rectangle that contains the whole control. |
| ClickablePointProperty | See notes. | If the list control has a clickable point (a point that can be clicked to cause the list to take focus), then that point must be exposed through this property. If the value of the IsOffScreen property is true, then the NoClickablePointException will be raised. |
| IsKeyboardFocusableProperty | See notes. | If the control can receive keyboard focus, it must support this property. |
| NameProperty | See notes. | The value of a list control's Name property should convey the category of options that the user is being asked to select from. This property typically gets its name from a static text label. If there is not a static text label the application developer must expose a value for the Name property. The only time this property is not required for list controls is if the control is used within the subtree of another control. |
| LabeledByProperty | See notes. | If there is a static text label then this property must expose a reference to that control. |
| ControlTypeProperty | List | This value is the same for all UI frameworks. |
| LocalizedControlTypeProperty | "list" | Localized string corresponding to the List control type. |
| IsContentElementProperty | True | The list control is always included in the content view of the UI Automation tree. |
| IsControlElementProperty | True | The list control is always included in the control view of the UI Automation tree. |
| IsKeyboardFocusableProperty | True | If the container can accept keyboard input then this property value should be true. |
| HelpTextProperty | See notes. | The Help text for list controls should explain why the user is being asked to make a choice from a list of options. For example, "Selection an item from this list will set the display resolution for your monitor." |
Required UI Automation Control Patterns and Properties
The following table lists the UI Automation control patterns required to be supported by list controls. For more information on control patterns, see UI Automation Control Patterns Overview.
| Control Pattern/Pattern Property | Support/Value | Notes |
|---|---|---|
| ISelectionProvider | Required | All controls that support the List control type must implement ISelectionProvider when a selection state is maintained between the items contained in the control. If the items within the container are not selectable, the Group control type must be used. |
| IsSelectionRequired | Depends | List controls do not always require that an item be selected. |
| CanSelectMultiple | Depends | List controls can be single or multiple-selection containers. |
| IScrollProvider | Depends | Implement this control pattern if items in the container are scrollable. |
| IGridProvider | Depends | Implement this pattern when grid navigation needs to be available on an item by item basis. |
| IMultipleViewProvider | Depends | Implement this control pattern if the control can support multiple views of the items in the container. |
| ITableProvider | Never | ITableProvider is never supported for the List control type. If the control should support this control pattern, then the control should be based on the Data Grid control type. |
Required UI Automation Events
The following table lists the UI Automation events required to be supported by all list controls. For more information on events, see UI Automation Events Overview.
| UI Automation Event | Support/Value | Notes |
|---|---|---|
| InvalidatedEvent | Depends | None |
| LayoutInvalidatedEvent | Depends | None |
| BoundingRectangleProperty property-changed event. | Required | None |
| IsOffscreenProperty property-changed event. | Required | None |
| IsEnabledProperty property-changed event. | Required | None |
| CurrentViewProperty property-changed event. | Depends | None |
| HorizontallyScrollableProperty property-changed event. | Depends | None |
| HorizontalScrollPercentProperty property-changed event. | Depends | None |
| HorizontalViewSizeProperty property-changed event. | Depends | None |
| VerticalScrollPercentProperty property-changed event. | Depends | None |
| VerticallyScrollableProperty property-changed event. | Depends | None |
| VerticalViewSizeProperty property-changed event. | Depends | None |
| AutomationFocusChangedEvent | Required | None |
| StructureChangedEvent | Required | None |