JAWS UIA Script API

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.

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).

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

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).