UiNode

What is UiNode object?

UiNode has been designed with the goal to allow an app to programmatically manipulate user interface objects belonging to other apps. While UI objects come in many flavors from many frameworks (just to name a few: win32, java, WPF, silverlight, flash) UiNode aims to be a uniform and simple UI automation and scraping interface to the myriad of UI objects you see on your screen.

Constants

UiClickType

Enumeration type that specifies the type of mouse click in Click method.

UI_CLICK_SINGLE = 0 - single click action is performed
UI_CLICK_DOUBLE = 1 - double click action is performed

UiFindScope

UiFindScope enumeration type specifies the search scope of FindAll and FindFirst methods.

UI_FIND_CHILDREN    = 0 - only direct children of the current node are taken into account
UI_FIND_DESCENDANTS = 1 - all descendants are considered
UI_FIND_TOP_LEVELS  = 2 - search for top level windows only

UiInputMethod

UiInputMethod enumeration specifies how Click, Hover and WriteText methods simulate keyboard and mouse events.

UI_HARDWARE_EVENTS = 0 - keystrokes and mouse events are synthesized by SendInput function
UI_WIN32_MSG       = 1 - WM_LBUTTONDOWN, WM_LBUTTONUP and WM_CHAR Win32 messages are used
UI_CONTROL_API     = 2 - the underlying technology of the node is used to generate events (like Active Accessibility,
                     Java Accessibility Bridge, HTML events)

UiMouseButton

UiMouseButton enumeration type specifies the mouse button in Click method.

UI_BTN_LEFT   = 0 - left mouse button is clicked
UI_BTN_RIGHT  = 1 - right mouse button is clicked
UI_BTN_MIDDLE = 2 - middle mouse button is clicked

UiSelectionType

UiSelectionType enumeration specifies the type of selection in SelectInteractive method.

UI_SELECT_NODE   = 0 - select a user interface object.
UI_SELECT_REGION = 1 - select a rectangular region from which a UI object is inferred

UiWaitForReadyLevels

UiWaitForReadyLevels enumeration specifies the wait for ready level for WaitForReady method and waitForReadyLevel property.

UI_WFR_NONE        = 0 - no wait at all
UI_WFR_INTERACTIVE = 1 - wait the node to become interactive
UI_WFR_COMPLETE    = 2 - wait the node to be completely available.

Methods

Click

UiNode Click(int dx, int dy, UiClickType clickType, UiMouseButtons mouseBtn, UiInputMethod inputMethod)

Simulates a click on the current UI object.

Parameters

dx          - horizontal displacement of the click position
dy          - vertical displacement of the click position
clickType   - single or double click (see: UiClickType)
mouseBtn    - left, middle or right click (see: UiMouseButtons)
inputMethod - hardware events, Win32 messages or node-dependent (see: UiInputMethod)

Return

the current node making method chaining possible.

Errors

E_UINODE_INVALID_CLICK_BTN and E_UINODE_INVALID_CLICK_MODE are raised for invalid clickType and mouseBtn input parameters.
E_UINODE_CLICK_ACTION_ERR is raised if the combination of clickType + mouseBtn is not supported by the current UI object.
E_UINODE_CLICK_GENERIC_ERR is raised when Click fails due to unknown errors in the underlying
automation technology (like Active Accessibility, Java Accessibility Bridge, HTML events).

Remarks

dx and dy are relative to clippingRegion or to top-left corner of the UI object if no clippingRegion is set.
If the current node represents the desktop or is uninitialized then dx and dy are in screen coordinates.

DragAndDrop

void DragAndDrop(int x, int y, UiNode targetNode, int targetX, int targetY)

Simulates drag and drop action from current UI object to targetNode UI object. This method is not yet implemented!

Parameters

(x,y)              - starting point of the drag & drop action
targetNode         - the drop target UI object
(targetX, targetY) - ending point of the drag & drop action

Remarks

x and y are relative to top-left corner of the current UI object or to clippingRegion if one is specified.
targetX and targetY are relative to top-left corner of targetNode or to targetNode.clippingRegion if one is specified.

FindAll

object[] FindAll(UiFindScope scope, string selector)

Retrieves a collection of UiNode objects according to selector search criteria.

Parameters

scope    - direct children, all descendants or top levels (see: UiFindScope)
selector - XML string specifying the conditions the UI objects in the collection should meet

Return

an array of UiNode objects that meets the scope and selector.

Errors

If the selector is invalid then E_UINODE_SYNTAX error is raised.
E_UINODE_INVALID_FINDALL_CALL is raised when the selector and the type of the current node does not match (see Remarks).

Remarks

The parameter selector is a non-empty XML string that must contain only one XML element:
<type_collection attr_1=val_1 … attr_n=val_n />

where type_collection is one of: wnd, ctrl, java, webctrl. If there are no XML attributes then all elements of type_collection type are considered. For some XML attributes, * wildcard is accepted as detailed in the table below:

type_collection	Valid attributes
wnd	aaname, app, title, cls, ctrlName, ctrlId (* wildcard supported by all attributes)
ctrl	name, automationId, labeledBy (* wildcard supported), role
java	name, virtualName (* wildcard supported), role
webctrl	tag + any HTML attribute (* wildcard supported)

Calling constraints:

// Assume that uiNode is valid object of type_node type.
uiNode.FindAll(scope, "<type_collection attr_1=val_1 … />");

Not all type_node - type_collection combinations are valid as explained in the table below:

type_node	type_collection
wnd	wnd
wnd	ctrl
wnd	java (if uiNode.hwnd is a Java window)
ctrl	ctrl
java	java
html	webctrl
webctrl	webctrl
webctrl	ctrl (if the HTML element is a window-less <embed> or <object>)

FindFirst

UiNode FindFirst(UiFindScope scope, string selector)

Retrieves a UI object, child of the current node or top level, according to scope and selector search criteria.

Parameters

scope    - direct children, all descendants or top levels (see: UiFindScope)
selector - XML string specifying the conditions the UI object should meet

Return

a new UiNode that meets the scope and selector.

Errors

If no UI object is found then E_UINODE_INVALID_IDENTIFIER error is raised.
If the selector is invalid then E_UINODE_SYNTAX error is raised.

Remarks

For UI_FIND_TOP_LEVELS the selector must contain only one XML element.
The current UiNode can be uninitialized only for UI_FIND_TOP_LEVELS otherwise
E_UINODE_UNINITIALIZED_ELEMENT error is raised if the element is not initialized.

FindImage

UiRegion FindImage(UiImage pImage, double dAccuracy) Searches the current UI object on screen for the position that matches the given image with a specific accuracy.

Parameters

image    - the image that is to be found inside the current UI object
accuracy - percent unit (0, 1] of the minimum similarity between the images 

Return

a UiRegion which represents the rectangle of the located text. This rectangle is relative to the UI object.

Errors

E_FAIL error is raised if the image is not found with the given accuracy.

Remarks

If the UiNode object has a clippingRegion set then this method searches only in that region.
If you want to get a collection of all matches see the FindAll method

FindString

UiRegion FindString(string text, int occurence, UiScrapeOptions options)

Searches for text in a given UI object and returns the bounding rectangle of the text found.

Parameters

text         - the text you are looking for.
occurence    - specifies how many times the text has to be found in order to have a final match.
options      - UiScrapeOptions object that specifies how to extract the text.

Return

a UiRegion which represents the rectangle of the located text. This rectangle is relative to the UI object.

Errors

E_INVALIDARG error is raised for invalid input parameters.

Remarks

If the UiNode object has a clippingRegion set then this method searches only in that region.
When the text is not found it returns a null UiRegion. The text parameter is case sensitive.
Occurence is 0 based, which means that you must specify 0 for the first occurence.

FromDesktop

UiNode FromDesktop()

Connects the current node to the top level desktop UI object.

Return

the current node making method chaining possible.

Remarks

If the current UiNode is already initialized, its internal data are released before connecting to desktop UI object.
If the current node represents the desktop then Click and Hover use screen coordinates to simulate mouse actions.
Also WriteText will simulates keystrokes on the window that has the focus.

FromScreenPoint

UiNode FromScreenPoint(int x, int y)

Initializes the internal data of the current UiNode with the UI object that contains the screen point (x, y).

Parameters

x   - horizontal coordinate of point
y   - vertical coordinate of point

Return

the current node making method chaining possible.

Errors

E_UINODE_UNINITIALIZED_ELEMENT error is raised if the element is not initialized.

Remarks

If the current UiNode is already initialized, its internal data are released before initializing from screen point.

FromScreenRegion

UiNode FromScreenRegion(UiRegion pVal)

Initializes the internal data of the current UiNode with the UI object that contains the UiRegion pVal.

Parameters

pVal    - a UiRegion in screen coordinates

Return

the current node making method chaining possible.

Errors

E_INVALIDARG error is raised for invalid input parameters.

Remarks

The UiNode returned is the smallest UI object that encloses the UiRegion passed as parameter.
If there isn't any UI object that completely encloses the UiRegion, than the UiNode returned is the top level window that 
contains the UI object located at the center of the region.
The clippingRegion of the current UiNode represents the UiRegion relative to UiNode's screen position.
The clippingRegion of the current UiNode can have negative coordinates.

FromSelector

UiNode FromSelector(string selector)

Initializes the internal data of the current UiNode according to Selector parameter.

Parameters

selector -  XML string specifying the conditions that the user interface object should meet

Return

the current node making method chaining possible.

Errors

If no UI object is found then E_UINODE_INVALID_IDENTIFIER error is raised.
If the selector is invalid then E_UINODE_SYNTAX error is raised.
E_UINODE_CANCELED_ERR error is raised if the current operation is canceled (see Cancel event).

Remarks

The method searches for a UI object that matches the selector in the amount of time specified by timeout property.

FromUIElem

UiNode FromUIElem(object uiElem)

Converts an existing UIElement to UiNode.

Parameters

uiElem - the UIElement object that will be used to initialize the current UiNode

Return

the current node making method chaining possible.

Remarks

UIElement library is deprecated. New projects should use UiNode instead.
If the current UiNode is already initialized, its internal data are released before conversion.
For Java UI objects the conversion is actually a transfer of ownership; the uiElem will become uninitialized after conversion.

See also: UIElem.InitializeFromUiNode and How to mix old and new API.

FromWindow

UiNode FromWindow(UiWindow window)

Converts a UiWindow library object to UiNode.

Parameters

window - the UiWindow library object that will be used to initialize the current UiNode

Return

the current node making method chaining possible.

Remarks

If the current UiNode is already initialized, its internal data are released before connecting to window UI object.

Get

object Get(string attr)

Retrives the specified attribute value.

Parameters

attr - the name of the attribute

Return

Depending on the attr name, a string, bool or object is returned.

Errors

E_UINODE_INVALID_ATTRIBUTE is raised if attr is not supported.

Remarks

For attributes type and name please check the Attributes section.

GetCaretPos

UiRegion GetCaretPos()

Retrieves the client coordinates of the caret's current position.

Return

the caret's position as a UiRegion object.

Remarks

the result is actually a point, the UiRegion object having zero widht and height.

GetBrowser

UiBrowser GetBrowser()

Creates a UiBrowser object out of a UiNode.

Return

a new browser object.

Errors

E_INVALIDARG is raised if the current UiNode is not a <html> or <webctrl> node.

Remarks

UiBrowser provides more browser-specific features for nodes that are web pages or web controls.

GetFocus

UiNode GetFocus()

Retrieves the UI object that has the focus. This method is not yet implemented!

Return

the node that has the focus or null.

Remarks

It starts with the current node and searches for a descendant that has the focus.
The method returns the current node itself if the current UI object has the focus.
If no object has the focus then null is returned.

GetSelector

string GetSelector(bool refresh)

Computes the selector of the current UiNode.

Parameters

refresh - if true, the function will recompute the selector.
If the function is called for the first time, the selector is calculated anyway. 

Return

a selector in XML format.

Errors

E_UINODE_UNINITIALIZED_ELEMENT is raised if the node is not initialized.
E_UINODE_INVALID_ELEMENT is raised if the user interface object is no longer valid.

Remarks

UiNode objects initialized by FromSelector already have a selector.

GetTopLevelWindow

UiWindow GetTopLevelWindow()

Creates a UiWindow object out of a UiNode.

Return

a new UiWindow associated with the top level parent window of the current UI object.

Remarks

UiWindow provides more window-specific features.

HasAttribute

bool HasAttribute(string attr)

Determines whether the current node has the specified attribute. This method is not yet implemented!

Parameters

attr - the name of the attribute

Return

true if the current node supports attr, false otherwise.

Remarks

For more information check Attributes section.

HideCaret

void HideCaret()

Removes the caret from the screen. This method is not yet implemented!

Hover

UiNode Hover(int dx, int dy, UiInputMethod inputMethod, int time)

Simulates mouse hover event over the current UI object.

Parameters

dx          - horizontal displacement of the mouse cursor position
dy          - vertical displacement of the mouse cursor position
inputMethod - hardware events, Win32 messages or node-dependent (see: UiInputMethod)
time        - the amount of time to keep the mouse cursor over the UI object

Return

the current node making method chaining possible.

Errors

E_UINODE_CLICK_ACTION_ERR is raised if the current UI object does not support inputMethod for simulating hover.
E_UINODE_CLICK_GENERIC_ERR is raised when Click fails due to unknown failures in the underlying
automation technology (like Active Accessibility, Java Accessibility Bridge, HTML events).

Remarks

dx and dy are relative to clippingRegion or to top-left corner of the UI object if no clippingRegion is set.
If the current node represents the desktop or is uninitialized then dx and dy are in screen coordinates.

IsEqual

bool IsEqual(UiNode anotherNode)

Compares two UiNode objects.

Return

true if the two UiNodes point to the same user interface objects, false otherwise.

Remarks

You can have two different UiNodes pointing to the same user interface object on the screen.
The method does not compare UiNodes objects themself but the UI objects they are pointing to.

IsValid

bool IsValid()

Checks if a UiNode object is in a valid state or not.

Return

true if the UI object is still valid, false otherwise.

Remarks

Even if you have a valid UiNode object, the corresponding user interface object can be destroyed (e.g. a window was closed).
In this case IsValid returns false.

MatchSelector

bool MatchSelector(string selector, bool matchChildren)

This method checks if the current UiNode object can be uniquely identified by the specified selector.

Parameters

selector      - XML string which will be matched against the current UiNode object.
matchChildren - specifies if the children of the UI nodes matching the selector should be considered as "matching".

Return

This function returns true if there is a unique correspondence between the current UiNode object and the given selector. Otherwise, it returns false.

Errors

E_INVALIDARG will be raised for an invalid selector parameter.
E_UINODE_SYNTAX will be raised if the selector parameter does not have a proper XML syntax.

Remarks

The "classic" method of checking if a UiNode matches a selector is to initialize a second UiNode object from that selector using the FromSelector method and then comparing the internal data of the objects. This approach is very inefficient, because, most of the time, you will have a mismatch coming from the very first child node in the selector.

MatchSelector is a fast method of checking whether the selector can uniquely describe the current UiNode. Unlike the FromSelector method, MatchSelector does not iterate the whole hierarchy specified by the selector. This method is able to stop at the first attribute mismatch, which will probably occur very early, if the selector does not match.

Moreover, the XML nodes in the selector which describe intermediary UI nodes in a unique manner can be dismissed faster by the matching algorithm. The XML nodes that have the index attribute set are considered to be not unique among the parent sub-tree. If the index attribute is not set, then the XML node indicates a unique UI sub-node. Our methods and tools which generate selectors verify this uniqueness and set the index attribute accordingly. If you write the selector yourself, or modify an existing one, make sure that the intermediary UI node is unique among the parent sub-tree before removing its index attribute.

Next

UiNode Next()

Retrieves the next node in the UI objects hierarchy. This method is not yet implemented!

Return

 next node relative to current node or null.

Remarks

The next logical object is returned, generally a sibling to the current object
or null if there is no next node.

Parent

UiNode Parent()

Retrieves the parent node of the current UiNode.

Return

 parent UiNode or null.

Remarks

null if the current node has no parent (it is a top level node).

Previous

UiNode Previous()

Retrieves the previous node in the UI objects hierarchy. This method is not yet implemented!

Return

 previous node relative to current node or null.

Remarks

The previous logical object is returned, generally a sibling to the current object
or null if there is no previous node.

Reset

UiNode Reset()

Releases any resources used internally by a UiNode and brings the node back to uninitialized state.

Return

the current node making method chaining possible.

Remarks

 For an uninitialized node, Click and Hover use screen coordinates to simulate mouse actions.
 Also WriteText will simulates keystrokes on the window that has the focus.

Scrape

UiScrapeResult Scrape(UiScrapeOptions options)

Extracts text from the current UiNode.

Parameters

options - UiScrapeOptions object that specifies how to extract the text.

Return

a UiScrapeResult object that contains the scraped text and some additional information.

Errors

E_INVALIDARG error is raised for invalid input parameters. 

Remarks

If the UiNode object has a clippingRegion set then only that region is scraped.
The method returns null if the UI object text cannot be extracted with the specified scrape options.
If UI_AUTOMATIC is used then, after execution, the options parameter will contain the scraping method choosen to extract the text.

Screenshot

UiImage Screenshot() Retrieves a screenshot of the current UI object.

Return

 UiImage object representing the screenshot of the current UI object.

Remarks

The screenshot takes into account clippingRegion property and it's cropped to that region.

SelectInteractive

UiNode SelectInteractive(UiSelectionType selectionType)

Initializes the internal data of the current UiNode with the UI object or region the user selects on screen. This method requires interaction with the user.

Parameters

selectionType - a UiSelectionType that specifies the default section mode

Return

the current node making method chaining possible.

Errors

E_UINODE_SELECTION_INTERNAL_ERR error is raised if selection is canceled.

Remarks

For rectangular region selections, the clippingRegion of the current UiNode represents the UiRegion relative to UiNode's screen position, similar to FromScreenRegion

Set

UiNode Set(string attr, object value)

Sets the value of the specified attribute.

Parameters

attr  - the name of the attribute
value - the value to be set

Errors

E_UINODE_INVALID_ATTRIBUTE is raised if attr is not supported or is read-only.

Remarks

Setting the value of an attribute changes the state of the underlying UI object on the screen
(e.g. selectedItem really selects the item inside the combo or list control).
For attributes type and name please check the Attributes section.

SetFocus

UiNode SetFocus()

Sets the keyboard focus to the current UI object

Return

the current node making method chaining possible.

ShowCaret

void ShowCaret()

Makes the caret visible on the screen at the caret's current position. This method is not yet implemented!

Remarks

When the caret becomes visible, it begins flashing automatically.

StartHighlight

UiNode StartHighlight()

Shows a visual highlighting rectangle around the UiNode.

Return

the current node making method chaining possible.

Remarks

This method is useful for debugging purposes.
The highlight rectangle takes into account clippingRegion property.

StopHighlight

UiNode StopHighlight()

Removes the visual highlighting rectangle around the UiNode.

Return

the current node making method chaining possible.

Remarks

This method is useful for debugging purposes.
It removes the visual highlighting rectangle previously displayed by StartHighlight.

TopParent

UiNode TopParent()

Retrieves the top parent node of the current UiNode.

Return

 top parent node.

Remarks

The top parent is a top level window.

WaitAttribute

UiNode WaitAttribute(string attr, object value)

Waits for the attr attribute of the current UI object to meet a specified value.

Parameters

attr  - the attribute name
value - the required attribute value the method is waiting for

Return

the current node making method chaining possible.

Errors

E_UINODE_WFR_TIMEOUT_ERR is raised when the attribute does not meet the required value in timeout.
E_UINODE_CANCELED_ERR is raised when the wait is canceled (see Cancel event).

Remarks

The method waits the amount of time specified by timeout property.

WaitForReady

UiNode WaitForReady(UiWaitForReadyLevels readyLevel)

Waits for the UI object to meet a given ready level.

Parameters

readyLevel - the level to be reached.

Return

the current node making method chaining possible.

Errors

E_UINODE_WFR_TIMEOUT_ERR is raised when the UI object does not meet the required readyLevel in timeout.
E_UINODE_CANCELED_ERR is raised when the wait is canceled (see Cancel event).

Remarks

The method wait for readyLevel the amount of time specified by timeout property.

WaitImage

UiNode WaitImage(UiImage Image, double Accuracy, int Appear)

Waits for a UiImage to appear or dissapear in the amount of time specified by timeout property

Parameters

Image     - represents the UiImage object you are waiting for
Accuracy  - the precentage of similarity used to find the UiImage 
Appear    - specifies the event you are waiting for

Return

the current node making method chaining possible.

Errors

If time elapsed and the UiImage didn't appear/disappear than E_UINODE_TIMEOUT_ERR is raised
E_INVALIDARG error is raised for invalid input parameters.

Remarks

Accuracy parameter is a double between 0 and 100.
If Appear is 0 than the method waits for a UiImage to disappear, else it waits for the UiImage to appear.

WriteText

UiNode WriteText(string text, UiInputMethod inputMethod)

Puts text in the UI object identified by the current UiNode.

Parameters

text        - the text to write into the control
inputMethod - hardware events, Win32 messages or node-dependent (see: UiInputMethod)

Return

the current node making method chaining possible.

Errors

E_UINODE_KEYS_SYNTAX is raised when the special syntax in text parameter is incorrect (see Remarks).
E_UINODE_CANNOT_USE_CTRL_API_METHOD is raised when UI_CONTROL_API method failed.
E_UINODE_KEYS_OTHER_ERR is raised when WriteText fails due to unknown errors in the underlying
automation technology (like Active Accessibility, Java Accessibility Bridge, HTML events).

Remarks

When UI_HARDWARE_EVENTS method is specified, special characters like Alt, Shift, Ctrl can be simulated. In order to specify such a character the following convention is used:

• A special characters sequence is enclosed in []
• A sequence of special characters consists of a sequence of tokens that describe the key that is pressed or released in order to synthesize that character.

A token has the form

TOKEN:=OPERATION(SPECIAL_CHARS)
OPERATION:=k|d|u
SPECIAL_CHARS:=alt|lalt|ralt|shift|lshift|rshift|ctrl|lctrl|rctrl|ins|del|home|end|pgup|pgdn|enter|left|right|up|
               down|tab|esc|back|pause|f1|f2|f3|f4|f5|f6|f7|f8|f9|f10|f11|f12|caps|num|add|sub|mul|div|decimal|break|
               num0|num1|num2|num3|num4|num5|num6|num7|num8|num9|scroll|sleep

k:=synthesize a key down followed by a key up event for the specified key.
d:=synthesize a key down event for the specified SPECIAL_CHARS.
u:=synthesize a key up event for the specified SPECIAL_CHARS.

Note: If you need to send [ char you need to escape it as [[.

  Example: text = "AbC[d(ctrl)]a[u(ctrl)k(alt)]" 
  This sample sequence outputs "AbC", then holds down (d) the Ctrl key, 
  presses "a" and then releases Ctrl (u) and hits Alt (k = press and release).

Properties

attributes

string[] attributes { get; }

Retrieves an array containing the names of the attributes supported by the current node.

autoRefresh

bool autoRefresh { set; get; }

When true, automatically re-initializes the current node if the UI object associated with it is no longer valid. Default value is true.

Remarks

The following methods are affected by autoRefresh: BringToForeground, Click, Get, Hover, Parent, Set, TopParent, WriteText.

clippingRegion

UiRegion clippingRegion { set; get; }

Defines a clipping rectangle inside the current node. Default value is null.

Remarks

When a clipping region is set, all the coordinates are relative to the clipping region.
Methods affected: Click, Hover, GetImage, StartHighlight.
Reset method resets clippinRegion to null.

timeout

int timeout { set; get; }

Defines the timeout used by any method that must complete its action in a given amount of time. Default value is 120,000 miliseconds (2 minutes).

Remarks

Method affected: FindFirst, FromSelector, WaitForReady, WaitImage.
If these methods cannot complete their task in timeout then E_UINODE_WFR_TIMEOUT_ERR error is raised.

waitForReadyLevel

UiWaitForReadyLevels waitForReadyLevel { set; get; }

Defines the ready level. Default value UI_WFR_INTERACTIVE.

Remarks

The following methods are affected: Click, Hover, Set, WriteText.
Before performing their actions, those methods first wait #timeout amount of time for the current node to
meet the specified waitFroReadyLevel.

If the required level is not met then E_UINODE_WFR_TIMEOUT_ERR error is raised.

Attributes

A UiNode object acts like an attribute dictionary. Each attribute has a name and a value, attributes names are case-insensitive. Attributes are used with the following methods: Get, HasAttribute and Set. Attributes can be read-only or read-write.

If a node does not support an attribute then E_UINODE_INVALID_ATTRIBUTE is raised. E_UINODE_INVALID_ATTRIBUTE is also raised when a read-only attribute is used in Set method.

Setting the value of an attribute changes the state of the underlying UI object on the screen (e.g. selectedItem really selects the item inside the combo or list control).

For <webctrl> nodes any HTML attribute is accepted in Get/Set methods.

aaname

Type:   string
Access: read-only

Retrieves the Active Accessibility name of the current node.

aastate

Type:   string
Access: read-only

Retrieves the Active Accessibility state of the current node. The value is provided as a comma-separated enumeration of AA states (e.g. "focusable, read only, linked").

app

Type:   string
Access: read-only

Retrieves the file name of the application containing the current node. Only the .exe file name without the path is provided.

AppPath

Type:   string
Access: read-only

Retrieves the file path of the application containing the current node. The path without .exe file name is provided.

automationId

Type:   string
Access: read-only

Retrieves the UI Automation ID of the current node. The attribute is exposed only by <ctrl> nodes.

checked

Type:   bool
Access: read-write

Gets or sets a value indicating whether the node is in the checked state. It only works for UI objects that actually are checkable (e.g. check-boxes, radios).

cls

Type:   string
Access: read-only

Retrieves the class name of the window containing the current node.

cookie

Type:   string
Access: read-write

Retrieves the cookie string for the HTML document containing the current node. It is exposed only by <html> and <webctrl> nodes.

ctrlId

Type:   string
Access: read-only

Retrieves the Win32 control ID of the window containing the current node.

ctrlName

Type:   string
Access: read-only

Retrieves the Windows Forms name of the current node. It is exposed ony by WinForms controls.

hasFocus

Type:   bool
Access: read-only

Gets a boolean value indicating whether the object currently has focus.

hwnd

Type:   number
Access: read-write

Gets or sets the Win32 window handle of the node. Setting a new HWND actually re-initializes the node.

innerHtml

Type:   string
Access: read-write

Gets or sets the innerHTML property of a HTML object. It is exposed only by <webctrl> nodes.

innerText

Type:   string
Access: read-only

Retrieves the innerText property of a HTML object. It is exposed only by <webctrl> nodes.

IsJavaBridgeEnabled

Type:   bool
Access: read-only

Retrieves a value indicating whether Java Accessibility Bridge is enabled for the application containing the current node. See Install Java Support for more info.

Usually IsJavaBridgeEnabled is used when IsJavaWindow attribute is true for the current node.

IsJavaWindow

Type:   bool
Access: read-only

Retrieves a value indicating whether the current node belongs to a Java application.

items

Type:   array
Access: read-only

Retrieves the collection of all items (as strings) inside a container UI object (e.g. list-box, combo-box).

javaState

Type:   string
Access: read-only

Retrieves the state of the current node as provided by Java Accessibility Bridge. The value is a comma-separated enumeration of states (e.g. "enabled, focusable, visible"). It only works for <java> nodes.

labeledBy

Type:   string
Access: read-only

Retrieves the UI Automation labeled by attribute of the current node. The attribute is exposed only by <ctrl> nodes.

name

Type:   string
Access: read-only

Retrieves the name of the current node. For <ctrl> and <wnd> nodes the name is provided by Active Accessibility. For <java> nodes the name is provided by Java Accessibility Bridge. For <html> the name is the usual HTML name attribute.

outerHtml

Type:   string
Access: read-write

Gets or sets the outerHTML property of a HTML object. It is exposed only by <webctrl> nodes.

outerText

Type:   string
Access: read-write

Gets or sets the outerText property of a HTML object. It is exposed only by <webctrl> nodes.

parentClass

Type:   string
Access: read-only

Retrieves the class HTML attribute of the fist parent node that have class. It is exposed only by <webctrl> nodes.

parentId

Type:   string
Access: read-only

Retrieves the ID HTML attribute of the fist parent node that have ID. It is exposed only by <webctrl> nodes.

parentName

Type:   string
Access: read-only

Retrieves the name HTML attribute of the fist parent node that have name. It is exposed only by <webctrl> nodes.

PID

Type:   number
Access: read-only

Retrieves the process ID of the application containing the current node.

position

Type:   UiRegion
Access: read-only

Gets the screen position of the node. It does not take into account the clippingRegion.

readyState

Type:   bool
Access: read-only

Gets a value indicating whether the HTML object is ready for scraping/automation. It is exposed only by <html> and <webctrl> nodes.

role

Type:   string
Access: read-only

Retrieves the Active Accessibility role of the current node.

selectedItem

Type:   string
Access: read-write

Gets or sets the selected item (as strings) inside a container UI object (e.g. list-box, combo-box). Setting the selected item of the current node also changes the selection inside the combo/list box UI control.

subsystem

Type:   string
Access: read-only

Retrieves the underlying UI system name as follows:

<wnd>     - "win32"
<ctrl>    - "aa"
<java>    - "java"
<html>    - "html"
<webctrl> - "webctrl"

With subsystem attribute we can find the type of a node at runtime.

tag

Type:   string
Access: read-only

Retrieves the HTML tagof the current node. It is exposed only by <webctrl> nodes.

text

Type:   string
Access: read-write

Gets the text value of a node. Sets the text value of editable UI objects (e.g. editable boxes).

TID

Type:   number
Access: read-only

Retrieves the ID of the thread that created the current node.

title

Type:   string
Access: read-only

Retrieves the window title of the node. For <html> nodes the web page title is retrieved. For <webctrl> the title is the usual title HTML attribute.

url

Type:   string
Access: read-write

Gets or sets the URL of the web page containing the current node. It is exposed only by <html> and <webctrl> nodes. Setting the URL causes the IE web page to navigate.

virtualName

Type:   string
Access: read-only

Retrieves the virtual name of the current Java node. as provided by Java Accessibility Bridge. It is only exposed by <java> nodes.

Errors

All methods and properties could raise E_UINODE_NOT_REGISTERED, E_UINODE_UNINITIALIZED_ELEMENT, E_UINODE_INVALID_ELEMENT errors if not otherwise specified.

All methods could also raise standard COM errors like: E_INVALIDARG, E_FAIL, E_UNEXPECTED.

Click, Hover, Set, WaitForReady, WaitImage and WriteText could raise E_UINODE_WFR_TIMEOUT_ERR if waitForReadyLevel is not meet in timeout.

FindFirst, FromSelector, RunApplication and WaitImage could raise E_UINODE_CANCELED_ERR error if the current operation is canceled (see Cancel event).

In most programming languages the errors are reported as exception (like COMException in C#).

E_UINODE_NOT_REGISTERED

hresult: 0x80040211
code:    529
message: Trial version expired. Please activate the library.

E_UINODE_INVALID_IDENTIFIER

hresult: 0x80040212
code:    530
message: Cannot find the UI object corresponding to this selector.

E_UINODE_SYNTAX

hresult: 0x80040213
code:    531
message: Syntax error in the selector.

E_UINODE_UNINITIALIZED_ELEMENT

hresult: 0x80040214
code:    532
message: Uninitialized UI node.

E_UINODE_INVALID_ELEMENT

hresult: 0x80040215
code:    533
message: Invalid UI node.

E_UINODE_CANNOT_USE_CTRL_API_METHOD

hresult: 0x80040216
code:    534
message: Cannot use UI_CONTROL_API on this UI node. Please use UI_HARDWARE_EVENTSmethod.

E_UINODE_CANNOT_GET_RECTANGLE

hresult: 0x80040217
code:    535
message: Cannot get the screen rectangle of this UI node.

E_UINODE_KEYS_SYNTAX

hresult: 0x80040218
code:    536
message: Syntax error in the key list.

E_UINODE_INVALID_FINDALL_CALL

hresult: 0x80040219
code:    537
message: Invalid FindAll call.

E_UINODE_INVALID_FINDFIRST_CALL

hresult: 0x8004021A
code:    539
message: Invalid FindFirst call.

E_UINODE_INVALID_START_CMD

hresult: 0x8004021E
code:    539
message: Invalid command line in RunApplication method.

E_UINODE_INVALID_ATTRIBUTE

hresult: 0x80040221
code:    545
message: Attribute not supported by the current UiNode.

E_UINODE_KEYS_OTHER_ERR

hresult: 0x80040222
code:    546
message: Synthetizing keys failure.

E_UINODE_WFR_TIMEOUT_ERR

hresult: 0x80040223
code:    547
message: Timeout reached. Increase timeout and/or change waitForReadyLevel property.

E_UINODE_CANCELED_ERR

hresult: 0x80040225
code:    549
message: Operation was canceled.

E_UINODE_INVALID_CLICK_BTN

hresult: 0x8004021A
code:    538
message: Invalid button parameter in Click method.

E_UINODE_INVALID_CLICK_MODE

hresult: 0x8004021B
code:    539
message: Invalid mode parameter in Click method.

E_UINODE_CLICK_GENERIC_ERR

hresult: 0x8004021D
code:    541
message: Click generic error.

E_UINODE_CLICK_ACTION_ERR

hresult: 0x80040220
code:    544
message: Action not supported by this type of element. Please use another type of click.

E_UINODE_SELECTION_INTERNAL_ERR

hresult: 0x80040224
code:    548
message: Internal error.

E_UINODE_TIMEOUT_ERR

hresult: 
code: 
message: Timeout reached.

Events

UiNode exposes only one event:

event IUiNodeEvents_CancelEventHandler Cancel
delegate void IUiNodeEvents_CancelEventHandler(out bool cancel)

Cancel event occurs repeatedly during time consuming operations: FindFirst, FromSelector, WaitImage, WaitPage. It gives the users a chance to cancel a long operation.

To cancel the current processing you have to set cancel out parameter to true in your event handler function. The current operation will raise a E_UINODE_CANCELED_ERR error.

For more info check this Events Tutorial.