Edit

UI Automation Control Patterns Overview

  • Article

A control pattern is an interface implementation that exposes a particular aspect of a control's functionality to Microsoft UI Automation client applications. Clients use the properties and methods exposed through a control pattern to retrieve information about a particular capability of the control, or to manipulate a particular aspect of the control's behavior. For example, a control that presents a tabular interface uses the Grid control pattern to expose the number of rows and columns in the table, and to enable a client to retrieve items from the table.

UI Automation uses control patterns to represent common control behaviors. For example, you use the Invoke control pattern for controls that can be invoked, such as buttons, and the Scroll control pattern for controls that have scroll bars, such as list boxes, list views, or combo boxes. Because each control pattern represents a separate functionality, control patterns can be combined to describe the full set of functionality supported by a particular control.

Note

An aggregate control is built with child controls that provide the user interface for functionality that is exposed by the parent, and the parent should implement all control patterns that are typically associated with its child controls. In turn, those same control patterns are not required to be implemented by the child controls.

 

This topic contains the following sections:

UI Automation Control Pattern Components

Control patterns support methods, properties, events, and relationships that are required to define a discrete piece of functionality available in a control.

  • The methods allow UI Automation clients to manipulate the control.
  • The properties and events provide information about the functionality and state of the control.
  • The relationship between a UI Automation element and its parent, children, and siblings describes the element structure in the UI Automation tree.

Control patterns relate to controls similar to the way interfaces relate to Component Object Model (COM) objects. In COM, you can query an object to ask what interfaces it supports, and then use those interfaces to access functionality. In UI Automation, clients can ask a control which control patterns it supports, and then interact with the control through the properties, methods, events, and structures exposed by the supported control patterns.

Control Patterns in Providers and Clients

UI Automation providers implement control pattern interfaces to expose the appropriate behavior for a specific piece of functionality that is supported by the control. These interfaces are not directly exposed to clients, but are used by the UI Automation core to implement another set of client interfaces. For example, a provider exposes scrolling functionality to UI Automation through IScrollProvider, and UI Automation exposes the functionality to clients through IUIAutomationScrollPattern.

Dynamic Control Patterns

Some controls do not always support the same set of control patterns. For example, a multiline edit control enables vertical scrolling only when it contains more lines of text than can be displayed in its viewable area. Scrolling is disabled when enough text is removed so that scrolling is no longer required. For this example, IUIAutomationScrollPattern is supported dynamically, depending on the how much text is in the edit box.

The following table describes the UI Automation control patterns. The table also lists the provider interfaces used to implement the control patterns, and the client interfaces used to access them.

Name Provider interface Client interface Description
Annotation IAnnotationProvider IUIAutomationAnnotationPattern Used to expose the properties of an annotation in a document, for example comments in the margin that are connected to document text.
Dock IDockProvider IUIAutomationDockPattern Used for controls that can be docked in a docking container, for example, toolbars or tool palettes.
Drag IDragProvider IUIAutomationDragPattern Used to support draggable controls, or controls with draggable items.
DropTarget IDropTargetProvider IUIAutomationDropTargetPattern Used to support controls that can be the target of a drag-and-drop operation.
ExpandCollapse IExpandCollapseProvider IUIAutomationExpandCollapsePattern Used for controls that can be expanded or collapsed, for example, menu items in an application, such as the File menu.
Grid IGridProvider IUIAutomationGridPattern Used for controls that support grid functionality, such as sizing and moving to a specified cell, for example, the large icon view in Windows Explorer or simple tables in Microsoft Office Word.
GridItem IGridItemProvider IUIAutomationGridItemPattern Used for controls that have cells in grids. The individual cells should support the GridItem pattern, for example, each cell in Windows Explorer detail view.
Invoke IInvokeProvider IUIAutomationInvokePattern Used for controls that can be invoked, such as buttons.
ItemContainer IItemContainerProvider IUIAutomationItemContainerPattern Used for controls that can contain other items.
LegacyIAccessible ILegacyIAccessibleProvider IUIAutomationLegacyIAccessiblePattern Used to expose Microsoft Active Accessibility properties and methods to UI Automation clients.
MultipleView IMultipleViewProvider IUIAutomationMultipleViewPattern Used for controls that can switch between multiple representations of the same set of information, data, or children, for example, a list-view control where data is available in thumbnail, tile, icon, list, or detail views.
ObjectModel IObjectModelProvider IUIAutomationObjectModelPattern Used to expose a pointer to the underlying object model of a document. This control pattern allows a client to navigate from a UI Automation element into the underlying object model.
RangeValue IRangeValueProvider IUIAutomationRangeValuePattern Used for controls that have a range of values. For example, a spinner control that displays years might have a range of 1900—2010, while a spinner control that displays months would have a range of 1—12.
Scroll IScrollProvider IUIAutomationScrollPattern Used for controls that can scroll when there is more information than can be displayed in the viewable area of the control.
ScrollItem IScrollItemProvider IUIAutomationScrollItemPattern Used for controls that have individual items in a list that scrolls, for example, a list control in a combo box control.
Selection ISelectionProvider IUIAutomationSelectionPattern Used for selection container controls, for example, list boxes and combo boxes.
SelectionItem ISelectionItemProvider IUIAutomationSelectionItemPattern Used for individual items in selection container controls, such as list boxes and combo boxes.
Spreadsheet ISpreadsheetProvider IUIAutomationSpreadsheetPattern Used to expose the contents of a spreadsheet or other grid-based document. Controls that implement the Spreadsheet control pattern should also implement the Grid control pattern.
SpreadsheetItem ISpreadsheetItemProvider IUIAutomationSpreadsheetItemPattern Used to expose the properties of a cell in a spreadsheet or other grid-based document. Controls that implement the SpreadsheetItem control pattern should also implement the GridItem control pattern.
Styles IStylesProvider IUIAutomationStylesPattern Used to describe a UI element that has a specific style, fill color, fill pattern, or shape.
SynchronizedInput ISynchronizedInputProvider IUIAutomationSynchronizedInputPattern Used for controls that accept keyboard or mouse input.
Table ITableProvider IUIAutomationTablePattern Used for controls that have a grid and header information.
TableItem ITableItemProvider IUIAutomationTableItemPattern Used for items in a table.
Text ITextProvider IUIAutomationTextPattern Used for edit controls and documents that expose textual information.
TextEdit ITextEditProvider IUIAutomationTextEditPattern Used for edit controls that modify text programmatically, for example a control that performs auto-correction or enables input composition.
TextChild ITextChildProvider IUIAutomationTextChildPattern Used to access an element’s nearest ancestor that supports the Text control pattern.
TextRange ITextRangeProvider IUIAutomationTextRange Used for retrieving textual content, text attributes, and embedded objects from text-based controls such as edit controls and documents.
Toggle IToggleProvider IUIAutomationTogglePattern Used for controls where the state can be toggled, for example, check boxes and checkable menu items.
Transform ITransformProvider IUIAutomationTransformPattern Used for controls that can be resized, moved, and rotated. Typical uses for the Transform control pattern are in designers, forms, graphical editors, and drawing applications.
Value IValueProvider IUIAutomationValuePattern Used for controls that have a value that does not lie within a specified range, for example, a date-time picker.
VirtualizedItem IVirtualizedItemProvider IUIAutomationVirtualizedItemPattern Used for controls that work with items in a virtual list.
Window IWindowProvider IUIAutomationWindowPattern Used for windows. Examples are top-level application windows, multiple-document interface (MDI) child windows, and dialog boxes.

 

Conceptual

Implementing UI Automation Control Patterns

Control Pattern Mapping for UI Automation Clients