List Control Type
This topic provides information about Microsoft UI Automation support for the List control type.
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 following sections define the required UI Automation tree structure, properties, control patterns, and events for the List control type. The UI Automation requirements apply to all list controls where the UI framework/platform integrates UI Automation support for control types and control patterns.
This topic contains the following sections.
- Typical Tree Structure
- Relevant Properties
- Required Control Patterns and Properties
- Required Events
- Related topics
Typical Tree Structure
The following table depicts a typical control and content view of the UI Automation tree that pertains to list controls, and describes what can be contained in each view. For more information about 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 information that is meaningful to the end user. |
|
|
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 ListItem or DataItem 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 ListItem or DataItem 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.
Relevant Properties
The following table lists the UI Automation properties whose value or definition is especially relevant to the List control type. For more information about UI Automation properties, see Retrieving Properties from UI Automation Elements.
| UI Automation Property | Value | Notes |
|---|---|---|
| UIA_AutomationIdPropertyId | See notes. | The value of this property must be unique among all peer elements in the raw view of the UI Automation tree. |
| UIA_BoundingRectanglePropertyId | See notes. | The outermost rectangle that contains the whole control. |
| UIA_ClickablePointPropertyId | See notes. | If the list control has a clickable point (a point that can be clicked to cause the list to take focus), that point must be exposed through this property. If the value of the UIA_IsOffscreenPropertyId property is TRUE, attempting to retrieve this property results in the UIA_E_NOCLICKABLEPOINT error. |
| UIA_ControlTypePropertyId | List | |
| UIA_HelpTextPropertyId | 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." |
| UIA_IsContentElementPropertyId | TRUE | The list control is always included in the content view of the UI Automation tree. |
| UIA_IsControlElementPropertyId | TRUE | The list control is always included in the control view of the UI Automation tree. |
| UIA_IsKeyboardFocusablePropertyId | See notes. | If the control can receive keyboard focus, it must support this property. |
| UIA_LabeledByPropertyId | See notes. | If there is a static text label then this property must expose a reference to that control. |
| UIA_LocalizedControlTypePropertyId | See notes. | Localized string corresponding to the List control type. The default value is "list" for en-US or English (United States). |
| UIA_NamePropertyId | 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. |
Required Control Patterns and Properties
The following table lists the UI Automation control patterns required to be supported by all list controls. For more information on control patterns, see UI Automation Control Patterns Overview.
| Control Pattern/Pattern Property | Support/Value | Notes |
|---|---|---|
| IGridProvider | Depends | Implement the Grid control pattern when grid navigation needs to be available on an item by item basis. |
| IMultipleViewProvider | Depends | Implement the MultipleView control pattern if the control can support multiple views of the items in the container. |
| IScrollProvider | Depends | Implement the Scroll control pattern if items in the container are scrollable. |
| ISelectionProvider | Depends | If a control supports the List control type that supports selection, the control must implement the Selection control pattern when a selection state is maintained between the items contained in the control. If the items within the control are not selectable, the Group control type can be used. |
| CanSelectMultiple | Depends | List controls can be single or multiple-selection containers. |
| IsSelectionRequired | Depends | List controls do not always require that an item be selected. |
| ITableProvider | Never | The Table control pattern is never supported for the List control type. If the control needs to support this control pattern, the control should be based on the DataGrid control type. |
Required Events
The following table lists the UI Automation events that list controls are required to support. For more information on events, see UI Automation Events Overview.
| UI Automation Event | Notes |
|---|---|
| UIA_AutomationFocusChangedEventId | |
| UIA_BoundingRectanglePropertyId property-changed event. | |
| UIA_IsEnabledPropertyId property-changed event. | If the control supports the IsEnabled property, it must support this event. |
| UIA_IsOffscreenPropertyId property-changed event. | If the control supports the IsOffscreen property, it must support this event. |
| UIA_LayoutInvalidatedEventId | If the layout of child items can be changed, the control must support this event. |
| UIA_MultipleViewCurrentViewPropertyId property-changed event. | If the control supports the MultipleView control pattern, it must support this event. |
| UIA_ScrollHorizontallyScrollablePropertyId property-changed event. | If the control supports the Scroll control pattern, it must support this event. |
| UIA_ScrollHorizontalScrollPercentPropertyId property-changed event. | If the control supports the Scroll control pattern, it must support this event. |
| UIA_ScrollHorizontalViewSizePropertyId property-changed event. | If the control supports the Scroll control pattern, it must support this event. |
| UIA_ScrollVerticalScrollPercentPropertyId property-changed event. | If the control supports the Scroll control pattern, it must support this event. |
| UIA_ScrollVerticallyScrollablePropertyId property-changed event. | If the control supports the Scroll control pattern, it must support this event. |
| UIA_ScrollVerticalViewSizePropertyId property-changed event. | If the control supports the Scroll control pattern, it must support this event. |
| UIA_Selection_InvalidatedEventId | If the control supports the Selection control pattern, it must support this event. |
| UIA_StructureChangedEventId |
Related topics
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for