Introduction
The JAWS UIA Script API provides access to Microsoft’s User Interface Automation (UIA) infrastructure via the JAWS script language. You can find detailed information about UIA on the Microsoft web site. This document describes the objects, methods, properties, and events available through the JAWS UIA Script API.
Supported Versions
With each version of Windows®, Microsoft extends the features provided by UI Automation. Many of the methods and properties described in this document are supported in Windows 7, most in Windows 8 and Windows 8.1, and all in Windows 10. Please consult the Microsoft documentation to find out which UIA interfaces, methods, and properties are supported in which versions of Windows.
All the objects, methods, properties, and events described in this document are available as of JAWS 18.0.2530.
Getting the FSUIA Object
The primary object in the JAWS UIA script API is FSUIA. Using this object, you can get other objects that represent UIA elements, get tree walkers which will allow you to traverse the tree of UIA elements, register for UIA events, and more.
To get an FSUIA object in scripts, use the JAWS built-in function CreateObjectEx as follows:
var object myObject = CreateObjectEx ("FreedomSci.UIA", false, "UIAScriptAPI.x.manifest" );
You can create as many FSUIA objects as you like, although you probably won’t need that many.
Properties
In the UIA Script API, all properties are get-only, except those for which “get/put” is explicitly declared in this document.
Caching
Those familiar with UIA will know that clients may request element and pattern data be cached in order to improve system performance. The JAWS UIA Script API handles UIA’s caching mechanism internally. Several of the most commonly requested element and pattern properties are requested to be cached; and the cached values are always checked before the uncached values. Using this approach should make most situations efficient while keeping the API as simple as possible.
The “Bool” Type
At present, the JAWS script language has no Boolean type. The term “bool” is used throughout the remainder of this document to indicate an integer value where zero (0) represents a Boolean value of false and any non-zero value represents a Boolean value of true.
The “Variant” Type
In the JAWS script language, a “variant” is a variable whose type is unknown at compile-time. Variants may be an int, string, handle, or object, and they can be used like any of these types. You can use the JAWS built-in script function GetVariantType to determine the type of a variant, although you may already know the underlying type based on the context. For example, if you request the name property of a UIA element and the return type is a variant, the underlying type will almost certainly be a string. If you happen to know the type of a given variant, you can declare the variable as the known type in the scripts. For example: if the GetProperty function returns a variant, but you know the type of the property returned will be a string, you can assign the return value directly to a string variable, rather than having to declare a variant. But even if you don’t know that a variant is a certain type like a string, you can still pass it to functions which take the string type.
Special Integer Types
There are several sets of pre-defined integer values used by UI Automation methods and properties. These represent various element types, property types, pattern identifiers, and so on. For JAWS scripters, these types are declared in the file UIA.jsh. In the file, each of the types listed below is preceded by a comment containing the name of the type in order to make them easy to reference from this document. These types are used to indicate the intended values of certain parameter, return, and property types from here on.
- AnnotationTypeID
- ControlTypeID
- DockPosition
- Endpoint
- EventID
- ExpandCollapseState
- LandmarkTypeID
- LegacySelectionFlags
- LiveSetting
- OrientationTypeID
- PropertyID
- RowOrColumnMajor
- ScrollAmountID
- StructureChangeTypeID
- StyleID
- SupportedTextSelectionID
- SynchronizedInputType
- TextAttributeID
- TextEditChangeType
- TextUnit
- ToggleState
- TreeScope
- WindowInteractionState
- WindowVisualState
- ZoomUnit
Parameters by Reference
When a parameter is passed to a function “by reference,” the value of the parameter is not only passed to the function, but also returned from the function. Therefore, after calling a function that takes a parameter by reference, the value of the parameter may have changed. This is a way of returning multiple pieces of information from a single function call. Throughout this document, the term “ByRef” is used to indicate those parameters which need to be passed to a function by reference.
In the JAWS script language, When a parameter is passed by reference, it must be done using a call to one of the reference functions: IntRef, StringRef, or IDispatchRef.
Note: this last function is used when the variable type is object. For example:
var int x;
var int y;
element.GetClickablePoint(IntRef(x), IntRef(y));
When this function returns, the values of x and y will be populated with the coordinates of the clickable point.
Arrays
The table below lists the types of arrays provided by the UIA Script API. Although the types of items contained in each array are different, all arrays behave the same way.
To get the number of items in an array, use its Count property, for instance, myArray.Count.
To access a specific item in an array by index, include the index in parentheses after the array name, for instance, myArray(5).
Note: Indexes are zero-based.
Finally, arrays may be used in ForEach loops as follows:
var string s;
ForEach s in myArray
; do something with s
EndForEach
Array |
Item type |
FSUIAElementArray |
FSUIAElement |
FSUIAIntArray |
int |
FSUIARectArray |
FSUIARect |
FSUIAStringArray |
string |
FSUIATextRangeArray |
FSUIATextRange |
Objects
FSUIA
Methods
Name |
Description |
bool AddAutomationEventHandler( EventID, FSUIAElement, TreeScope ); |
Registers a method that handles Microsoft UI Automation events. See the Events section of this document for further details. |
bool AddFocusChangedEventHandler(); |
Registers a method that handles focus-changed events. See the Events section of this document for further details. |
bool AddPropertyChangedEventHandler( PropertyID, FSUIAElement, TreeScope ); |
Registers a method that handles property-changed events.
See the Events section of this document for further details. |
bool AddStructureChangedEventHandler( FSUIAElement, TreeScope ); |
Registers a method that handles structure-changed events.
See the Events section of this document for further details. |
bool AddTextEditTextChangedEventHandler ( FSUIAElement, TreeScope, TextEditChangeType); |
Registers a method that handles programmatic text-edit events. See the Events section of this document for further details. |
bool CheckNotSupported(variant ); |
Checks a provided VARIANT to see if it contains the Not Supported identifier. |
bool CompareElements( FSUIAElement, FSUIAElement ); |
Compares two UI Automation elements to determine whether they represent the same underlying UI element. |
bool CompareRuntimeIds( FSUIAIntArray, FSUIAIntArray ); |
Compares two integer arrays containing run-time identifiers (IDs) to determine whether their content is the same and they belong to the same UI element. |
FSUIACondition CreateAndCondition( FSUIACondition, FSUIACondition ); |
Creates a condition that selects elements that match both of two conditions. |
FSUIACondition CreateBoolPropertyCondition( PropertyID, bool ); |
Creates a condition for a Boolean property. |
FSUIACondition CreateFalseCondition(); |
Creates a condition that is always false. |
FSUIACondition CreateIntPropertyCondition( PropertyID, int ); |
Creates a condition for an integer property. |
FSUIACondition CreateNotCondition( FSUIACondition ); |
Creates a condition that is the negative of a specified condition. |
FSUIACondition CreateOrCondition( FSUIACondition, FSUIACondition ); |
Creates a combination of two conditions where a match exists if either of the conditions is true. |
FSUIACondition CreateStringPropertyCondition( PropertyID, string ); |
Creates a condition for a string property. |
FSUIATreeWalker CreateTreeWalker( FSUIACondition ); |
Retrieves an IUIAutomationTreeWalker interface that can be used to traverse the UI Automation tree. Elements in the tree match the provided condition. |
FSUIACondition CreateTrueCondition(); |
Retrieves a predefined condition that selects all elements. |
FSUIAElement GetElementFromHandle( handle ); |
Retrieves a UI Automation element for the specified window. |
FSUIAElement GetElementFromIAccessible(object, int ); |
Retrieves a UI Automation element for the specified accessible object from a Microsoft Active Accessibility server. Parameter 2 is the MSAA child ID of the desired object. |
FSUIAElement GetElementFromPoint( int, int ); |
Retrieves the FSUIAElement interface for the UI element at the specified point on the desktop. Parameter 1 is the x coordinate of the point. Parameter 2 is the y coordinate. |
FSUIAElement GetFocusedElement(); |
Retrieves the UI Automation element that has the input focus. |
string GetPatternProgramaticName( PatternID ); |
Retrieves the registered programmatic name of a control pattern. |
string GetPropertyProgramaticName( PropertyID ); |
Retrieves the registered programmatic name of a property. |
FSUIAElement GetRootElement(); |
Retrieves the UI Automation element that represents the desktop. |
bool PollForPotentialSupportedPatterns( FSUIAElement, ByRef FSUIAIntArray, ByRef FSUIAStringArray ); |
Retrieves the control patterns that might be supported on a UI Automation element. Parameter 2 is an array of PatternIDs. Parameter 3 is an array of localized pattern name strings. |
bool PollForPotentialSupportedProperties( FSUIAElement, ByRef FSUIAIntArray, ByRef FSUIAStringArray ); |
Retrieves the properties that might be supported on a UI Automation element. Parameter 2 is an array of PropertyIDs. Parameter 3 is an array of localized property name strings. |
Properties
Type |
Name |
Description |
bool |
AutoSetFocus |
Specifies whether calls to UI Automation control pattern methods automatically set focus to the target element. (get/put) |
int |
ConnectionTimeout |
Specifies the length of time, in milliseconds, that UI Automation will wait for a provider to respond to a client request for an automation element. (get/put) |
FSUIACondition |
ContentViewCondition |
Retrieves a predefined condition object that selects content elements. |
FSUIATreeWalker |
ContentViewWalker |
Retrieves an IUIAutomationTreeWalker interface used to discover content elements. |
FSUIACondition |
ControlViewCondition |
Retrieves a predefined condition interface that selects control elements. |
FSUIATreeWalker |
ControlViewWalker |
Retrieves an IUIAutomationTreeWalker interface used to discover control elements. |
FSUIACondition |
RawViewCondition |
Retrieves a condition interface for a predefined condition that selects all UI elements in an unfiltered view. |
FSUIATreeWalker |
RawViewWalker |
Retrieves an IUIAutomationTreeWalker interface used to traverse an unfiltered view of the UI Automation tree. |
int |
TransactionTimeout |
Specifies the length of time, in Milliseconds, that UI Automation will wait for a provider to respond to a client request for information about an automation element. (get/put) |
FSUIAAnnotation
Properties
Type |
Name |
Description |
string |
Author |
Retrieves the name of the annotation author. |
string |
DateTime |
Retrieves the date and time that this annotation was created. |
FSUIAElement |
Target |
Retrieves the element that is being annotated. |
AnnotationTypeID |
TypeID |
Retrieves a value that identifies the annotation's type. |
string |
TypeName |
Retrieves the localized name of this annotation's type. |
FSUIACondition
The FSUIACondition object has no script-accessible members.
FSUIADock
Methods
Name |
Description |
bool SetPosition(DockPosition ); |
Sets the dock position of this element. |
Properties
Type |
Name |
Description |
DockPosition |
Position |
Retrieves the dock position of this element within its docking container. |
FSUIADrag
Methods
Name |
Description |
FSUIAElementArray GetGrabbedItems(); |
Retrieves a collection of elements that represent the full set of items that the user is dragging as part of a drag operation. |
Properties
Type |
Name |
Description |
string |
DropEffect |
Retrieves a localized string that indicates what happens when the user drops this element as part of a drag-drop operation. |
FSUIAStringArray |
DropEffects |
Retrieves an array of localized strings that enumerate the full set of effects that can happen when this element as part of a drag-and-drop operation. |
bool |
IsGrabbed |
Indicates whether the user has grabbed this element as part of a drag-and-drop operation. |
FSUIADropTarget
Properties
Type |
Name |
Description |
string |
Effect |
Retrieves a localized string that describes what happens when the user drops the grabbed element on this drop target. |
FSUIAStringArray |
Effects |
Retrieves an array of localized strings that enumerate the full set of effects that can happen when the user drops a grabbed element on this drop target as part of a drag-and-drop operation. |
FSUIAElement
Methods
Name |
Description |
FSUIAElement BuildUpdatedCache(); |
Retrieves a new FSUIAElement interface with an updated cache. |
FSUIAElementArray FindAll( TreeScope, FSUIACondition ); |
Returns all UI Automation elements that satisfy the specified condition. |
FSUIAElement FindFirst( TreeScope, FSUIACondition ); |
Retrieves the first child or descendant element that matches the specified condition. |
FSUIAAnnotation GetAnnotationPattern(); |
Returns a pattern object if the pattern is available. |
bool GetClickablePoint( ByRef int, ByRef int ); |
Retrieves a point on the element that can be clicked. The first parameter is the x coordinate. The second parameter is the y coordinate. |
FSUIADock GetDockPattern(); |
Returns a pattern object if the pattern is available. |
FSUIADrag GetDragPattern(); |
Returns a pattern object if the pattern is available. |
FSUIADropTarget GetDropTargetPattern(); |
Returns a pattern object if the pattern is available. |
FSUIAExpandCollapse GetExpandCollapsePattern(); |
Returns a pattern object if the pattern is available. |
FSUIAGridItem GetGridItemPattern(); |
Returns a pattern object if the pattern is available. |
FSUIAGrid GetGridPattern(); |
Returns a pattern object if the pattern is available. |
FSUIAInvoke GetInvokePattern(); |
Returns a pattern object if the pattern is available. |
FSUIAItemContainer GetItemContainerPattern(); |
Returns a pattern object if the pattern is available. |
FSUIALegacyIAccessible GetLegacyIAccessiblePattern(); |
Returns a pattern object if the pattern is available. |
FSUIAMultipleView GetMultipleViewPattern(); |
Returns a pattern object if the pattern is available. |
variant GetPropertyValue(PropertyID ); |
Retrieves the value of a property for this UI Automation element. |
FSUIARangeValue GetRangeValuePattern(); |
Returns a pattern object if the pattern is available. |
FSUIAIntArray GetRuntimeID(); |
Retrieves the unique identifier assigned to the UI element. |
FSUIAScrollItem GetScrollItemPattern(); |
Returns a pattern object if the pattern is available. |
FSUIAScroll GetScrollPattern(); |
Returns a pattern object if the pattern is available. |
FSUIASelectionItem GetSelectionItemPattern(); |
Returns a pattern object if the pattern is available. |
FSUIASelection GetSelectionPattern(); |
Returns a pattern object if the pattern is available. |
FSUIASpreadsheetItem GetSpreadsheetItemPattern(); |
Returns a pattern object if the pattern is available. |
FSUIASpreadsheet GetSpreadsheetPattern(); |
Returns a pattern object if the pattern is available. |
FSUIAStyles GetStylesPattern(); |
Returns a pattern object if the pattern is available. |
FSUIASynchronizedInput GetSynchronizedInputPattern(); |
Returns a pattern object if the pattern is available. |
FSUIATableItem GetTableItemPattern(); |
Returns a pattern object if the pattern is available. |
FSUIATable GetTablePattern(); |
Returns a pattern object if the pattern is available. |
FSUIATextChild GetTextChildPattern(); |
Returns a pattern object if the pattern is available. |
FSUIATextEdit GetTextEditPattern(); |
Returns a pattern object if the pattern is available. |
FSUIAText GetTextPattern(); |
Returns a pattern object if the pattern is available. |
FSUIAToggle GetTogglePattern(); |
Returns a pattern object if the pattern is available. |
FSUIATransform GetTransformPattern(); |
Returns a pattern object if the pattern is available. |
FSUIAValue GetValuePattern(); |
Returns a pattern object if the pattern is available. |
FSUIAVirtualizedItem GetVirtualizedItemPattern(); |
Returns a pattern object if the pattern is available. |
FSUIAWindow GetWindowPattern(); |
Returns a pattern object if the pattern is available. |
bool SetFocus(); |
Sets the keyboard focus to this UI Automation element. |
bool ShowContextMenu(); |
Programmatically invokes a context menu on the target element. |
Properties
Type |
Name |
Description |
string |
AcceleratorKey |
Retrieves the accelerator key for the element. |
string |
AccessKey |
Retrieves the access key character for the element. |
FSUIAElementArray |
Annotation Objects |
Retrieves an array of elements representing the annotations associated with this element. |
FSUIAIntArray |
Annotation Types |
Retrieves an array of annotation type identifiers indicating the types of annotations that are associated with this element. |
string |
AriaProperties |
Retrieves the value of the ARIA properties of the element. |
string |
AriaRole |
Retrieves the ARIA role of the element. |
string |
AutomationId |
Retrieves the UI Automation identifier of the element. |
FSUIARect |
BoundingRectangle |
Retrieves the coordinates of the rectangle that completely encloses the element. |
string |
ClassName |
Retrieves the class name of the element. |
FSUIAElementArray |
ControllerFor |
Retrieves an array of elements for which this element serves as the controller. |
int |
ControlType |
Retrieves the control type of the element. |
int |
Culture |
Retrieves the culture identifier for the element. |
FSUIAElementArray |
DescribedBy |
Retrieves an array of elements that describe this element. |
FSUIAElementArray |
FlowsFrom |
Retrieves an array of elements that indicates the reading order before the current element. |
FSUIAElementArray |
FlowsTo |
Retrieves an array of elements whose order suggests the reading order after the current element. |
string |
FrameworkID |
Retrieves the name of the underlying UI framework. |
string |
FullDescription |
Returns a localized string which can contain extended description text for an element. |
bool |
HasKeyboardFocus |
Retrieves a value that indicates whether the element has keyboard focus. |
string |
HelpText |
Retrieves the help text for the element. |
bool |
IsContentElement |
Retrieves a value that indicates whether the element is a content element. |
bool |
IsControlElement |
Retrieves a value indicating whether the UI element is a control. |
bool |
IsDataValidForForm |
Retrieves a value that indicates whether the element contains valid data for the form. |
bool |
IsEnabled |
Retrieves a value that indicates whether the UI Automation element is enabled. |
bool |
IsKeyboardFocusable |
Retrieves a value that indicates whether the UI Automation element can accept keyboard focus. |
bool |
IsOffscreen |
Retrieves a value that indicates whether the element is off screen. |
bool |
IsPassword |
Retrieves a value that indicates whether the element contains a disguised password. |
bool |
IsPeripheral |
Retrieves the peripheral UI indicator for the element. |
bool |
IsRequiredForForm |
Retrieves a value that indicates whether the element is required to be filled out on a form. |
string |
ItemStatus |
Retrieves a description of the status of an item within an element. |
string |
ItemType |
Retrieves a string describing the type of the item represented by a UI element. |
FSUIAElement |
LabeledBy |
Retrieves the element that contains the text label for this element. |
LandmarkTypeID |
LandmarkType |
Returns the landmark type identifier associated with an element. |
int |
Level |
Returns the 1-based integer for the level in the hierarchical or broken hierarchical structure for the element. |
LiveSetting |
LiveSetting |
Indicates the type of notifications, if any, that the element sends when the content of the element changes. |
string |
LocalizedControlType |
Retrieves a localized description of the UI element's control type. |
string |
LocalizedLandmarkType |
Returns a text string describing the type of landmark that the element represents. |
string |
Name |
Retrieves the name of the UI element. |
handle |
NativeWindowHandle |
Retrieves the window handle of the element. |
bool |
OptimizeForVisualContent |
Indicates whether the provider exposes only elements that are visible. |
OrientationTypeID |
Orientation |
Retrieves the orientation of the element. |
int |
PositionInSet |
Returns the 1-based integer for the ordinal position in the set for the element. |
int |
ProcessId |
Retrieves the ID of the process that hosts the element. |
string |
ProviderDescription |
Retrieves a description of the UI Automation provider for this element. |
int |
SizeOfSet |
Returns the 1-based integer for the size of the set where the element is located. |
FSUIAExpandCollapse
Methods
Name |
Description |
void Collapse(); |
Hides all child nodes, controls, or content of the element. |
void Expand(); |
Displays all child nodes, controls, or content of the element. |
Properties
Type |
Name |
Description |
ExpandCollapseState |
ExpandCollapseState |
Retrieves a value that indicates the state, expanded or collapsed, of the element. |
FSUIAGrid
Methods
Name |
Description |
FSUIAElement GetItem( int, int ); |
Retrieves a UI Automation element representing an item in the grid. Parameter 1 is the zero-based index of a row, Parameter 2 is the zero-based index of a column. |
Properties
Type |
Name |
Description |
int |
ColumnCount |
The number of columns in the grid. |
int |
RowCount |
Retrieves the number of rows in the grid. |
FSUIAGridItem
Properties
Type |
Name |
Description |
int |
Column |
Retrieves the zero-based index of the column that contains the item. |
int |
ColumnSpan |
Retrieves the number of columns spanned by the grid item. |
FSUIAElement |
ContainingGrid |
Retrieves the element that contains the grid item. |
int |
Row |
Retrieves the zero-based index of the row that contains the grid item. |
int |
RowSpan |
Retrieves the number of rows spanned by the grid item. |
FSUIAInvoke
Methods
Name |
Description |
bool Invoke(); |
Invokes the action of a control, such as a button click. |
FSUIAItemContainer
Methods
Name |
Description |
FSUIAElement FindItemByProperty( FSUIAElement, PropertyID, variant ); |
Retrieves an element within a containing element, based on a specified property value. |
FSUIALegacyIAccessible
Methods
Name |
Description |
void DoDefaultAction(); |
Performs the Microsoft Active Accessibility default action for the element. |
object GetIAccessible(); |
Retrieves an IAccessible object that corresponds to the UI Automation element. |
FSUIAElementArray GetSelection(); |
Retrieves the Microsoft Active Accessibility property that identifies the selected children of this element. |
bool Select(LegacySelectionFlags ); |
Performs a Microsoft Active Accessibility selection. |
bool SetValue( string ); |
Sets the Microsoft Active Accessibility value property for the element. |
Properties
Type |
Name |
Description |
int |
ChildID |
Retrieves the Microsoft Active Accessibility child identifier for the element. |
string |
DefaultAction |
Retrieves the Microsoft Active Accessibility default action for the element. |
string |
Description |
Retrieves the Microsoft Active Accessibility description of the element. |
string |
Help |
Retrieves the Microsoft Active Accessibility help string for the element. |
string |
KeyboardShortcut |
Retrieves the Microsoft Active Accessibility keyboard shortcut property for the element. |
string |
Name |
Retrieves the Microsoft Active Accessibility name property of the element. |
int |
Role |
Retrieves the Microsoft Active Accessibility role identifier of the element. |
int |
State |
Retrieves the Microsoft Active Accessibility state identifier for the element. |
string |
Value |
Retrieves the Microsoft Active Accessibility value property. |
FSUIAMultipleView
Methods
Name |
Description |
FSUIAIntArray GetSupportedViews(); |
Retrieves a collection of control-specific view identifiers. |
string GetViewName( int ); |
Retrieves the name of a control-specific view. |
bool SetCurrentView( int ); |
Sets the view of the control. |
Properties
Type |
Name |
Description |
int |
CurrentView |
Retrieves the control-specific identifier of the current view of the control. |
FSUIARangeValue
Methods
Name |
Description |
bool SetValue( int ); |
Sets the value of the control. |
Properties
Type |
Name |
Description |
bool |
IsReadOnly |
Indicates whether the value of the element can be changed. |
int |
LargeChange |
Retrieves the value that is added to or subtracted from the value of the control when a large change is made, such as when the PAGE DOWN key is pressed. |
int |
Maximum |
Retrieves the maximum value of the control. |
int |
Minimum |
Retrieves the minimum value of the control. |
int |
SmallChange |
Retrieves the value that is added to or subtracted from the value of the control when a small change is made, such as when an ARROW key is pressed. |
int |
Value |
Retrieves the value of the control. |
FSUIARect
Properties
Type |
Name |
Description |
int |
Bottom |
The bottom edge of the rectangle. |
int |
Left |
The left edge of the rectangle. |
int |
Right |
The right edge of the rectangle. |
int |
Top |
The top edge of the rectangle. |
FSUIAScroll
Methods
Name |
Description |
bool Scroll(ScrollAmountID, ScrollAmountID ); |
Scrolls the visible region of the content area horizontally and vertically. Parameter 1 is horizontal. Parameter 2 is vertical. |
bool SetScrollPercent( int, int ); |
Sets the horizontal and vertical scroll positions as a percentage of the total content area within the UI Automation element. Parameter 1 is horizontal. Parameter 2 is vertical. |
Properties
Type |
Name |
Description |
bool |
HorizontallyScrollable |
Indicates whether the element can scroll horizontally. |
int |
HorizontalScrollPercent |
Retrieves the horizontal scroll position. |
int |
HorizontalViewSize |
Retrieves the horizontal size of the viewable region of a scrollable element, expressed as a percentage of the total content area within the element. |
bool |
VerticallyScrollable |
Indicates whether the element can scroll vertically. |
int |
VerticalScrollPercent |
Retrieves the vertical scroll position. |
int |
VerticalViewSize |
Retrieves the vertical size of the viewable region of a scrollable element, expressed as a percentage of the total content area within the element. |
FSUIAScrollItem
Methods
Name |
Description |
void ScrollIntoView(); |
Scrolls the content area of a container object to display the UI Automation element within the visible region (viewport) of the container. |
FSUIASelection
Methods
Name |
Description |
FSUIAElementArray GetSelection(); |
Retrieves the selected elements in the container. |
Properties
Type |
Name |
Description |
bool |
CanSelectMultiple |
Indicates whether more than one item in the container can be selected at one time. |
bool |
IsSelectionRequired |
Indicates whether at least one item must be selected at all times. |
FSUIASelectionItem
Methods
Name |
Description |
bool AddToSelection(); |
Adds the current element to the collection of selected items. |
bool RemoveFromSelection(); |
Removes this element from the selection. |
void Select(); |
Clears any selected items and then selects the current element. |
Properties
Type |
Name |
Description |
bool |
IsSelected |
Indicates whether this item is selected. |
FSUIAElement |
SelectionContainer |
Retrieves the element that supports IUIAutomationSelectionPattern and acts as the container for this item. |
FSUIASpreadsheet
Methods
Name |
Description |
FSUIAElement GetItemByName( string ); |
Retrieves a UI Automation element that represents the spreadsheet cell that has the specified name, for instance, “A1”. |
FSUIASpreadsheetItem
Methods
Name |
Description |
FSUIAElementArray GetAnnotationObjects(); |
Retrieves an array of elements representing the annotations associated with this spreadsheet cell. |
FSUIAIntArray GetAnnotationTypes(); |
Retrieves an array of annotation type identifiers indicating the types of annotations that are associated with this spreadsheet cell. |
Properties
Type |
Name |
Description |
string |
Formula |
Retrieves the formula for this cell. |
FSUIAStyles
Properties
Type |
Name |
Description |
string |
ExtendedProperties |
Retrieves a localized string that contains the list of extended properties for an element in a document. |
int |
FillColor |
Retrieves the fill color of an element in a document. |
int |
FillPatternColor |
Retrieves the color of the pattern used to fill an element in a document. |
string |
Shape |
Retrieves the shape of an element in a document. |
StyleID |
StyleID |
Retrieves the identifier of the visual style associated with an element in a document. |
string |
StyleName |
Retrieves the name of the visual style associated with an element in a document. |
FSUIASynchronizedInput
Methods
Name |
Description |
bool Cancel(); |
Causes the UI Automation provider to stop listening for mouse or keyboard input. |
bool StartListening(SynchronizedInputType ); |
Causes the UI Automation provider to start listening for mouse or keyboard input. |
FSUIATable
Methods
Name |
Description |
FSUIAElementArray GetColumnHeaders(); |
Retrieves a collection of UI Automation elements representing all the column headers in a table. |
FSUIAElementArray GetRowHeaders(); |
Retrieves a collection of UI Automation elements representing all the row headers in a table. |
Properties
Type |
Name |
Description |
RowOrColumnMajor |
RowOrColumnMajor |
Retrieves the primary direction of traversal for the table. |
FSUIATableItem
Methods
Name |
Description |
FSUIAElementArray GetColumnHeaderItems(); |
Retrieves the column headers associated with a table item or cell. |
FSUIAElementArray GetRowHeaderItems(); |
Retrieves the row headers associated with a table item or cell. |
FSUIAText
Methods
Name |
Description |
FSUIATextRange GetCaretRange( ByRef int ); |
Retrieves a zero-length text range at the location of the caret that belongs to the text-based control. Parameter 1 is a reference to an int that indicates whether the text-based control that contains the caret has keyboard focus; 0 is false, otherwise true. |
FSUIATextRangeArray GetSelection(); |
Retrieves a collection of text ranges that represents the currently selected text in a text-based control. |
FSUIATextRangeArray GetVisibleRanges(); |
Retrieves an array of disjoint text ranges from a text-based control where each text range represents a contiguous span of visible text. |
FSUIATextRange RangeFromAnnotation( FSUIAElement ); |
Retrieves a text range containing the text that is the target of the annotation associated with the specified annotation element. |
FSUIATextRange RangeFromChild( FSUIAElement ); |
Retrieves a text range enclosing a child element such as an image, hyperlink, Microsoft Excel spreadsheet, or other embedded object. |
FSUIATextRange RangeFromPoint( int, int ); |
Retrieves the degenerate (empty) text range nearest to the specified screen coordinates. Parameter 1 is the x coordinate. Parameter 2 is the y coordinate. |
Properties
Type |
Name |
Description |
FSUIATextRange |
DocumentRange |
Retrieves a text range that encloses the main text of a document. |
SupportedTextSelectionID |
SupportedTextSelection |
Retrieves a value that specifies the type of text selection that is supported by the control. |
FSUIATextChild
Properties
Type |
Name |
Description |
FSUIAElement |
TextContainer |
Retrieves this element's nearest ancestor element that supports the Text control pattern. |
FSUIATextRange |
TextRange |
Retrieves a text range that encloses this child element. |
FSUIATextEdit
Methods
Name |
Description |
FSUIAElement GetActiveComposition(); |
Returns the active composition. |
FSUIATextRange GetConversionTarget(); |
Returns the current conversion target range. |
FSUIATextRange
Methods
Name |
Description |
bool AddToSelection(); |
Adds the text range to the collection of selected text ranges in a control that supports multiple, disjoint spans of selected text. |
FSUIATextRange Clone(); |
Retrieves a new IUIAutomationTextRange identical to the original and inheriting all properties of the original. |
bool Compare( FSUIATextRange ); |
Retrieves a value that specifies whether this text range has the same endpoints as another text range. |
int CompareEndPoints( Endpoint, FSUIATextRange, Endpoint ); |
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 another text range. |
bool ExpandToEnclosingUnit( TextUnit ); |
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. |
FSUIATextRange FindAttribute( TextAttributeID, variant, bool ); |
Retrieves a text range subset that has the specified text attribute value. Parameter 3 should be set to true if the search is to be done backward; otherwise false. |
FSUIATextRange FindText( string, bool, bool ); |
Retrieves a text range subset that contains the specified text. Parameter 2 should be set to true if the search is to be done backward; otherwise false. Parameter 3 should be set to true if the search is to be case-insensitive; otherwise false. |
variant GetAttributeValue( TextAttributeID ); |
Retrieves the value of the specified text attribute across the entire text range. |
FSUIARectArray GetBoundingRectangles(); |
Retrieves a collection of bounding rectangles for each fully or partially visible line of text in a text range. |
FSUIAElementArray GetChildren(); |
Retrieves a collection of all embedded objects that fall within the text range. |
FSUIAElement GetEnclosingElement(); |
Returns the innermost UI Automation element that encloses the text range. |
string GetText( int ); |
Returns the plain text of the text range. Parameter 2 is the maximum length in characters of the text to retrieve. |
int Move( TextUnit, int ); |
Moves the text range forward or backward by the specified number of text units. Negative values for parameter 2 will move the range backward. Returns the number of units actually moved. |
bool MoveEndpointByRange( Endpoint, FSUIATextRange, Endpoint ); |
Moves one endpoint of the current text range to the specified endpoint of a second text range. |
int MoveEndpointByUnit( Endpoint, TextUnit, int ); |
Moves one endpoint of the text range the specified number of text units within the document range. Negative values for parameter 3 will move the range backward. Returns the number of units actually moved. |
bool RemoveFromSelection(); |
Removes the text range from an existing collection of selected text in a text container that supports multiple, disjoint selections. |
bool ScrollIntoView( bool ); |
Causes the text control to scroll until the text range is visible in the viewport. Parameter 1 should be true if the text control should be scrolled so that the text range is flush with the top of the viewport; false if it should be flush with the bottom of the viewport. |
bool Select(); |
Selects the span of text that corresponds to this text range, and removes any previous selection. |
bool ShowContextMenu(); |
Programmatically invokes a context menu on the target element. |
FSUIAToggle
Methods
Name |
Description |
void Toggle(); |
Cycles through the toggle states of the control. |
Properties
Type |
Name |
Description |
ToggleState |
ToggleState |
Retrieves the toggled state of the control. |
FSUIATransform
Methods
Name |
Description |
bool Move( int, int ); |
Moves the UI Automation element. Parameter 1 is the screen coordinates of the left side of the control. Parameter 2 is the screen coordinates of the top of the control. |
bool Resize( int, int ); |
Resizes the UI Automation element. Parameter 1 is the new width of the window, in pixels. Parameter 2 is the new height of the window, in pixels. |
bool Rotate( int ); |
Rotates the UI Automation element. Parameter 1 is the number of degrees to rotate the element. A positive number rotates clockwise; a negative number rotates counterclockwise. |
bool Zoom( int ); |
Zooms the viewport of the control. Parameter 1 is the amount to zoom the viewport, specified as a percentage. Positive values increase the zoom level, and negative values decrease it. The control zooms its viewport to the nearest supported value. |
bool ZoomByUnit(ZoomUnit ); |
Zooms the viewport of the control by the specified unit. |
Properties
Type |
Name |
Description |
bool |
CanMove |
Indicates whether the element can be moved. |
bool |
CanResize |
Indicates whether the element can be moved. |
bool |
CanRotate |
Indicates whether the element can be rotated. |
bool |
CanZoom |
Indicates whether the control supports zooming of its viewport. |
int |
ZoomLevel |
Retrieves the zoom level of the control's viewport. |
int |
ZoomMaximum |
Retrieves the maximum zoom level of the control's viewport. |
int |
ZoomMinimum |
Retrieves the minimum zoom level of the control's viewport. |
FSUIATreeWalker
Methods
Name |
Description |
bool GoToFirstChild(); |
Moves the current element to its first child. Returns true if the move succeeded. Otherwise false. |
bool GoToNextSibling(); |
Moves the current element to its next sibling. Returns true if the move succeeded. Otherwise false. |
bool GoToParent(); |
Moves the current element to its parent. Returns true if the move succeeded. Otherwise false. |
bool GoToPriorSibling(); |
Moves the current element to its prior sibling. Returns true if the move succeeded. Otherwise false. |
Properties
Type |
Name |
Description |
FSUIACondition |
Condition |
Retrieves the condition that specifies items to walk in the tree. |
FSUIAElement |
CurrentElement |
An element in the UIA tree. (get/put) |
FSUIAValue
Methods
Name |
Description |
bool SetValue( string ); |
Sets the value of an element. |
Properties
Type |
Name |
Description |
bool |
IsReadOnly |
Indicates whether the value of the element is read-only. |
string |
Value |
Retrieves the value of the element. |
FSUIAVirtualizedItem
Methods
Name |
Description |
bool Realize(); |
Creates a full UI Automation element for a virtualized item. |
FSUIAWindow
Methods
Name |
Description |
bool Close(); |
Closes the window. |
bool SetWindowVisualState(WindowVisualState ); |
Minimizes, maximizes, or restores the window. |
bool WaitForInputIdle( int ); |
Causes the calling code to block for the specified time or until the associated process enters an idle state, whichever completes first. |
Properties
Type |
Name |
Description |
bool |
CanMaximize |
Indicates whether the window can be maximized. |
bool |
CanMinimize |
Indicates whether the window can be minimized. |
WindowInteractionState |
InteractionState |
Retrieves the current state of the window for the purposes of user interaction. |
bool |
IsModal |
Indicates whether the window is modal. |
bool |
IsTopmost |
Indicates whether the window is the topmost element in the z-order. |
WindowVisualState |
VisualState |
Retrieves the visual state of the window; that is, whether it is in the normal, maximized, or minimized state. |
Events
Scripts may register to receive UIA events by calling one of the add-event-handler methods on an FSUIA object.
Begin example
var object events = CreateObjectEx ("FreedomSci.UIA", false, "UIAScriptAPI.x.manifest" );
var object element = events.GetFocusedElement();
events.AddPropertyChangedEventHandler(UIA_NamePropertyId, element, TreeScope_Element | TreeScope_Descendants )
End example
The same FSUIA object must then be passed to the JAWS built-in function ComAttachEvents.
Note the second parameter below. This string will be prepended to the event callback function in the scripts.
Begin example
ComAttachEvents( events, “UIA_” );
EndExample
Now, when a UIA property changed event occurs for the name property, the function UIA_PropertyChangedEvent in the JAWS scripts will be called.
Finally, to stop receiving events, the FSUIA object must be set to a null object.
Begin example
var object nullObject;
events = nullObject;
End example
Note: In the examples above, the FSUIA object named events would typically be declared as a global variable. If it were declared inside a function, when the function ended, the object would automatically be set to null, and any previously registered events would be unregistered before JAWS ever had a chance to receive them.
Event callback functions
The following table gives the names and parameter types of the available event callback functions.
Name |
Description |
AutomationEvent( FSUIAElement, EventID ); |
The automation event callback. Parameter 1 is the element for which the event occurred. Parameter 2 is the EventID. |
FocusChangedEvent(FSUIAElement ); |
The focus changed event callback. Parameter 1 is the new element with focus. |
PropertyChangedEvent( FSUIAElement, PropertyID, variant ); |
The property changed event callback. Parameter 1 is the element for which the event occurred. Parameter 2 is the property ID for the property that changed. Parameter 3 is the new value for the specified property. |
StructureChangedEvent( FSUIAElement, StructureChangeTypeID, FSUIAIntArray ); |
The structure changed event callback. Parameter 1 is the element for which the event occurred. Parameter 2 is the type of structure change. Parameter 3 is the runtime ID of the element that changes. Parameter 3 is only valid when the StructureTypeID in parameter 2 is StructureChangeType_ChildRemoved. |
TextEditTextChangedEvent(FSUIAElement, TextEditChangeType, FSUIAStringArray); |
The text edit changed event callback. Parameter 1 is the element for which the event occurred. Parameter 2 is the type of text-edit change that occurred. Parameter 3 is the event data passed by the event. Parameter 3 contains different payloads for each text-edit change type. For the TextEditChangeType_AutoCorrect, the data is the new corrected string. For the TextEditChangeType_Composition, the data is the updated string in the composition (only the part that changed). For the TextEditChangeType_CompositionFinalized, the data is the finalized string of the completed composition (this may be empty if composition was canceled or deleted). |