Skip to content

07. Patterns

Jump to bottom
Descolada edited this page Jan 9, 2023 · 2 revisions

Introduction

Patterns provide a way to interact with elements in pattern-specific ways. For example, use the InvokePattern for controls that can be invoked (such as buttons) and the ScrollPattern for controls that have scroll bars (such as list boxes, list views, or combo boxes). One element can have multiple patterns available, and child elements might not have the same patterns as the parent element.

In this article we have a non-exhaustive list of available patterns. More comprehensive information is available at Microsoft documentation and UIAutomationclient header.

Examples for patterns are Examples 9-16 in the Examples folder.

A list of patterns:

InvokePattern, SelectionPattern, ValuePattern, RangeValuePattern, ScrollPattern, ExpandCollapsePattern, GridPattern, GridItemPattern, MultipleViewPattern, WindowPattern, SelectionItemPattern, DockPattern, TablePattern, TableItemPattern, TextPattern, TogglePattern, TransformPattern, ScrollItemPattern, LegacyIAccessiblePattern, ItemContainerPattern, VirtualizedItemPattern, SynchronizedInputPattern, ObjectModelPattern, AnnotationPattern, StylesPattern, SpreadsheetPattern, SpreadsheetItemPattern, TextChildPattern, DragPattern, DropTargetPattern, TextEditPattern, CustomNavigationPattern

Accessing patterns

This UIA library tries to automatically detect which patterns are available for the element and then tries to access the property or method from that pattern automatically. This means that if, for example, the element is a CheckBox type element and has TogglePattern available (in Accessibility Insights or UIAViewer), then Element.Toggle() would automatically detect that it needs to use TogglePattern and calls that method from there.

In some cases this might fail: for example both LegacyIAccessiblePattern and SelectionItemPattern have the Select() method available, but if both patterns are supported then there is not way of knowing which one to use and one is chosen randomly. To force the use of a specific pattern, use Element.SomePattern to get the pattern object, and access the property/methodmethod from there: Element.SelectionItemPattern.Select() will use SelectionItemPattern to Select().

Value pattern

ValuePattern provides access to a control that contains a value that does not span a range and that can be represented as a string. This string may or may not be editable, depending on the control and its settings (SetValue might not be available).

Properties

  • Value: this can be used to both get and set the value.
  • IsReadOnly

Methods

  • SetValue(value) : equivalent to setting the value property with Element.Value := "test"

Invoke pattern

InvokePattern allows invoking the action of a control (typically a button). Usually Invoke is used if it initiates or performs a single, unambiguous action and does not maintain state when activated.

Properties

Invoke pattern doesn't have any properties

Methods

  • Invoke()

Toggle pattern

TogglePattern can be used to cycle through a set of states of a control, which usually is checking or unchecking a checkbox.

Properties

  • ToggleState: 0 = not toggled / not checked, 1 = toggled. ToggleState can also be used to set the toggle state to the desired value.

Methods

  • Toggle()

LegacyIAccessible pattern

LegacyIAccessiblePattern exposes the methods and properties of MSAA/Acc (the predecessor of UIA).

Properties

  • ChildId
  • Name
  • Value
  • Description
  • Role
  • State
  • Help
  • KeyboardShortcut
  • DefaultAction

Methods

  • Select(flags=3)

flags needs to be a combination of SELFLAG. The default is SELFLAG_TAKESELECTION and SELFLAG_TAKEFOCUS.

  • DoDefaultAction()
  • SetValue(value)
  • GetCurrentSelection()
  • GetIAccessible()

This method currently isn't working, but theoretically should return the Acc object.

Scroll pattern

ScrollPattern can be used to scroll an element.

Properties

  • HorizontalScrollPercent
  • VerticalScrollPercent
  • HorizontalViewSize
  • VerticalViewSize
  • HorizontallyScrollable
  • VerticallyScrollable

Methods

  • Scroll(horizontal=-1, vertical=-1)
  • SetScrollPercent(horizontal=-1, vertical=-1)

horizontal and vertical need to be one of UIA.ScrollAmount enumerations:

NoScroll = -1
LargeDecrement = 0
SmallDecrement = 1
NoAmount = 2
LargeIncrement = 3
SmallIncrement = 4

ScrollItem pattern

ScrollItemPattern can be used to scroll a subelement of a scrollable element (eg combobox item) into view.

Properties

ScrollItem doesn't have any properties.

Methods

  • ScrollIntoView()

Grid pattern

GridPattern provides access to a control that acts as a container for a collection of child controls that are organized in a two-dimensional logical coordinate system that can be traversed by row and column. The children of this element support the GridItemPattern interface.

Properties

  • RowCount
  • ColumnCount

Methods

  • GetItem(row,column) where row and column are using 0-based indexing (0 = first row/column)

GridItem pattern

GridItemPattern provides access to a child control in a grid-style container that supports the GridPattern interface.

Properties

  • ContainingGrid
  • Row
  • Column
  • RowSpan
  • ColumnSpan

Methods

GridItem doesn't have any methods.

Table pattern

TablePattern provides access to a control that acts as a container for a collection of child elements. The children of this element support TableItemPattern and are organized in a two-dimensional logical coordinate system that can be traversed by row and column.

Properties

  • RowOrColumnMajor

Methods

  • GetCurrentRowHeaders() returns an array of elements
  • GetCurrentColumnHeaders() returns an array of elements

TableItem pattern

TableItemPattern provides access to a child element in a container that supports TablePattern.

Properties

TableItem doesn't have any properties

Methods

  • GetCurrentRowHeaderItems() returns an array of elements
  • GetCurrentColumnHeaderItems() returns an array of elements

MultipleView pattern

MultipleViewPattern provides access to a control that can switch between multiple representations of the same information or set of child controls.

Properties

  • View

Methods

  • GetViewName(view)
  • SetView(view)
  • GetSupportedViews() returns an array of views

Views are control-specific, so use GetSupportedViews() to access the supported views, then use GetViewName to get the name of the view.

Selection pattern

SelectionPattern provides access to a control that contains selectable child items. The children of this element support SelectionItemPattern.

Properties

  • CanSelectMultiple
  • IsSelectionRequired

SelectionPattern2 Properties

  • FirstSelectedItem
  • LastSelectedItem
  • SelectedItem
  • ItemCount

Methods

  • GetSelection() returns an array of elements

SelectionItem pattern

SelectionItemPattern provides access to the selectable child items of a container control that supports UIA_SelectionPattern.

Properties

  • IsSelected
  • SelectionContainer returns an element

Methods

  • Select()
  • AddToSelection()
  • RemoveFromSelection()

Window pattern

WindowPattern provides access to the fundamental functionality of a window.

Properties

  • CanMaximize
  • CanMinimize
  • IsModal
  • IsTopmost
  • WindowVisualState : one of UIA.WindowVisualState values (Normal = 0, Maximized = 1, Minimized = 2)
  • WindowInteractionState : one of UIA.WindowInteractionState values (Running = 0, Closing = 1, ReadyForUserInteraction = 2, BlockedByModalWindow = 3, NotResponding = 4)

Methods

  • Close()
  • WaitForInputIdle(milliseconds)
  • SetWindowVisualState(state) : state can be one of UIA.WindowVisualState enums (Normal = 0, Maximized = 1, Minimized = 2)

Transform pattern

TransformPattern provides access to a control that can be moved, resized, or rotated.

Properties

  • CanMove
  • CanResize
  • CanRotate

Methods

  • Move(x, y)
  • Resize(w, h)
  • Rotate(degrees)

TextPattern and TextRange

TextPattern

TextPattern provides access to a control that contains text. TextPattern can't be used to change the text, for that you would need to use ValuePattern or AutoHotkeys Send functions.

Properties

  • DocumentRange returns a new TextRange object that encloses the main text of a document.
  • SupportedTextSelection

Methods

  • RangeFromPoint(x, y) retrieves an empty TextRange nearest to the specified screen coordinates
  • RangeFromChild(child) retrieves a TextRange enclosing a child element such as an image, hyperlink, Microsoft Excel spreadsheet, or other embedded object.
  • GetSelection() returns the currently selected text as an array of TextRanges
  • GetVisibleRanges() retrieves an array of disjoint text ranges from a text-based control where each text range represents a contiguous span of visible text

TextPattern2 methods

  • RangeFromAnnotation(annotation) returns a TextRange
  • GetCaretRange(ByRef isActive="") retrieves a zero-length text range at the location of the caret that belongs to the text-based control. isActive is set to True if the text-based control that contains the caret has keyboard focus, otherwise False.

TextRange

Properties

TextRange doesn't have any properties

Methods

  • Clone() returns a copy of the TextRange (retrieves a new UIA_TextRange identical to the original and inheriting all properties of the original).
  • Compare(comparisonTextRange) compares whether this TextRange has the same endpoints as comparisonTextRange
  • CompareEndPoints(srcEndPoint, comparisonTextRange, targetEndPoint) retrieves a value that specifies whether the start or end endpoint of this text range is the same as the start or end endpoint of comparisonTextRange. Returns a negative value if the caller's endpoint occurs earlier in the text than the target endpoint; 0 if the caller's endpoint is at the same location as the target endpoint; or a positive value if the caller's endpoint occurs later in the text than the target endpoint. srcEndPoint and targetEndPoint need to be UIA.TextPatternRangeEndpoint enums (Start = 0, End = 1).
  • ExpandToEnclosingUnit(unit:=6) normalizes the text range by the specified text unit. The range is expanded if it is smaller than the specified unit, or shortened if it is longer than the specified unit. unit needs to be a UIA.TextUnit enum (Character = 0, Format = 1, Word = 2, Line = 3, Paragraph = 4, Page = 5, default is Document = 6)
  • FindAttribute(attr, val, backward:=False) retrieves a text range subset that has the specified text attribute value. attr needs to be a UIA.TextAttribute enum, and val the desired value (some can be strings, others text attribute enums such as UIA.BulletStyle enum)
  • FindText(text, backward:=False, ignoreCase:=False) retrieves a text range subset that contains the specified text.
  • GetAttributeValue(attr) retrieves the value of the specified text attribute across the entire text range. attr needs to be a UIA_TextAttributeId enum.
  • GetBoundingRectangles() returns an array of bounding rectangle objects {x:top left X-coord,y:top left Y-coord,w:width,h:height} for each fully or partially visible line of text in a text range.
  • GetEnclosingElement() returns the innermost UI Automation element that encloses the text range.
  • GetText(maxLength=-1) returns the plain text of the text range. maxLength is the maximum length of the string to return, or -1 if no limit is required.
  • Move(unit, count) moves the text range forward or backward by the specified number of text units. unit needs to be a UIA.TextUnit enum (Character = 0, Format = 1, Word = 2, Line = 3, Paragraph = 4, Page = 5, default is Document = 6).
  • MoveEndpointByUnit(endpoint, unit, count) moves one endpoint of the text range the specified number of text units within the document range. endpoint needs to be UIA.TextPatternRangeEndpoint enum (Start = 0, End = 1). unit needs to be a UIA.TextUnit enum (Character = 0, Format = 1, Word = 2, Line = 3, Paragraph = 4, Page = 5, default is Document = 6).
  • MoveEndpointByRange(srcEndPoint, range, targetEndPoint) moves one endpoint of the current text range to the specified endpoint of a second text range. srcEndPoint and targetEndPoint need to be TextPatternRangeEndpoint enums.
  • Select() selects the span of text that corresponds to this text range, and removes any previous selection.
  • AddToSelection() adds the text range to the collection of selected text ranges in a control that supports multiple, disjoint spans of selected text.
  • RemoveFromSelection() removes the text range from an existing collection of selected text in a text container that supports multiple, disjoint selections.
  • ScrollIntoView(alignToTop) causes the text control to scroll until the text range is visible in the viewport. alignToTop is a boolean value.
  • GetChildren() returns an array of elements that fall within the text range.

TextRange2 methods

  • ShowContextMenu()

TextRange3 methods

  • GetEnclosingElementBuildCache(cacheRequest)
  • GetChildrenBuildCache(cacheRequest)
  • GetAttributeValues(attributeIds, attributeIdCount) returns an array of attribute values

Clone this wiki locally