-
Notifications
You must be signed in to change notification settings - Fork 28
07. Patterns
Patterns provide a way to interact with elements in pattern-specific ways. For example, you 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, TextPattern2, StylesPattern, SpreadsheetPattern, SpreadsheetItemPattern, TransformPattern2, TextChildPattern, DragPattern, DropTargetPattern, TextEditPattern, CustomNavigationPattern, SelectionPattern2
Ways of getting patterns from elements is described in the Elements section in this Wiki. Shortly put, one can use either use UIA_Element.GetCurrentPattern("pattern name or id") (such as element.GetCurrentPattern("Toggle")), or get patterns as properties (element.ValuePattern). For a more in-depth description, check out the Elements section.
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)
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()
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()
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.
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
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()
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 UIA_GridItemPattern interface.
Properties
- RowCount
- ColumnCount
Methods
- GetItem(row,column) where row and column are using 0-based indexing (0 = first row/column)
GridItemPattern provides access to a child control in a grid-style container that supports the UIA_GridPattern interface.
Properties
- ContainingGrid
- Row
- Column
- RowSpan
- ColumnSpan
Methods
GridItem doesn't have any methods.
TablePattern provides access to a control that acts as a container for a collection of child elements. The children of this element support UIA_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
TableItemPattern provides access to a child element in a container that supports UIA_TablePattern.
Properties
TableItem doesn't have any properties
Methods
- GetCurrentRowHeaderItems() returns an array of elements
- GetCurrentColumnHeaderItems() returns an array of elements
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)
- SetCurrentView(view)
- GetCurrentSupportedViews() returns an array of views
Views are control-specific, so use GetCurrentSupportedViews() to access the supported views, then use GetViewName to get the name of the view.
SelectionPattern provides access to a control that contains selectable child items. The children of this element support UIA_SelectionItemPattern.
Properties
- CanSelectMultiple
- IsSelectionRequired
Methods
- GetCurrentSelection() returns an array of elements
Properties
- FirstSelectedItem
- LastSelectedItem
- CurrentCurrentSelectedItem
- ItemCount
Methods
SelectionPattern2 doesn't have additional methods.
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()
WindowPattern provides access to the fundamental functionality of a window.
Properties
- CanMaximize
- CanMinimize
- IsModal
- IsTopmost
- WindowVisualState : one of UIA_Enum.WindowVisualState enums (Normal = 0, Maximized = 1, Minimized = 2)
- WindowInteractionState : one of UIA_Enum.WindowInteractionState enums (Running = 0, Closing = 1, ReadyForUserInteraction = 2, BlockedByModalWindow = 3, NotResponding = 4)
Methods
- Close()
- WaitForInputIdle(milliseconds)
- SetWindowVisualState(state) : state can be one of UIA_Enum.WindowVisualState enums (Normal = 0, Maximized = 1, Minimized = 2)
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 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 UIA_TextRange 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 extends TextPattern with additional methods. It can only be used if TextPattern2 is available.
Properties
TextPattern2 doesn't provide additional properties.
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.
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 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 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_TextAttributeId enum (available in UIA_Enum), and val the desired value (some can be strings, others text attribute enums such as 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 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 TextPatternRangeEndpoint enum (Start = 0, End = 1). unit needs to be a 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.
Properties
TextRange2 doesn't have additional properties.
Methods
- ShowContextMenu()
Properties
TextRange3 doesn't have additional properties.
Methods
- GetEnclosingElementBuildCache(cacheRequest)
- GetChildrenBuildCache(cacheRequest)
- GetAttributeValues(attributeIds, attributeIdCount) returns an array of attribute values