Since: API Level v2
public final class

JavaUIAPlugin

com.webmbt.plugin.JavaUIAPlugin

Class Overview

JavaUIA (beta) plugin enables the model to interact/drive Windows Java UI application. It executes commands through a .Net library to perform Windows based UIAutomation actions.

To utilise this plugin, enable JavaUIA plugin in Model Property dialog and you have enabled Java Access Bridge, please refer to How to setup for Java UIA for more details.

TestOptimalServer.bat (or TestOptimalServer.sh for linux/mac) must have lib/uia/* added to the class path argument.

Java UI element types (roles) (Up to Java 1.3)

  • Alert
  • AWT Component
  • Canvas
  • Check Box
  • Color Chooser
  • Column Header
  • Combo Box
  • Desktop Icon
  • Desktop Pane
  • Dialog
  • Directory Pane
  • File Chooser
  • Filler
  • Frame
  • Glass Pane
  • Icon
  • Internal Frame
  • Label
  • Layered Pane
  • List
  • List Item
  • Menu
  • Menu Bar
  • Menu Item
  • Option Pane
  • Page Tab
  • Page Tab List
  • Password Text
  • Panel
  • Popup Menu
  • Progress Bar
  • Push Button
  • Radio Button
  • Root Pane
  • Row Header
  • Scroll Pane
  • Scroll Bar
  • Separator
  • Slider
  • Split Pane
  • Swing Component
  • Toggle Button
  • Table
  • Text
  • Tool Bar
  • Tool Tip
  • Tree
  • Uknown
  • Window

Java UI Automation Actions
The following table of supported actions that can be performed on a Java UI element are listed in the table below. NOTE: In Java, the majority of UI objects have actions available inherent with the type of object, e.g. "push button" will always support the "click" action. However, the ability to perform an action will be affected by the status of the item, namely whether it is currently enabled, or focusable.
Argument variables for PerformGivenAction() Description
actionType subActionType
Activate -- For hyperlinks and selectable tree items, the "Activate" action is akin to the user clicking into the item, but where the "Click" action is not supported.
Click--Emulates the user performing a mouse click on the UI element.
Toggle Selected--Performs the action of switching the UI element between selected and unselected. Typically applies in cases where multiple select, or highlight, is possible.
Change Selection--In a parent UI element which has a number of selectable child items (but the child items themselves don't support the "Toggle Selected" action), then this action will shift the selection to the item corresponding the numerical value given argument. Used against types such as page tab lists, and combo box drop down lists.
Toggle Expand--Performs the action of switching the UI element between expanded and collapsed, as in the case of element trees. If an argument is provided of value expand/collapse, then the plugin will make sure that the item ends in the respective expanded/collapsed state.
Edit--Performs the begin edit action.
Commit Edit--Equivalent of the user finishing their text entry into the editable field.
Cancel Edit--Equivalent to the user cancelling their edit operation of an editable UI object, and returning its value to the previous value.
Set Caret--Will move the cursor position in the editable field. The numerical value given in the argument defines the index of the character the cursor should be behind, i.e. an argument of 3 will put the cursor behind the 3rd character.
Toggle Drop Down--Toggles a drop down item, such as a drop down menu, between expanded and collapsed.
Close Window--For a frame or dialog which supports this action, it is equivalent to the user selecting the close button in the top right of that frame/dialog.

Java UI Element Properties
The following table lists standard properties that are assigned to Java UI elements, and the string that can be passed as the "propertyName" in the getProperty() to retrieve that value.
propertyName Description and return value
acceleratorkey Accelerator key is typically the key that combines with an ALT keypress to provide a shortcut to the UI element of interest.
accesskey Access key is the full keyboard shortcut that pertains to the UI element of interest. E.g. ALT+F.
canmaximise Returns the string value of true / false to indicate if the UI element can be maximised.
canminimise Returns the string value of true / false to indicate if the UI element can be minimised.
canmove Returns the string value of true / false to indicate if the UI element can be moved by the user.
canresize Returns the string value of true / false to indicate if the UI element can be resized by the user.
canrotate Returns the string value of true / false to indicate if the UI element can be rotated.
canselectmultiple Returns the string value of true / false to indicate if the UI element permits multiple child elements to be selected at any one given time.
classname Returns the class name of the UI element.
controltype Returns the full name of the Control Type of the UI element.
expandcollapsestate Returns the string representation of the current expand/collapse state of the UI element:
  • Expanded
  • Collapsed
frameworkid Returns the Framework ID of the UI element.
haskeyboardfocus Returns the string value of true / false to indicate if the UI element currently has keyboard focus (i.e. will be the specific UI element that will receive any keyboard events if they occur at that time).
helptext Returns the help text string for that UI element, typically also the tooltip text.
iscontentelement Returns the string value of true / false to indicate if the UI element is a content element.
isenabled Returns the string value of true / false to indicate if the UI element is currently enabled.
isoffscreen Returns the string value of true / false to indicate if the UI element is off screen, specifically, if it is scrolled out of sight within its parent container.
ispassword Returns the string value of true / false to indicate if the UI element is a password field, i.e. if it disguises user input when entered.
isselected Returns the string value of true / false to indicate if the UI element is currently selected.
itemstatus Returns the status string, if the UI element is used to convey the status of the application or an application component, e.g. it may convey if a contact in an instant messaging application is "busy", "connected", etc.
localizedcontroltype Returns the localised version of the Control Type string, generally an abbreviated version of the Control Type property.
name Returns the name of the UI element.
togglestate Returns the string representation of the current toggle state of the UI element:
  • Off
  • On
value Returns the value of the UI element. This will take a different form for various UI elements, for example in hyperlinks this will return the URL, for text fields it will return the contents, for combo boxes it will display the current value or tooltip.
windowvisualstate Returns the string representation of the current window visual state of the UI element:
  • Maximized
  • Minimized
  • Normal

Copyright © 2008 - 2017 TestOptimal LLC. All Rights Reserved.

Summary

Public Constructors
JavaUIAPlugin()
Public Methods
boolean activateObject()
Will attempt to perform the Java UI Activate action on the last found Java UI object / window.
boolean addSelection()
Performs an "add to selection" on the last found UI object / window, equivalent to a CTRL + select.
boolean clickObject()
Will attempt to perform the Window UI Invoke pattern on the last found UI object / window.
boolean closeWindow()
Will attempt to trigger the close event from the Window pattern on the last found UI object / window.
boolean collapseObject()
Will attempt to trigger the collapse event from the ExpandCollapse pattern for the last found UI object / window.
String countSelectedItems()
Retrieves the count representing the number of selected items in the last found UI object / window.
boolean doAction(String actionType, String subActionType, String actionValue1, String actionValue2, String parentFrame)
Will perform the specified action on the last found UI object.
boolean expandObject()
Will attempt to trigger the expand event from the ExpandCollapse pattern for the last found UI object / window.
boolean findJavaWindow(String window, String win_exact, String nestedJavaApp)
finds the root window hosting a Java Application.
boolean findObject(String object, String obj_exact, String objectType, String index)
Will return whether it finds an object with a matching name property, similar to the previous function, but allows the user to specify selecting the Nth occurrence of a matching criteria, where N or more matching UI elements have been found.
boolean findObject(String object, String obj_exact, String objectType)
Will return whether it finds an object of the given text and type under the last window.
boolean findObjectByProperty(String searchText, String exactText, String objectType, String index, String propertyType, String relative)
Similar to the preceding function [findObjectByProperty()], but also allows the user to define whether the search should occur relative to reference point last set via setRefPoint().
boolean findObjectByProperty(String searchText, String exactText, String objectType, String index, String propertyType)
Will return whether it finds a UI object based on its type and the search text.
boolean findObjectIDRelToRef(String objectID)
boolean findObjectIDRelToRef(String objectID, String objectType)
boolean findObjectRelToRef(String object, String obj_exact, String objectType, String index)
boolean findObjectRelToRef(String object, String obj_exact, String objectType)
Will search for the defined object, within the UI tree relative to the reference point that has been set.
String getCenterX()
returns the last UI element center X co-ordinate.
String getCenterY()
returns the last UI element center Y co-ordinate.
String getClassName()
Retrieves the property containing the name for the last found UI object / window.
String getControlType()
Retrieves the property containing the UI Control Type for the last found UI object / window.
String getExpandCollapseState()
Retrieves the property containing the current expanded/collapsed state for the last found UI object / window.
String getFontSize()
Retrieves the Font Size in the current text/edit UI object.
String getFontType()
Retrieves the Font Type in the current text/edit UI object.
String getHeight()
returns the pixel height of the last found UI element.
String getItemStatus()
Retrieves the property containing the item status for the last found UI object / window.
String getName()
Retrieves the name for the last found UI object / window.
String getProperty(String propertyName, String qualifier)
Retrieves the property identified by the given name.
String getProperty(String propertyName)
Attempt to retrieve the specified property from the last found UI object, regardless of whether it was a window or child UI element.
boolean getRefPoint()
Sets the current UI element of interest to the reference point, if a valid one is currently held.
String getSelectedChildName()
Defined primarily for Java UI support, where the current selected item from a list is not discernable directly from the selectable items themselves, but by querying their immediate parent container.
String getValue()
Retrieves the value of the last found UI object / window (should not be confused with the name).
String getWidth()
returns the pixel width of the last found UI element.
String getWindowCoords()
returns the current window coordinates in the format of (left, top).
String getWindowSize()
returns the current window size in the format of (width, height).
String getX()
returns the last UI element x-coordinate.
String getY()
returns the last UI element y-coordinate.
String hasFocus()
Returns whether the last found UI object / window has the keyboard focus.
boolean haveRefPoint()
Query to check whether we have a reference point set.
String isEditable()
Returns whether the last found UI object / window is editable.
String isEnabled()
Returns whether the last found UI object / window is enabled.
String isExpandable()
Returns whether the last found UI object / window is expandable.
String isOffscreen()
Returns whether the last found UI object / window is outside the view boundaries of its parent container (e.g.
String isSelected()
Returns whether the last found UI object / window is currently selected.
boolean removeSelection()
Performs a "remove from selection" on the last found UI object / window, equivalent to a deselect without affecting other selected items.
boolean resetTCP()
Resets connection to the UIA TCP service.
boolean select()
Performs a select operation on the last found UI object / window.
boolean setFocus()
For items are focusable (which is the majority of UI elements) it will set the item in focus, equivalent to the user clicking within that component.
boolean setRefPoint()
Will set a reference point at the last found UI element, whether it was from a findWindow() or findObject() operation.
void setUIAPort(String port)
Allows TestOptimal user to set a specific port number for the UIATCPServer TCP/IP connection to be on.
String snapScreen(String fn_p)
takes a snapshot of the current window and save the image in the file specified.
boolean startApp(String appPath, String args)
Starts the application (via a hidden host command prompt session) with the given arguments.
boolean stopApp(String appPath)
Performs a "kill process" operation on the given application.
void type(String typeText)
Utilizes the Java Robot to emulate US 101 keyboard presses to provide the action of typing.
void typeWithModifier(String typeText, String optionKey)
Utilizes the Java Robot to emulate US 101 keyboard presses to provide the action of typing into the current UI element.
boolean waitForJavaWindow(String searchWindow, String win_exact, String nestedJavaApp, String milliseconds)
Search for the given Java window, defined by the title text, from the root of the UI tree, and only within the first level.
boolean waitForObject(String searchObject, String obj_exact, String objectType, String milliseconds)
Search for the given object, identified by the combination of its name text and object type, within the UI tree from the parent window.
boolean waitForObjectByProperty(String searchText, String exactText, String objectType, String index, String property, String relative, String duration)
Generic search that can define which property field the search text can be applied against the chosen property field for found objects.
boolean waitForObjectDestroyed(String searchText, String exactText, String objectType, String index, String property, String relative, String duration)
Wait for a given UI element, identified by the search criteria to be destroyed or dismissed by application or system events, within the given time allowance.

Public Constructors

public JavaUIAPlugin ()

Since: API Level v2

Public Methods

public boolean activateObject ()

Since: API Level v2

Will attempt to perform the Java UI Activate action on the last found Java UI object / window.

Returns
  • true - if successful. false - if an error occurred performing the operation, or the Activate action is not supported for the current UI element.

public boolean addSelection ()

Since: API Level v2

Performs an "add to selection" on the last found UI object / window, equivalent to a CTRL + select.

Returns
  • true - if successful. false - if an error occurred performing the action, or the SelectionItem pattern is not supported for the current UI element.

public boolean clickObject ()

Since: API Level v2

Will attempt to perform the Window UI Invoke pattern on the last found UI object / window.

Returns
  • true - if successful. false - if an error occurred performing the operation, or the Invoke pattern is not supported for the current UI element.

public boolean closeWindow ()

Since: API Level v2

Will attempt to trigger the close event from the Window pattern on the last found UI object / window.

Returns
  • true - if successful. false - if an error occurred performing the action, or the Window pattern is not supported for the current UI element.

public boolean collapseObject ()

Since: API Level v2

Will attempt to trigger the collapse event from the ExpandCollapse pattern for the last found UI object / window.

Returns
  • true - if successful. false - if an error occurred performing the action, or the ExpandCollapse pattern is not supported for the current UI element.

public String countSelectedItems ()

Since: API Level v2

Retrieves the count representing the number of selected items in the last found UI object / window.

Throws
property is not supported for the current UI element. User will need to check the TestOptimal error logs for the details of the failure.
MBTException

public boolean doAction (String actionType, String subActionType, String actionValue1, String actionValue2, String parentFrame)

Since: API Level v2

Will perform the specified action on the last found UI object.

Parameters
actionType (required) - the action to be performed on the UI element found. For a full list of possible actions, see Appendix B - Microsoft UI Automation Actions.
subActionType (conditional) - For acceptable values, see Appendix B - Microsoft UI Automation Actions.
actionValue1 (conditional) - For acceptable values, see Appendix B - Microsoft UI Automation Actions.
actionValue2 (conditional) - For acceptable values, see Appendix B - Microsoft UI Automation Actions.
parentFrame (required) if "true", action will be directed to the Window object at the top of the UI tree.

If "false", action will be directed at the last UI element.

Alternatively, you can also use "window" to direct action to the parent window,

"refpoint" to direct action to the last saved reference point,

or "latest" for the most recent child UI element found.

Returns
  • true - if successful, false - if an error occurred establishing connections or if the input arguments were invalid.

public boolean expandObject ()

Since: API Level v2

Will attempt to trigger the expand event from the ExpandCollapse pattern for the last found UI object / window.

Returns
  • true - if successful. false - if an error occurred performing the action, or the ExpandCollapse pattern is not supported for the current UI element.

public boolean findJavaWindow (String window, String win_exact, String nestedJavaApp)

Since: API Level v2

finds the root window hosting a Java Application. The given text identifies the hosting Microsoft Window. This Window is then recursively searched for the lowest level Sun Java frame, which is then used as the base reference for the Java application UI tree. If found, it keeps a reference to that Sun Java object and uses it as the root location for all subsequent Java UI object search requests.

Returns true if Java UI window is found, otherwise it returns false.

Parameters
window (optional) - the text to be used to match in the parent UI element name property.
nestedJavaApp (optional) - if has a value of "true", then once the root Microsoft UI window element is found, it will recursively search for the first Sun Java frame element it encounters and treats this as the root of the Java UI tree. If this parameter is not defined, or set as "false", then it will test the root Microsoft window UI element as to whether it is also a Java element (it won't search recursively).
Returns
  • true - if successful and a match was found. false - if an error occurred establishing connections or if the input arguments were invalid.

public boolean findObject (String object, String obj_exact, String objectType, String index)

Since: API Level v2

Will return whether it finds an object with a matching name property, similar to the previous function, but allows the user to specify selecting the Nth occurrence of a matching criteria, where N or more matching UI elements have been found.

Parameters
object (optional) - the text to be used to match in child UI element name property. If no text string is given, then the search will look for the first child element that matches based on objType.
index The "index" argument identifies N.
Returns
  • true - if successful and a match was found. false - if an error occurred establishing connections or if the input arguments were invalid.

public boolean findObject (String object, String obj_exact, String objectType)

Since: API Level v2

Will return whether it finds an object of the given text and type under the last window. If found, it will keep a reference to the AUT UI Object itself such that future actions and commands will be directed to.

Parameters
object (optional) - the text to be used to match in child UI element name property. If no text string is given, then the search will look for the first child element that matches based on objType.
Returns
  • true - if successful and a match was found. false - if an error occurred establishing connections or if the input arguments were invalid.

public boolean findObjectByProperty (String searchText, String exactText, String objectType, String index, String propertyType, String relative)

Since: API Level v2

Similar to the preceding function [findObjectByProperty()], but also allows the user to define whether the search should occur relative to reference point last set via setRefPoint().

Supported property codes are:

  • "name" : Searches the name field of the UI element
  • "tooltip" : Searches the tooltip (aka help text) field
  • "classname" : Searches the class name field, which should be noted to be different from the Control Type (or Object Type).
  • "autoid" : Search by the Automation ID (applicable to Win UI objects only).

Parameters
searchText : The text string to be used when searching the relevant property field.
exactText : A string value of either 'true'/'false' to indicate whether the searchText should be an exact match or if a partial match is ok.
objectType : Filter on the UI object type.
index : The index parameter indicates which found occurrence should be returned.
relative : A string value of either 'true'/'false' to indicate whether the search should be conducted relative to the current reference point.

public boolean findObjectByProperty (String searchText, String exactText, String objectType, String index, String propertyType)

Since: API Level v2

Will return whether it finds a UI object based on its type and the search text. This function allows the user to direct the search text against a specific property field in the event that the name field does not contain usable value.

Supported property codes are:

  • "name" : Searches the name field of the UI element
  • "tooltip" : Searches the tooltip (aka help text) field
  • "classname" : Searches the class name field, which should be noted to be different from the Control Type (or Object Type).
  • "autoid" : Search by the Automation ID (applicable to Win UI objects only).

Parameters
searchText : The text string to be used when searching the relevant property field.
exactText : A string value of either 'true'/'false' to indicate whether the searchText should be an exact match or if a partial match is ok.
objectType : Filter on the UI object type.
index : The index parameter indicates which found occurrence should be returned.

public boolean findObjectIDRelToRef (String objectID)

Since: API Level v2

public boolean findObjectIDRelToRef (String objectID, String objectType)

Since: API Level v2

public boolean findObjectRelToRef (String object, String obj_exact, String objectType, String index)

Since: API Level v2

public boolean findObjectRelToRef (String object, String obj_exact, String objectType)

Since: API Level v2

Will search for the defined object, within the UI tree relative to the reference point that has been set.

Parameters
object (optional) - the text to be used to match in child UI element name property. If no text string is given, then the search will look for the first child element that matches based on objType.
Returns
  • true - if successful and a match was found. false - if an error occurred establishing connections, if the input arguments were invalid, or if no reference point exists.

public String getCenterX ()

Since: API Level v2

returns the last UI element center X co-ordinate.

Returns
  • ui element center X co-ordinate
Throws
MBTException

public String getCenterY ()

Since: API Level v2

returns the last UI element center Y co-ordinate.

Returns
  • ui element center Y co-ordinate.
Throws
MBTException

public String getClassName ()

Since: API Level v2

Retrieves the property containing the name for the last found UI object / window.

Returns
  • the property string.
Throws
property is not supported for the current UI element. User will need to check the TestOptimal error logs for the details of the failure.
MBTException

public String getControlType ()

Since: API Level v2

Retrieves the property containing the UI Control Type for the last found UI object / window.

Returns
  • the property string.
Throws
property is not supported for the current UI element. User will need to check the TestOptimal error logs for the details of the failure.
MBTException

public String getExpandCollapseState ()

Since: API Level v2

Retrieves the property containing the current expanded/collapsed state for the last found UI object / window.

Returns
  • the property string.
Throws
property is not supported for the current UI element. User will need to check the TestOptimal error logs for the details of the failure.
MBTException

public String getFontSize ()

Since: API Level v2

Retrieves the Font Size in the current text/edit UI object.

Returns
  • the font size.
Throws
property is not supported for the current UI element. User will need to check the TestOptimal error logs for the details of the failure.
MBTException

public String getFontType ()

Since: API Level v2

Retrieves the Font Type in the current text/edit UI object.

Returns
  • the font property.
Throws
property is not supported for the current UI element. User will need to check the TestOptimal error logs for the details of the failure.
MBTException

public String getHeight ()

Since: API Level v2

returns the pixel height of the last found UI element.

Returns
  • UI element pixel height.
Throws
MBTException

public String getItemStatus ()

Since: API Level v2

Retrieves the property containing the item status for the last found UI object / window.

Throws
property is not supported for the current UI element. User will need to check the TestOptimal error logs for the details of the failure.
MBTException

public String getName ()

Since: API Level v2

Retrieves the name for the last found UI object / window.

Throws
property is not supported for the current UI element. User will need to check the TestOptimal error logs for the details of the failure.
MBTException

public String getProperty (String propertyName, String qualifier)

Since: API Level v2

Retrieves the property identified by the given name. Qualifier is used in contexts where the property relates to an element of a selected group.

Parameters
propertyName - property of current element that we want to get the value of.
qualifier - typically a N index to a subgroup.
Returns
  • value of the requested property code. Empty string if not supported.
Throws
MBTException

public String getProperty (String propertyName)

Since: API Level v2

Attempt to retrieve the specified property from the last found UI object, regardless of whether it was a window or child UI element.

Parameters
propertyName (required) - the name of the property that is wished to be retrieved.
Returns
  • - if property is not supported for the current UI element, if there was an error in finding a UI element with the parameters given, or the parameters were invalid. User will need to check the TestOptimal error logs for the details of the failure. - if successful, the command will return the property string.
Throws
MBTException

public boolean getRefPoint ()

Since: API Level v2

Sets the current UI element of interest to the reference point, if a valid one is currently held. (Restores stored UI reference element as item that will receive following UI operations).

Returns
  • value: true - if successful. false - if no reference point is held, or the current reference point is invalid.

public String getSelectedChildName ()

Since: API Level v2

Defined primarily for Java UI support, where the current selected item from a list is not discernable directly from the selectable items themselves, but by querying their immediate parent container.

Throws
property is not supported for the current UI element. User will need to check the TestOptimal error logs for the details of the failure.
MBTException

public String getValue ()

Since: API Level v2

Retrieves the value of the last found UI object / window (should not be confused with the name).

Throws
property is not supported for the current UI element. User will need to check the TestOptimal error logs for the details of the failure.
MBTException

public String getWidth ()

Since: API Level v2

returns the pixel width of the last found UI element.

Returns
  • UI element pixel width.
Throws
MBTException

public String getWindowCoords ()

Since: API Level v2

returns the current window coordinates in the format of (left, top).

Returns
  • "" on error or no window not selected.
Throws
MBTException

public String getWindowSize ()

Since: API Level v2

returns the current window size in the format of (width, height).

Returns
  • window width and height
Throws
MBTException

public String getX ()

Since: API Level v2

returns the last UI element x-coordinate.

Returns
  • ui element left most x-coordinate.
Throws
MBTException

public String getY ()

Since: API Level v2

returns the last UI element y-coordinate.

Returns
  • ui element upper most y-coordinate.
Throws
MBTException

public String hasFocus ()

Since: API Level v2

Returns whether the last found UI object / window has the keyboard focus.

Returns
  • the property string.
Throws
property is not supported for the current UI element. User will need to check the TestOptimal error logs for the details of the failure.
MBTException

public boolean haveRefPoint ()

Since: API Level v2

Query to check whether we have a reference point set. A quick query to the reference point's properties are also made to ensure that it is valid (i.e. UI element still exists on screen). If the reference point has become invalid, then it'll be destroyed

Returns
  • value: true - if a reference point is saved and still valid, otherwise false - if there is no reference point or the current one has become invalid.

public String isEditable ()

Since: API Level v2

Returns whether the last found UI object / window is editable.

Returns
  • the property string.
Throws
property is not supported for the current UI element. User will need to check the TestOptimal error logs for the details of the failure.
MBTException

public String isEnabled ()

Since: API Level v2

Returns whether the last found UI object / window is enabled.

Returns
  • the property string.
Throws
property is not supported for the current UI element. User will need to check the TestOptimal error logs for the details of the failure.
MBTException

public String isExpandable ()

Since: API Level v2

Returns whether the last found UI object / window is expandable.

Returns
  • the property string.
Throws
property is not supported for the current UI element. User will need to check the TestOptimal error logs for the details of the failure.
MBTException

public String isOffscreen ()

Since: API Level v2

Returns whether the last found UI object / window is outside the view boundaries of its parent container (e.g. scrolled out of view).

Throws
property is not supported for the current UI element. User will need to check the TestOptimal error logs for the details of the failure.
MBTException

public String isSelected ()

Since: API Level v2

Returns whether the last found UI object / window is currently selected.

Throws
property is not supported for the current UI element. User will need to check the TestOptimal error logs for the details of the failure.
MBTException

public boolean removeSelection ()

Since: API Level v2

Performs a "remove from selection" on the last found UI object / window, equivalent to a deselect without affecting other selected items.

Returns
  • true - if successful. false - if an error occurred performing the action, or the SelectionItem pattern is not supported for the current UI element.

public boolean resetTCP ()

Since: API Level v2

Resets connection to the UIA TCP service. Use it to reestablish connection to UIA agent process. Returns true if a TCP connection to the agent could be established.

Returns
  • true - if successful. false - if an error occurred.

public boolean select ()

Since: API Level v2

Performs a select operation on the last found UI object / window.

Returns
  • true - if successful. false - if an error occurred performing the action, or the SelectionItem pattern is not supported for the current UI element.

public boolean setFocus ()

Since: API Level v2

For items are focusable (which is the majority of UI elements) it will set the item in focus, equivalent to the user clicking within that component.

Returns
  • true - if successful. false - if an error occurred, or the UI element is not focusable.

public boolean setRefPoint ()

Since: API Level v2

Will set a reference point at the last found UI element, whether it was from a findWindow() or findObject() operation. If there had been a previous reference point set, then that point will be lost.

Returns
  • true - if successful. false - if an error occurred, i.e. primarily if there is no previously found UI element to set a reference point against.

public void setUIAPort (String port)

Since: API Level v2

Allows TestOptimal user to set a specific port number for the UIATCPServer TCP/IP connection to be on.

Parameters
port The port number that TCP/IP communication should occur on between the UIA plugin and the UIATCPService.

public String snapScreen (String fn_p)

Since: API Level v2

takes a snapshot of the current window and save the image in the file specified. The file is stored in snapscreen subfolder of the model folder.

Note this function is overloaded by different plugins. If multiple plugins are used for the model, be sure to prefix the function call with the plugin nmae, for example $WinUIA.snapScreen('myScreen.jpg').

Returns
  • the image file
Throws
Exception

public boolean startApp (String appPath, String args)

Since: API Level v2

Starts the application (via a hidden host command prompt session) with the given arguments. appPath can contain the full path to the executable.

Parameters
appPath (required) - the executable/batch/command to run. May contain absolute path. MUST NOT contain any arguments or parameters.
args (optional) - any arguments or parameters to pass to the command at run time. Can be left blank.
Returns
  • true - if successful, false - if an error occurred establishing connections or if the input arguments were invalid.
Throws
MBTException

public boolean stopApp (String appPath)

Since: API Level v2

Performs a "kill process" operation on the given application. app should just define the process name, with no execution or path.

Returns
  • true - if successful, false - if an error occurred processing the request.

public void type (String typeText)

Since: API Level v2

Utilizes the Java Robot to emulate US 101 keyboard presses to provide the action of typing. Will require the user to ensure that the events are going to the correct field.

Parameters
typeText (required) - this is the string that the user wishes to be typed. Can contain special characters such as punctuation, carriage returns, and tabs.

You may send one function key in typeText with the key token, [KEYS.ENTER], [KEYS.F1], etc. When key token is used, typeText must only contain one key token only. See Sending Keyboard Keys.

Throws
Exception

public void typeWithModifier (String typeText, String optionKey)

Since: API Level v2

Utilizes the Java Robot to emulate US 101 keyboard presses to provide the action of typing into the current UI element.

Example:

<action code="$typeWithModifier ('this is my text','[KEYS.SHIFT][KEYS.CONTROL]')"/>

Parameters
typeText (required) - this is the string that the user wishes to be typed. Can contain special characters such as punctuation, carriage returns, and tabs.

You may send one function key in typeText with the key token, [KEYS.ENTER], [KEYS.F1], etc. When key token is used, typeText must only contain one key token only. See Sending Keyboard Keys.

Throws
Exception

public boolean waitForJavaWindow (String searchWindow, String win_exact, String nestedJavaApp, String milliseconds)

Since: API Level v2

Search for the given Java window, defined by the title text, from the root of the UI tree, and only within the first level. If the window is found within the timeframe defined in milliseconds, then true is returned, otherwise false is returned. A reference to that window will be maintained if search successful.

Parameters
nestedJavaApp (optional) - if has a value of "true", then once the root Microsoft UI window element is found, it will recursively search for the first Sun Java frame element it encounters and treats this as the root of the Java UI tree. If this parameter is not defined, or set as "false", then it will test the root Microsoft window UI element as to whether it is also a Java element (it won't search recursively).
milliseconds (required) - the duration in milliseconds that the utility will continue to search for, if the UI element is not found.
Returns
  • true - if successful and a match was found. false - if an error occurred, the input arguments were invalid, or the timeout occurred without finding the UI element.

public boolean waitForObject (String searchObject, String obj_exact, String objectType, String milliseconds)

Since: API Level v2

Search for the given object, identified by the combination of its name text and object type, within the UI tree from the parent window. If the UI object is found within the timeframe defined in milliseconds, then true is returned, otherwise false is returned. References to that window and object will be maintained if search successful.

Parameters
milliseconds (required) - the duration in milliseconds that the utility will continue to search for, if the UI element is not found.
Returns
  • true - if successful and a match was found. false - if an error occurred, the input arguments were invalid, or the timeout occurred without finding the UI element.

public boolean waitForObjectByProperty (String searchText, String exactText, String objectType, String index, String property, String relative, String duration)

Since: API Level v2

Generic search that can define which property field the search text can be applied against the chosen property field for found objects. Supports relative searching derived against the last set reference point.

Supported property codes are:

  • "name" : Searches the name field of the UI element
  • "tooltip" : Searches the tooltip (aka help text) field
  • "classname" : Searches the class name field, which should be noted to be different from the Control Type (or Object Type).
  • "autoid" : Search by the Automation ID (applicable to Win UI objects only).

Parameters
searchText : The text string to be used when searching the relevant property field.
exactText : A string value of either 'true'/'false' to indicate whether the searchText should be an exact match or if a partial match is ok.
objectType : Filter on the UI object type.
property : The name of the property field to search in with the searchText.
relative : A string value of either 'true'/'false' to indicate whether the search should be conducted relative to the current reference point.
duration : milliseconds to wait for.

public boolean waitForObjectDestroyed (String searchText, String exactText, String objectType, String index, String property, String relative, String duration)

Since: API Level v2

Wait for a given UI element, identified by the search criteria to be destroyed or dismissed by application or system events, within the given time allowance. No reference to any UI objects will be retained, but the reference to the root window element, and any UI reference point, will be retained.

Supports relative searching derived against the last set reference point.

Supported property codes are:

  • "name" : Searches the name field of the UI element
  • "tooltip" : Searches the tooltip (aka help text) field
  • "classname" : Searches the class name field, which should be noted to be different from the Control Type (or Object Type).
  • "autoid" : Search by the Automation ID (applicable to Win UI objects only).

Parameters
searchText The text string to be used when searching the relevant property field.

exactText A string value of either 'true'/'false' to indicate whether the searchText should be an exact match or if a partial match is ok.

objectType Filter on the UI object type.

property The name of the property field to search in with the searchText.

relative A string value of either 'true'/'false' to indicate whether the search should be conducted relative to the current reference point.

duration Time in milliseconds to wait for UI element to be destroyed.
Returns
  • true/false indicating success.