Since: API Level v2
public final class

WinUIAPlugin

com.webmbt.plugin.WinUIAPlugin

Class Overview

WinUIAPlugin enables the model to interact/drive Windows UI application. It executes commands through a .Net library to perform Windows based UIAutomation actions.

To utilise this plugin, enable WinUIA plugin in Model Property dialog. You may use Microsoft UI Verify spy utility to find the locator for the UI controls.

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

Microsoft UI Automation Types
The following list defines the different Control Types supported:

  • Button
  • Calendar
  • CheckBox
  • ComboBox
  • Custom
  • DataGrid
  • DataItem
  • Document
  • Edit
  • Group
  • Header
  • HeaderItem
  • Hyperlink
  • Image
  • List
  • ListItem
  • Menu
  • MenuBar
  • MenuItem
  • Pane
  • ProgressBar
  • RadioButton
  • ScrollBar
  • Separator
  • Slider
  • Spinner
  • SplitButton
  • StatusBar
  • Tab
  • TabItem
  • Table
  • Text
  • Thumb
  • TitleBar
  • ToolBar
  • ToolTip
  • Tree
  • TreeItem
  • Window
  • Microsoft UI Automation Actions
    The list of supported actions that can be performed on a Windows UI element are listed in the table below. NOTE: Some actions are implicitly supported by an object type (e.g. Button type always supports Invoke patterns) but many other patterns are only supported if the developer of the application coded support. To determine if an element supports a specific Windows pattern / action, it can be checked via the VisualUIVerify tool, or Microsoft's Inspect tool.

    Argument variables for PerformGivenAction() Description
    actionType subActionType
    Dock -- For dockable elements, allows user to set the docking orientation. The value of actionValue1 can be any of the following: Bottom / Fill / Left / None / Right / Top
    actionValue2 is ignored.
    ExpandCollapse Collapse Will collapse a UI element that supports ExpandCollapsePattern. A common example is pull down menus. Both actionValue1 and actionValue2 are ignored.
    Expand Will expand a UI element that supports ExpandCollapsePattern. A common example is pull down menus. Both actionValue1 and actionValue2 are ignored.
    Grid -- Gets handle to UI element in the grid, located by row number (actionValue1) and column number (actionValue2).
    GridItem -- --NOT SUPPORTED --
    Invoke -- Emulates a user invoke action (typically a mouse click) on the UI element. Both actionValue1 and actionValue2 are ignored.
    MultipleView Setcurrentview Changes the UI element to show the view identified by the viewIndex (actionValue1). Examples are Media Player skins, or thumbnail views. Value in actionValue2 is ignored.
    RangeValue -- Changes the range value of the UI element to the value given in actionValue1. Value in actionValue2 is ignored.
    Scroll Scroll Performs a scroll in both the horizontal and vertical planes. Horizontal scroll amount is defined in actionValue1, and vertical scroll amount is defined in actionValue2.
    The scroll amounts are defined by using enumerated strings:
    largedecrement / smalldecrement / noamount / smallincrement / largeincrement
    Scrollhorizontal Performs a scroll in the horizontal plane. Horizontal scroll amount is defined in actionValue1, and actionValue2 is ignored.
    The scroll amount is defined by using enumerated strings:
    largedecrement / smalldecrement / noamount / smallincrement / largeincrement
    Scrollvertical Performs a scroll in the vertical plane. Vertical scroll amount is defined in actionValue1, and actionValue2 is ignored.
    The scroll amount is defined by using enumerated strings:
    largedecrement / smalldecrement / noamount / smallincrement / largeincrement
    Setscrollpercent Sets the scroll position in terms of percent of the overall scroll range. The percent value (between 0 to 100) will be moved to immediately. A value of "-1" will not scroll in that direction.
    The percent to set the horizontal scroll position is defined in actionValue1, and percent to set the vertical scroll position is defined in actionValue2.
    ScrollItem -- Scroll element into view. Typically used in picker objects. Both actionValue1 and actionValue2 are ignored.
    Selection -- --NOT SUPPORTED --
    SelectionItem Select Will perform a select operation on the current UI element. Both actionValue1 and actionValue2 are ignored.
    Addtoselection Will perform an add to selection where multiple selection is supported by the parent container. Both actionValue1 and actionValue2 are ignored.
    Removefromselection Will remove the current element from the current selection, where multiple selection is supported by the parent container. Both actionValue1 and actionValue2 are ignored.
    Table -- Gets handle to UI element in the table cell located by row number (actionValue1) and column number (actionValue2).
    TableItem -- -- NOT SUPPORTED --
    Text -- -- NOT SUPPORTED --
    Toggle -- Performs the toggle operation on the current UI element. Both actionValue1 and actionValue2 are ignored.
    Transform Move Performs a move operation on the current UI element, to the screen pixel co-ordinates defined by x (actionValue1) and y (actionValue2). The top-left corner of the UI element will be moved to that location.
    Resize Performs a resize operation on the current UI element, to the screen pixel co-ordinates defined by x (actionValue1) and y (actionValue2). The bottom-right corner of the UI element will be dragged to that location.
    Rotate Performs a rotate operation on the current UI element, rotating by the degrees given in actionValue1. actionValue2 is ignored.
    Value -- -- NOT SUPPORTED --
    Window Close Emulates a user initiated close request on the current UI element. Both actionValue1 and actionValue2 are ignored.
    setwindowvisualstate Changes the window visual state of the current UI element. The new state is taken from the enumerated string value in actionValue1:
    Maximised / minimised / normal.
    actionValue2 is ignored.

    Microsoft UI Element Properties
    The following table lists standard properties that are assigned to Microsoft UI elements, and the string that can be passed as the "propertyName" in the RetrieveObjectProperty() 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
    WinUIAPlugin()
    Public Methods
    boolean addSelection()
    Performs an "add to selection" on the last found UI object / window, equivalent to a CTRL + select.
    boolean addSelection(String xpath)
    Performs an "add to selection" on the UI object / window identified by xpath, equivalent to a CTRL + select.
    String canMaximise()
    Returns whether the last found UI object / window can be maximised.
    String canMaximise(String xpath)
    Returns whether the UI object / window identified by xpath can be maximised.
    String canMinimise(String xpath)
    Returns whether the UI object / window identified by xpath can be minimised.
    String canMinimize()
    Returns whether the last found UI object / window can be minimised.
    String canMove()
    Returns whether the last found UI object / window can be moved.
    String canMove(String xpath)
    Returns whether the UI object / window identified by xpath can be moved.
    String canResize()
    Returns whether the last found UI object / window can be resized.
    String canResize(String xpath)
    Returns whether the UI object / window identified by xpath can be resized.
    String canRotate(String xpath)
    Returns whether the UI object / window identified by xpath can be rotated.
    String canRotate()
    Returns whether the last found UI object / window can be rotated.
    boolean clickObject()
    Will attempt to perform the Window UI Invoke pattern on the last found UI object / window.
    boolean clickObject(String xpath)
    Will attempt to perform the Window UI Invoke pattern on the UI object / window identified by the xpath
    boolean closeWindow()
    Will attempt to trigger the close event from the Window pattern on the UI object / window identified by the xpath.
    boolean closeWindow(String xpath)
    Will attempt to trigger the close event from the Window pattern on the UI object / window identified by the xpath.
    boolean collapseObject(String xpath)
    Will attempt to trigger the collapse event from the ExpandCollapse pattern for the UI object / window identifed by xpath.
    boolean collapseObject()
    Will attempt to trigger the collapse event from the ExpandCollapse pattern for the last found UI object / window.
    String countObjects(String object, String obj_exact, String objectType)
    String countObjects(String object, String obj_exact, String objectType, String fromHere)
    Counts the UI objects found by the given text, under the UI tree relating to the last found window item (findWindow).
    String countSelectedItems(String xpath)
    Retrieves the count representing the number of selected items in the UI object / window identified by xpath.
    String countSelectedItems()
    Retrieves the count representing the number of selected items in the last found UI object / window.
    String countWindows(String window, String win_exact)
    Counts the windows found by the given text, in the first level from the host machine Desktop.
    boolean doAction(String actionType, String subActionType, String actionValue1, String actionValue2, String parentFrame)
    Will perform the specified action on the last found UI object.
    boolean dockObject(String dockLocation)
    Will attempt to set the docking location to dockLocation via the Docking pattern for the last found UI object / window.
    boolean dockObject(String xpath, String dockLocation)
    Will attempt to set the docking location to dockLocation via the Docking pattern for the UI object / window identified by xpath.
    boolean expandObject(String xpath)
    Will attempt to trigger the expand event from the ExpandCollapse pattern for the UI object / window identified by the xpath.
    boolean expandObject()
    Will attempt to trigger the expand event from the ExpandCollapse pattern for the last found UI object / window.
    boolean findObject(String object, String obj_exact, String objectType, String index)
    Will perform a search for a UI element, as in the aforementioned findObject(searchText, exactMatch, objectType), but also supports a fourth argument in which the user can define that they are wishing to reference the Nth occurrence of a UI element matching the search criteria.
    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 findObjectByTooltip(String tooltipText, String obj_exact, String objectType)
    Will return whether it finds an object of the given tooltip text and type under the last window.
    boolean findObjectID(String objectID)
    Will return whether it finds an object of the given automation ID under the last window.
    boolean findObjectID(String objectID, String objectType)
    Will return whether it finds an object of the given automation ID under the last found window reference.
    boolean findObjectIDRelToRef(String objectID)
    boolean findObjectIDRelToRef(String objectID, String objectType)
    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.
    boolean findObjectRelToRef(String object, String obj_exact, String objectType, String index)
    boolean findWindow(String window, String win_exact, String index)
    finds the window by the given text, in the first level from the host machine Desktop.
    boolean findWindow(String window, String win_exact)
    finds the window by the given text, in the first level from the host machine Desktop.
    boolean findWindowByProperty(String searchText, String win_exact, String attribute, String index)
    Finds the window by the given text, in the first level from the host Desktop.
    boolean findWindowID(String autoID, String index)
    Finds the primary application window by the given automation ID.
    boolean findXPath(String xpath)
    A replacement for findObject().
    String getCenterX(String xpath)
    returns the center X co-ordinate of UI element identified by xpath.
    String getCenterX()
    returns the last UI element center X co-ordinate.
    String getCenterY(String xpath)
    returns the center Y co-ordinate of UI element identified by xpath.
    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 getClassName(String xpath)
    Retrieves the property containing the name for the UI object / window identified by xpath.
    String getControlType(String xpath)
    Retrieves the property containing the UI Control Type for the UI object / window identified by xpath.
    String getControlType()
    Retrieves the property containing the UI Control Type for the last found UI object / window.
    String getExpandCollapseState(String xpath)
    Retrieves the property containing the current expanded/collapsed state for the UI object / window identified by xpath.
    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 getFontSize(String xpath)
    Retrieves the Font Size in the text/edit UI object idnetified by xpath.
    String getFontType(String xpath)
    Retrieves the Font Type in the text/edit UI object identified by xpath.
    String getFontType()
    Retrieves the Font Type in the current text/edit UI object.
    String getFrameworkID()
    Retrieves the property containing the framework ID for the last found UI object / window.
    String getFrameworkID(String xpath)
    Retrieves the property containing the framework ID for the UI object / window identified by xpath.
    String getHeight()
    returns the pixel height of the last found UI element.
    String getHeight(String xpath)
    returns the pixel height of the UI element identified by xpath.
    String getHelpText(String xpath)
    Retrieves the property containing the help text (typically the tooltip) for the UI object / window identified by xpath.
    String getHelpText()
    Retrieves the property containing the help text (typically the tooltip) for the last found UI object / window.
    String getInteractionState(String xpath)
    Retrieves the property containing the current window interaction state for the UI object / window identified by xpath.
    String getInteractionState()
    Retrieves the property containing the current window interaction state for the last found UI object / window.
    String getItemStatus()
    Retrieves the property containing the item status for the last found UI object / window.
    String getItemStatus(String xpath)
    Retrieves the property containing the item status for the UI object / window identified by xpath.
    String getLocalisedControlType(String xpath)
    Retrieves the property containing the localised control type for the UI object / window identified by xpath.
    String getLocalisedControlType()
    Retrieves the property containing the localised control type for the last found UI object / window.
    String getName(String xpath)
    Retrieves the name for the UI object / window identified by xpath.
    String getName()
    Retrieves the name for the last found UI object / window.
    String getPropAcceleratorKey()
    Retrieves the property containing the accelerator key for the last found UI object / window.
    String getPropAcceleratorKey(String xpath)
    Retrieves the property containing the accelerator key for the UI object / window identified by xpath.
    String getPropAccessKey()
    Retrieves the property containing the access key for the last found UI object / window.
    String getPropAccessKey(String xpath)
    Retrieves the property containing the access key for the UI object / window identified by xpath.
    String getPropAutoID()
    Retrieves the automation ID property for the last found UI object / window.
    String getPropAutoID(String xpath)
    Retrieves the automation ID property for the UI object / window identified by xpath.
    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 getSelectedChildName(String xpath)
    Defined primarily for Java UI support, where the item identified by xpath from a list is not discernable directly from the selectable items themselves, but by querying their immediate parent container.
    boolean getSelectedItem(String index)
    Will attempt to set the "last found UI Object" reference to the first item that is currently selected, if the previously referenced UI object supports the Selection pattern.
    boolean getSelectedItem(String xpath, String index)
    Will attempt to set the "UI Object identified by xpath" reference to the first item that is currently selected, if the previously referenced UI object supports the Selection pattern.
    String getToggleState(String xpath)
    Retrieves the current toggle state for the UI object / window identified by xpath.
    String getToggleState()
    Retrieves the current toggle state for the last found UI object / window.
    String getValue()
    Retrieves the value of the last found UI object / window (should not be confused with the name).
    String getValue(String xpath)
    Retrieves the value of the UI object / window identified by xpath (should not be confused with the name).
    String getViewName(String xpath, String viewIndex)
    Will retrieve the name property of the view identified by viewIndex from the UI object / window identified by xpath.
    String getViewName(String viewIndex)
    Will retrieve the name property of the view identified by viewIndex from the last found UI object / window.
    String getVisualState()
    Retrieves the property containing the current window visual status for the last found UI object / window.
    String getVisualState(String xpath)
    Retrieves the property containing the current window visual status for the UI object / window identified by xpath.
    String getWidth()
    returns the pixel width of the last found UI element.
    String getWidth(String xpath)
    returns the pixel width of the UI element identified by xpath.
    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(String xpath)
    returns the x-coordinate of the UI item identified by xpath.
    String getX()
    returns the last UI element x-coordinate.
    String getY(String xpath)
    returns the y-coordinate of the UI element identifieid by xpath.
    String getY()
    returns the last UI element y-coordinate.
    String hasFocus()
    Returns whether the last found UI object / window has the keyboard focus.
    String hasFocus(String xpath)
    Returns whether the UI object / window identified by xpath has the keyboard focus.
    boolean haveRefPoint()
    Query to check whether we have a reference point set.
    boolean isAppPopUpPresent(String titleText, String isChildPopUp)
    Will check for a pop-up dialog identified by the text in the pop up title.
    String isContentElement()
    Returns whether the last found UI object / window is a control element.
    String isContentElement(String xpath)
    Returns whether the UI object / window identified by xpath is a control element.
    boolean isDesktopIconPresent(String iconText)
    Searches the list of desktop icons for the first application icon that matches the text provided.
    String isEnabled()
    Returns whether the last found UI object / window is enabled.
    String isEnabled(String xpath)
    Returns whether the UI object / window identified by xpath is enabled.
    String isExpandable()
    Returns whether the last found UI object / window is expandable.
    String isExpandable(String xpath)
    Returns whether the UI object / window identified by xpath is expandable.
    String isOffscreen(String xpath)
    Returns whether the UI object / window identified by xpath is outside the view boundaries of its parent container (e.g.
    String isOffscreen()
    Returns whether the last found UI object / window is outside the view boundaries of its parent container (e.g.
    String isPassword(String xpath)
    Returns whether the UI object / window identified by xpath is a password field (indicates if user entered text is protected).
    String isPassword()
    Returns whether the last found UI object / window is a password field (indicates if user entered text is protected).
    String isSelected()
    Returns whether the last found UI object / window is currently selected.
    String isSelected(String xpath)
    Returns whether the UI object / window identified by xpath is currently selected.
    String isTopMost()
    Returns whether the last found UI object / window is at the top of the Windows z-order, i.e.
    String isTopMost(String xpath)
    Returns whether the UI object / window identified by xpath is at the top of the Windows z-order, i.e.
    boolean move(String xpath, String destX, String destY)
    Performs a move to the pixel co-ordinate location on the UI object / window identified by xpath.
    boolean move(String destX, String destY)
    Performs a move to the pixel co-ordinate location on the last found UI object / window.
    boolean openStartMenu()
    Will open the Microsoft Windows Start menu.
    boolean removeSelection(String xpath)
    Performs a "remove from selection" on the UI object / window identified by xpath, equivalent to a deselect without affecting other selected items.
    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(String dbgMode)
    INETRNAL USE ONLY.
    boolean resetTCP()
    Resets connection to the UIA TCP service.
    boolean resize(String xpath, String destX, String destY)
    Performs a resize operation, moving the resize control (typically lower-right corner of the window) to the given pixel co-ordinates.
    boolean resize(String destX, String destY)
    Performs a resize operation, moving the resize control (typically lower-right corner of the window) to the given pixel co-ordinates.
    boolean rotate(String degrees)
    Performs a rotate operation to the given number of degrees, on the last found UI object / window.
    boolean rotate(String xpath, String degrees)
    Performs a rotate operation to the given number of degrees, on the UI object / window identified by xpath.
    boolean scroll(String xpath, String scrollAmountX, String scrollAmountY)
    Emulate simultaneous horizontal and vertical scroll action on the UI object / window identified by xpath.
    boolean scroll(String scrollAmountX, String scrollAmountY)
    Emulate simultaneous horizontal and vertical scroll action on the last found UI object / window.
    boolean scrollHorizontal(String scrollAmount)
    Emulate a horizontal scroll action on the last found UI object / window.
    boolean scrollHorizontal(String xpath, String scrollAmount)
    Emulate a horizontal scroll action on the UI object / window identifed by xpath.
    boolean scrollVertical(String xpath, String scrollAmount)
    Emulate a vertical scroll action on the UI object / window identified by xpath.
    boolean scrollVertical(String scrollAmount)
    Emulate a vertical scroll action on the last found UI object / window.
    boolean select(String xpath)
    Performs a select operation on the UI object / window identified by xpath.
    boolean select()
    Performs a select operation on the last found UI object / window.
    boolean selectGridItem(String xpath, String row, String column)
    Will attempt to trigger the expand event from the ExpandCollapse pattern for the UI object / window identified by xpath.
    boolean selectGridItem(String row, String column)
    Will attempt to trigger the expand event from the ExpandCollapse pattern for the last found UI object / window.
    boolean selectTableItem(String row, String column)
    Will attempt to set the "last found UI Object" reference to the element from the given grid location, if the previously referenced UI object supports the TableItem pattern.
    boolean selectTableItem(String xpath, String row, String column)
    Will attempt to set the the UI Object reference identified by xpath to the element from the given grid location, if the previously referenced UI object supports the TableItem pattern.
    boolean setCurrentView(String xpath, String viewIndex)
    Will set the visible view to that identified by viewIndex for the UI object / window identifed by xpath.
    boolean setCurrentView(String viewIndex)
    Will set the visible view to that identified by viewIndex for 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 setFocus(String xpath)
    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 setObjectValue(String xpath, String newValue)
    HAS LIMITED SUPPORT FROM MICROSOFT.
    boolean setObjectValue(String newValue)
    HAS LIMITED SUPPORT FROM MICROSOFT.
    boolean setRefPoint()
    Will set a reference point at the last found UI element, whether it was from a findWindow() or findObject() operation.
    boolean setScrollIntoView()
    If the last found UI object is out of the current view, then scroll into view if it supports the Scroll pattern
    boolean setScrollIntoView(String xpath)
    If the UI object identified by xpath is out of the current view, then scroll into view if it supports the Scroll pattern
    boolean setScrollPercent(String horizPercent, String vertPercent)
    Modify the scroll position of the scrollable element for horizontal and/or vertical scroll operations for the last found UI object / window.
    boolean setScrollPercent(String xpath, String horizPercent, String vertPercent)
    Modify the scroll position of the scrollable element for horizontal and/or vertical scroll operations for the UI object / window identified by xpath.
    boolean setSliderRange(String range)
    Will perform the action of modifying the last found UI object / window to have the slider set to the new value given in range.
    boolean setSliderRange(String xpath, String range)
    Will perform the action of modifying the UI object / window identified by xpath to have the slider set to the new value given in range.
    void setUIAPort(String port)
    Allows TestOptimal user to set a specific port number for the UIATCPServer TCP/IP connection to be on.
    boolean setVisualStatus(String xpath, String newStatus)
    Will attempt to set the Window Visual State to the value of "newStatus" for the UI object / window identified by the xpath.
    boolean setVisualStatus(String newStatus)
    Will attempt to set the Window Visual State to the value of "newStatus" for the last found UI object / window.
    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.
    boolean toggle()
    Performs a toggle event on the last found UI object / window.
    boolean toggle(String xpath)
    Performs a toggle event on the UI object / window identified by xpath.
    void type(String xpath, String typeText)
    Utilizes the Java Robot to emulate US 101 keyboard presses to provide the action of typing into the UI element identified by xpath.
    void type(String typeText)
    Utilizes the Java Robot to emulate US 101 keyboard presses to provide the action of typing into the UI element that has the focus.
    void typeWithModifier(String typeText, String optionKey)
    Utilizes the Java Robot to emulate US 101 keyboard presses to provide the action of typing into the UI element that has the focus.
    void typeWithModifier(String xpath, String typeText, String optionKey)
    Utilizes the Java Robot to emulate US 101 keyboard presses to provide the action of typing into the UI element identified by xpath.
    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.
    boolean waitForObjectID(String searchObjectID, String milliseconds)
    Search for the given object, identified by the provided automation ID, within the UI tree from the parent window.
    boolean waitForWindow(String searchWindow, String win_exact, String milliseconds)
    Search for the given window, defined by the title text, from the root of the UI tree, and only within the first level.
    boolean waitForWindowByProperty(String searchText, String win_exact, String index, String property, String milliseconds)
    Search for the given window, defined by the given properties, from the root of the UI tree, and only within the first level.
    boolean waitForWindowDestroyed(String searchWindow, String win_exact, String milliseconds)
    Will wait until the matching window is 'destroyed', by either being closed or dismissed by a system event, or until the timeout has occurred.

    Public Constructors

    public WinUIAPlugin ()

    Since: API Level v2

    Public Methods

    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 addSelection (String xpath)

    Since: API Level v2

    Performs an "add to selection" on the UI object / window identified by xpath, equivalent to a CTRL + select.

    Parameters
    xpath (required) - the xpath to identify the control
    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 String canMaximise ()

    Since: API Level v2

    Returns whether the last found UI object / window can be maximised.

    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 canMaximise (String xpath)

    Since: API Level v2

    Returns whether the UI object / window identified by xpath can be maximised.

    Parameters
    xpath (required) - the xpath to identify the control
    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 canMinimise (String xpath)

    Since: API Level v2

    Returns whether the UI object / window identified by xpath can be minimised.

    Parameters
    xpath (required) - the xpath to identify the control
    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 canMinimize ()

    Since: API Level v2

    Returns whether the last found UI object / window can be minimised.

    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 canMove ()

    Since: API Level v2

    Returns whether the last found UI object / window can be moved.

    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 canMove (String xpath)

    Since: API Level v2

    Returns whether the UI object / window identified by xpath can be moved.

    Parameters
    xpath (required) - the xpath to identify the control
    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 canResize ()

    Since: API Level v2

    Returns whether the last found UI object / window can be resized.

    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 canResize (String xpath)

    Since: API Level v2

    Returns whether the UI object / window identified by xpath can be resized.

    Parameters
    xpath (required) - the xpath to identify the control
    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 canRotate (String xpath)

    Since: API Level v2

    Returns whether the UI object / window identified by xpath can be rotated.

    Parameters
    xpath (required) - the xpath to identify the control
    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 canRotate ()

    Since: API Level v2

    Returns whether the last found UI object / window can be rotated.

    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 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 clickObject (String xpath)

    Since: API Level v2

    Will attempt to perform the Window UI Invoke pattern on the UI object / window identified by the xpath

    Parameters
    xpath (required) - the xpath to identify the control
    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 UI object / window identified by the xpath.

    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 closeWindow (String xpath)

    Since: API Level v2

    Will attempt to trigger the close event from the Window pattern on the UI object / window identified by the xpath.

    Parameters
    xpath (required) - the xpath to identify the control
    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 (String xpath)

    Since: API Level v2

    Will attempt to trigger the collapse event from the ExpandCollapse pattern for the UI object / window identifed by xpath.

    Parameters
    xpath (required) - the xpath to identify the control
    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 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 countObjects (String object, String obj_exact, String objectType)

    Since: API Level v2

    public String countObjects (String object, String obj_exact, String objectType, String fromHere)

    Since: API Level v2

    Counts the UI objects found by the given text, under the UI tree relating to the last found window item (findWindow). No references are kept to any UI objects that are found in this call.

    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.
    fromHere (optional) - "true/false" to say whether search from reference point.
    Returns
    • numerical count of windows found matching criteria.

    public String countSelectedItems (String xpath)

    Since: API Level v2

    Retrieves the count representing the number of selected items in the UI object / window identified by xpath.

    Parameters
    xpath (required) - the xpath to identify the control
    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 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 String countWindows (String window, String win_exact)

    Since: API Level v2

    Counts the windows found by the given text, in the first level from the host machine Desktop. No references are kept to any found windows.

    Parameters
    window (optional) - the text to be used to match in the parent UI element name property.
    Returns
    • numerical count of windows found matching criteria.

    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,
    • "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 dockObject (String dockLocation)

    Since: API Level v2

    Will attempt to set the docking location to dockLocation via the Docking pattern for the last found UI object / window.

    Parameters
    dockLocation (required) - the new location of the dockable UI element [bottom/fill/left/none/right/top].
    Returns
    • true - if successful. false - if an error occurred performing the action, the Dock pattern is not supported for the current UI element, or the argument was invalid

    public boolean dockObject (String xpath, String dockLocation)

    Since: API Level v2

    Will attempt to set the docking location to dockLocation via the Docking pattern for the UI object / window identified by xpath.

    Parameters
    xpath (required) - the xpath to identify the control
    dockLocation (required) - the new location of the dockable UI element [bottom/fill/left/none/right/top].
    Returns
    • true - if successful. false - if an error occurred performing the action, the Dock pattern is not supported for the current UI element, or the argument was invalid

    public boolean expandObject (String xpath)

    Since: API Level v2

    Will attempt to trigger the expand event from the ExpandCollapse pattern for the UI object / window identified by the xpath.

    Parameters
    xpath (required) - the xpath to identify the control
    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 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 findObject (String object, String obj_exact, String objectType, String index)

    Since: API Level v2

    Will perform a search for a UI element, as in the aforementioned findObject(searchText, exactMatch, objectType), but also supports a fourth argument in which the user can define that they are wishing to reference the Nth occurrence of a UI element matching the search criteria. This is intended to be applied in cases where GUI design has not provided unique identifiers for forms where a particular UI element appears multiple times with the same identifiers.

    NOTE: If the last window found was a native Microsoft window (e.g. through findWindow()), then it will perform a search for the defined object among the native Microsoft objects in the UI tree. If the last window searched for was a Java window (e.g. through findJavaWindow()), then it will search for the defined object within the java UI objects of the UI tree.

    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 (Optional) - he "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 findObjectByTooltip (String tooltipText, String obj_exact, String objectType)

    Since: API Level v2

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

    Parameters
    tooltipText (optional) - the text to be used to match in child UI element tooltip 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 findObjectID (String objectID)

    Since: API Level v2

    Will return whether it finds an object of the given automation ID under the last window. If found, it will keep a reference to both the AUT UI Object.

    Parameters
    objectID (required) - the automation ID that identifies the UI object within the given application.
    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 findObjectID (String objectID, String objectType)

    Since: API Level v2

    Will return whether it finds an object of the given automation ID under the last found window reference. If found, it will keep a reference to the UI Object itself.

    Parameters
    objectID (required) - the automation ID that identifies the UI object within the given application.

    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)

    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 boolean findObjectRelToRef (String object, String obj_exact, String objectType, String index)

    Since: API Level v2

    public boolean findWindow (String window, String win_exact, String index)

    Since: API Level v2

    finds the window by the given text, in the first level from the host machine Desktop. If found, it keeps a reference to that Window UI object and makes it the current window. Any future action and commands will be directed to this window.

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

    Parameters
    window (optional) - the text to be used to match in the parent UI element name property.
    index The index parameter defines for it to search for the Nth occurrence of that window, where N is given by index.
    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 findWindow (String window, String win_exact)

    Since: API Level v2

    finds the window by the given text, in the first level from the host machine Desktop. If found, it keeps a reference to that Window UI object and makes it the current window. Any future action and commands will be directed to this window.

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

    Parameters
    window (optional) - the text to be used to match in the parent UI element name property.
    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 findWindowByProperty (String searchText, String win_exact, String attribute, String index)

    Since: API Level v2

    Finds the window by the given text, in the first level from the host Desktop. The property of UI elements searched is defined by the attribute value. If found, it keeps a reference to that window UI object and makes it the current window. Any future action and commands will be directed to this window.

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

    Parameters
    searchText (optional) the text to be used to match in the parent UI element attribute.

    attribute (required) defines the attribute that will be searched for the given searchText value.

    index (optional) defaults to 1 if not provided. This indicates the Nth match for the search criteria should be considered the desired instance.
    Returns
    • value: true - if successful and a match was found. false - if an error occurred establishing connections or if the input arguments were invalid.

    public boolean findWindowID (String autoID, String index)

    Since: API Level v2

    Finds the primary application window by the given automation ID. Also allows the use of an index to find the N'th occurrence in the event that multiple windows are open with that same Automation ID.

    Parameters
    autoID the automation ID to search for.

    index the Nth occurrence to find. Will default to 1 if not defined.
    Returns
    • true/false to indicate success of search.

    public boolean findXPath (String xpath)

    Since: API Level v2

    A replacement for findObject(). Still requires that a findWindow() to have been successfully executed. Supported syntax is:

    • xpath=/path/path/path/...
    • xpath=//path/path/...
    • id=automation_id
    • automation_id

    Each path element can be followed by one or more qualifiers, which have the format of:

    • [@attr='value']/
    • [contains(attr,'value')]
    • [starts-with(attr,'value')]
    • [index]
    e.g.: xpath=/path/path[@attr='value'][2]

    Supported attributes (attr) are:

    • name - name property of element
    • class - classname property
    • id - automation ID
    • helptext - help text (tooltip) property of element

    All attributes searches are case insensitive. As a further qualifier, in a "xpath=" syntax, the first path element can be an identifier search of format:

    id('automation id value')

    e.g.: xpath=//id('id value')/path/path

    Supported path codes are the same as the object type list used in $_findObject() searches.

    Returns
    • true / false to indicate success in searching for element.

    public String getCenterX (String xpath)

    Since: API Level v2

    returns the center X co-ordinate of UI element identified by xpath.

    Parameters
    xpath (required) - the xpath to identify the control
    Returns
    • ui element center X co-ordinate
    Throws
    MBTException

    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 (String xpath)

    Since: API Level v2

    returns the center Y co-ordinate of UI element identified by xpath.

    Parameters
    xpath (required) - the xpath to identify the control
    Returns
    • ui element center Y 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 getClassName (String xpath)

    Since: API Level v2

    Retrieves the property containing the name for the UI object / window identified by xpath.

    Parameters
    xpath (required) - the xpath to identify the control
    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 (String xpath)

    Since: API Level v2

    Retrieves the property containing the UI Control Type for the UI object / window identified by xpath.

    Parameters
    xpath (required) - the xpath to identify the control
    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 (String xpath)

    Since: API Level v2

    Retrieves the property containing the current expanded/collapsed state for the UI object / window identified by xpath.

    Parameters
    xpath (required) - the xpath to identify the control
    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 getFontSize (String xpath)

    Since: API Level v2

    Retrieves the Font Size in the text/edit UI object idnetified by xpath.

    Parameters
    xpath (required) - the xpath to identify the control
    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 (String xpath)

    Since: API Level v2

    Retrieves the Font Type in the text/edit UI object identified by xpath.

    Parameters
    xpath (required) - the xpath to identify the control
    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 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 getFrameworkID ()

    Since: API Level v2

    Retrieves the property containing the framework ID 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 getFrameworkID (String xpath)

    Since: API Level v2

    Retrieves the property containing the framework ID for the UI object / window identified by xpath.

    Parameters
    xpath (required) - the xpath to identify the control
    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 getHeight ()

    Since: API Level v2

    returns the pixel height of the last found UI element.

    Returns
    • UI element pixel height.
    Throws
    MBTException

    public String getHeight (String xpath)

    Since: API Level v2

    returns the pixel height of the UI element identified by xpath.

    Parameters
    xpath (required) - the xpath to identify the control
    Returns
    • UI element pixel height.
    Throws
    MBTException

    public String getHelpText (String xpath)

    Since: API Level v2

    Retrieves the property containing the help text (typically the tooltip) for the UI object / window identified by xpath.

    Parameters
    xpath (required) - the xpath to identify the control
    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 getHelpText ()

    Since: API Level v2

    Retrieves the property containing the help text (typically the tooltip) 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 getInteractionState (String xpath)

    Since: API Level v2

    Retrieves the property containing the current window interaction state for the UI object / window identified by xpath.

    Parameters
    xpath (required) - the xpath to identify the control
    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 getInteractionState ()

    Since: API Level v2

    Retrieves the property containing the current window interaction state 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 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 getItemStatus (String xpath)

    Since: API Level v2

    Retrieves the property containing the item status for the UI object / window identified by xpath.

    Parameters
    xpath (required) - the xpath to identify the control
    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 getLocalisedControlType (String xpath)

    Since: API Level v2

    Retrieves the property containing the localised control type for the UI object / window identified by xpath.

    Parameters
    xpath (required) - the xpath to identify the control
    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 getLocalisedControlType ()

    Since: API Level v2

    Retrieves the property containing the localised control type 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 (String xpath)

    Since: API Level v2

    Retrieves the name for the UI object / window identified by xpath.

    Parameters
    xpath (required) - the xpath to identify the control
    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 getPropAcceleratorKey ()

    Since: API Level v2

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

    Returns
    • the accelerator key 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 getPropAcceleratorKey (String xpath)

    Since: API Level v2

    Retrieves the property containing the accelerator key for the UI object / window identified by xpath.

    Parameters
    xpath (required) - the xpath to identify the control
    Returns
    • the accelerator key 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 getPropAccessKey ()

    Since: API Level v2

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

    Returns
    • the access key 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 getPropAccessKey (String xpath)

    Since: API Level v2

    Retrieves the property containing the access key for the UI object / window identified by xpath.

    Parameters
    xpath (required) - the xpath to identify the control
    Returns
    • the access key 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 getPropAutoID ()

    Since: API Level v2

    Retrieves the automation ID property for the last found UI object / window.

    Returns
    • the automation ID property string.
    Throws
    MBTException if not supported for the current UI element.

    public String getPropAutoID (String xpath)

    Since: API Level v2

    Retrieves the automation ID property for the UI object / window identified by xpath.

    Parameters
    xpath (required) - the xpath to identify the control
    Returns
    • the automation ID property string.
    Throws
    MBTException if not supported for the current UI element.

    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 getSelectedChildName (String xpath)

    Since: API Level v2

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

    Parameters
    xpath (required) - the xpath to identify the control
    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 getSelectedItem (String index)

    Since: API Level v2

    Will attempt to set the "last found UI Object" reference to the first item that is currently selected, if the previously referenced UI object supports the Selection pattern.

    Parameters
    index (required) - the numerical index of the item, from the list of currently selected items, that should be have the current UI element handle set to.
    Returns
    • true - if successful. false - if an error occurred, the input argument was invalid, there were no items selected to get from, or the current UI element does not support the Selection pattern.

    public boolean getSelectedItem (String xpath, String index)

    Since: API Level v2

    Will attempt to set the "UI Object identified by xpath" reference to the first item that is currently selected, if the previously referenced UI object supports the Selection pattern.

    Parameters
    xpath (required) - the xpath to identify the control
    index (required) - the numerical index of the item, from the list of currently selected items, that should be have the current UI element handle set to.
    Returns
    • true - if successful. false - if an error occurred, the input argument was invalid, there were no items selected to get from, or the current UI element does not support the Selection pattern.

    public String getToggleState (String xpath)

    Since: API Level v2

    Retrieves the current toggle state for the UI object / window identified by xpath.

    Parameters
    xpath (required) - the xpath to identify the control
    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 getToggleState ()

    Since: API Level v2

    Retrieves the current toggle state 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 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 getValue (String xpath)

    Since: API Level v2

    Retrieves the value of the UI object / window identified by xpath (should not be confused with the name).

    Parameters
    xpath (required) - the xpath to identify the control
    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 getViewName (String xpath, String viewIndex)

    Since: API Level v2

    Will retrieve the name property of the view identified by viewIndex from the UI object / window identified by xpath.

    Parameters
    xpath (required) - the xpath to identify the control
    viewIndex (required) - the numerical index to the view that is being referenced.
    Returns
    • " - if an error occurred, index was out of range, or MultipleView pattern not supported by the current UI element. - name property of the referenced view.
    Throws
    MBTException

    public String getViewName (String viewIndex)

    Since: API Level v2

    Will retrieve the name property of the view identified by viewIndex from the last found UI object / window.

    Parameters
    viewIndex (required) - the numerical index to the view that is being referenced.
    Returns
    • " - if an error occurred, index was out of range, or MultipleView pattern not supported by the current UI element. - name property of the referenced view.
    Throws
    MBTException

    public String getVisualState ()

    Since: API Level v2

    Retrieves the property containing the current window visual 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 getVisualState (String xpath)

    Since: API Level v2

    Retrieves the property containing the current window visual status for the UI object / window identified by xpath.

    Parameters
    xpath (required) - the xpath to identify the control
    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 getWidth (String xpath)

    Since: API Level v2

    returns the pixel width of the UI element identified by xpath.

    Parameters
    xpath (required) - the xpath to identify the control
    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 (String xpath)

    Since: API Level v2

    returns the x-coordinate of the UI item identified by xpath.

    Parameters
    xpath (required) - the xpath to identify the control
    Returns
    • ui element left most x-coordinate.
    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 (String xpath)

    Since: API Level v2

    returns the y-coordinate of the UI element identifieid by xpath.

    Parameters
    xpath (required) - the xpath to identify the control
    Returns
    • ui element upper most y-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 String hasFocus (String xpath)

    Since: API Level v2

    Returns whether the UI object / window identified by xpath has the keyboard focus.

    Parameters
    xpath (required) - the xpath to identify the control
    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 boolean isAppPopUpPresent (String titleText, String isChildPopUp)

    Since: API Level v2

    Will check for a pop-up dialog identified by the text in the pop up title. isChildPopUp defines whether it will search for the pop up nested within the AUT UI tree, or if it will search for it as an independent window.

    Parameters
    isChildPopUp (optional) - if true, then the search will look for a window / pane type match under the AUT UI tree. If false, then the search for the pop up will search the root level of the Windows UI tree.
    Returns
    • true - if successful, and a matching pop up dialog was found. false - if no match was found, or if an error occurred.

    public String isContentElement ()

    Since: API Level v2

    Returns whether the last found UI object / window is a control element.

    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 isContentElement (String xpath)

    Since: API Level v2

    Returns whether the UI object / window identified by xpath is a control element.

    Parameters
    xpath (required) - the xpath to identify the control
    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 isDesktopIconPresent (String iconText)

    Since: API Level v2

    Searches the list of desktop icons for the first application icon that matches the text provided. Only gets a reference to indicate whether found.

    Parameters
    iconText (required) - the text to be matched, at least partially, in the desktop icon.
    Returns
    • true - if successful, and a matching desktop icon reference was found. false - if an error occurred performing the operation, or no matching desktop icon could be found.

    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 isEnabled (String xpath)

    Since: API Level v2

    Returns whether the UI object / window identified by xpath is enabled.

    Parameters
    xpath (required) - the xpath to identify the control
    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 isExpandable (String xpath)

    Since: API Level v2

    Returns whether the UI object / window identified by xpath is expandable.

    Parameters
    xpath (required) - the xpath to identify the control
    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 (String xpath)

    Since: API Level v2

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

    Parameters
    xpath (required) - the xpath to identify the control
    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 isPassword (String xpath)

    Since: API Level v2

    Returns whether the UI object / window identified by xpath is a password field (indicates if user entered text is protected).

    Parameters
    xpath (required) - the xpath to identify the control
    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 isPassword ()

    Since: API Level v2

    Returns whether the last found UI object / window is a password field (indicates if user entered text is protected).

    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 String isSelected (String xpath)

    Since: API Level v2

    Returns whether the UI object / window identified by xpath is currently selected.

    Parameters
    xpath (required) - the xpath to identify the control
    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 isTopMost ()

    Since: API Level v2

    Returns whether the last found UI object / window is at the top of the Windows z-order, i.e. whether it is in focus.

    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 isTopMost (String xpath)

    Since: API Level v2

    Returns whether the UI object / window identified by xpath is at the top of the Windows z-order, i.e. whether it is in focus.

    Parameters
    xpath (required) - the xpath to identify the control
    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 move (String xpath, String destX, String destY)

    Since: API Level v2

    Performs a move to the pixel co-ordinate location on the UI object / window identified by xpath. The top-left corner of the UI element will be moved to that pixel location.

    Parameters
    xpath (required) - the xpath to identify the control
    destX (required) - the x co-ordinate defining the pixel based location that the move should occur to.
    destY (required) - the y co-ordinate defining the pixel based location that the move should occur to.
    Returns
    • true - if successful. false - if an error occurred performing the action, the Transform pattern is not supported for the current UI element, or input arguments were invalid.

    public boolean move (String destX, String destY)

    Since: API Level v2

    Performs a move to the pixel co-ordinate location on the last found UI object / window. The top-left corner of the UI element will be moved to that pixel location.

    Parameters
    destX (required) - the x co-ordinate defining the pixel based location that the move should occur to.
    destY (required) - the y co-ordinate defining the pixel based location that the move should occur to.
    Returns
    • true - if successful. false - if an error occurred performing the action, the Transform pattern is not supported for the current UI element, or input arguments were invalid.

    public boolean openStartMenu ()

    Since: API Level v2

    Will open the Microsoft Windows Start menu. Repeating the operation will close it.

    Returns
    • true - if successful. false - if an error occurred performing the operation.

    public boolean removeSelection (String xpath)

    Since: API Level v2

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

    Parameters
    xpath (required) - the xpath to identify the control
    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 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 (String dbgMode)

    Since: API Level v2

    INETRNAL USE ONLY. Resets connection to the UIA TCP service. Use it to reestablish connection to UIA agent process. Allows caller to turn on debug mode, where user wants to run their own instance of the .Net client (hence it will not start/stop the .Net service. Returns true if a TCP connection to the agent could be established.

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

    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 resize (String xpath, String destX, String destY)

    Since: API Level v2

    Performs a resize operation, moving the resize control (typically lower-right corner of the window) to the given pixel co-ordinates. The top-left corner will remain stationary.

    Parameters
    xpath (required) - the xpath to identify the control
    destX (required) - the x co-ordinate defining the pixel based location that the resize should occur to.
    destY (required) - the y co-ordinate defining the pixel based location that the resize should occur to. #Return value: true - if successful. false - if an error occurred performing the action, the Transform pattern is not supported for the current UI element, or input arguments were invalid.

    public boolean resize (String destX, String destY)

    Since: API Level v2

    Performs a resize operation, moving the resize control (typically lower-right corner of the window) to the given pixel co-ordinates. The top-left corner will remain stationary.

    Parameters
    destX (required) - the x co-ordinate defining the pixel based location that the resize should occur to.
    destY (required) - the y co-ordinate defining the pixel based location that the resize should occur to. #Return value: true - if successful. false - if an error occurred performing the action, the Transform pattern is not supported for the current UI element, or input arguments were invalid.

    public boolean rotate (String degrees)

    Since: API Level v2

    Performs a rotate operation to the given number of degrees, on the last found UI object / window.

    Parameters
    degrees (required) - the integer number of degrees that the rotate should occur for.
    Returns
    • true - if successful. false - if an error occurred performing the action, the Transform pattern is not supported for the current UI element, or input argument was invalid.

    public boolean rotate (String xpath, String degrees)

    Since: API Level v2

    Performs a rotate operation to the given number of degrees, on the UI object / window identified by xpath.

    Parameters
    xpath (required) - the xpath to identify the control
    degrees (required) - the integer number of degrees that the rotate should occur for.
    Returns
    • true - if successful. false - if an error occurred performing the action, the Transform pattern is not supported for the current UI element, or input argument was invalid.

    public boolean scroll (String xpath, String scrollAmountX, String scrollAmountY)

    Since: API Level v2

    Emulate simultaneous horizontal and vertical scroll action on the UI object / window identified by xpath.

    Parameters
    xpath (required) - the xpath to identify the control
    scrollAmountX (optional) - will default to noamount if not provided. Defines the horizontal scroll amount for the current operation [largedecrement/smalldecrement/noamount/smallincrement/ largeincrement].
    scrollAmountY (optional) - will default to noamount if not provided. Defines the vertical scroll amount for the current operation [largedecrement /smalldecrement/noamount/smallincrement/largeincrement].
    Returns
    • true - if successful. false - if an error occurred, the input arguments were invalid, or the element does not support the Scroll pattern.

    public boolean scroll (String scrollAmountX, String scrollAmountY)

    Since: API Level v2

    Emulate simultaneous horizontal and vertical scroll action on the last found UI object / window.

    Parameters
    scrollAmountX (optional) - will default to noamount if not provided. Defines the horizontal scroll amount for the current operation [largedecrement/smalldecrement/noamount/smallincrement/ largeincrement].
    scrollAmountY (optional) - will default to noamount if not provided. Defines the vertical scroll amount for the current operation [largedecrement /smalldecrement/noamount/smallincrement/largeincrement].
    Returns
    • true - if successful. false - if an error occurred, the input arguments were invalid, or the element does not support the Scroll pattern.

    public boolean scrollHorizontal (String scrollAmount)

    Since: API Level v2

    Emulate a horizontal scroll action on the last found UI object / window.

    Parameters
    scrollAmount (optional) - will default to noamount if not provided. Defines the horizontal scroll amount for the current operation [largedecrement/smalldecrement/noamount/smallincrement/ largeincrement].
    Returns
    • true - if successful. false - if an error occurred, the input arguments were invalid, or the element does not support the Scroll pattern.

    public boolean scrollHorizontal (String xpath, String scrollAmount)

    Since: API Level v2

    Emulate a horizontal scroll action on the UI object / window identifed by xpath.

    Parameters
    xpath (required) - the xpath to identify the control
    scrollAmount (optional) - will default to noamount if not provided. Defines the horizontal scroll amount for the current operation [largedecrement/smalldecrement/noamount/smallincrement/ largeincrement].
    Returns
    • true - if successful. false - if an error occurred, the input arguments were invalid, or the element does not support the Scroll pattern.

    public boolean scrollVertical (String xpath, String scrollAmount)

    Since: API Level v2

    Emulate a vertical scroll action on the UI object / window identified by xpath.

    Parameters
    xpath (required) - the xpath to identify the control
    scrollAmount (optional) - will default to noamount if not provided. Defines the vertical scroll amount for the current operation [largedecrement /smalldecrement/noamount/smallincrement/largeincrement].
    Returns
    • true - if successful. false - if an error occurred, the input arguments were invalid, or the element does not support the Scroll pattern.

    public boolean scrollVertical (String scrollAmount)

    Since: API Level v2

    Emulate a vertical scroll action on the last found UI object / window.

    Parameters
    scrollAmount (optional) - will default to noamount if not provided. Defines the vertical scroll amount for the current operation [largedecrement /smalldecrement/noamount/smallincrement/largeincrement].
    Returns
    • true - if successful. false - if an error occurred, the input arguments were invalid, or the element does not support the Scroll pattern.

    public boolean select (String xpath)

    Since: API Level v2

    Performs a select operation on the UI object / window identified by xpath.

    Parameters
    xpath (required) - the xpath to identify the control
    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 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 selectGridItem (String xpath, String row, String column)

    Since: API Level v2

    Will attempt to trigger the expand event from the ExpandCollapse pattern for the UI object / window identified by xpath.

    Parameters
    xpath (required) - the xpath to identify the control
    row (required) - integer reference to the row of interest.
    column (required) - integer reference to the column of interest.
    Returns
    • true - if successful. false - if an error occurred performing the action, or the ExpandCollapse pattern is not supported for the current UI element.

      Will attempt to set the "last found UI Object" reference to the element from the given grid location, if the previously referenced UI object supports the GridItem pattern.true - if successful. false - if an error occurred performing the action, the Grid pattern is not supported for the current UI element, or the grid reference was invalid/out of range.

    public boolean selectGridItem (String row, String column)

    Since: API Level v2

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

    Parameters
    row (required) - integer reference to the row of interest.
    column (required) - integer reference to the column of interest.
    Returns
    • true - if successful. false - if an error occurred performing the action, or the ExpandCollapse pattern is not supported for the current UI element. Will attempt to set the "last found UI Object" reference to the element from the given grid location, if the previously referenced UI object supports the GridItem pattern.true - if successful. false - if an error occurred performing the action, the Grid pattern is not supported for the current UI element, or the grid reference was invalid/out of range.

    public boolean selectTableItem (String row, String column)

    Since: API Level v2

    Will attempt to set the "last found UI Object" reference to the element from the given grid location, if the previously referenced UI object supports the TableItem pattern.

    Parameters
    row (required) - integer reference to the row of interest.
    column (required) - integer reference to the column of interest.
    Returns
    • true - if successful. false - if an error occurred performing the action, the Table pattern is not supported for the current UI element, or the table cell reference was invalid/out of range.

    public boolean selectTableItem (String xpath, String row, String column)

    Since: API Level v2

    Will attempt to set the the UI Object reference identified by xpath to the element from the given grid location, if the previously referenced UI object supports the TableItem pattern.

    Parameters
    xpath (required) - the xpath to identify the control
    row (required) - integer reference to the row of interest.
    column (required) - integer reference to the column of interest.
    Returns
    • true - if successful. false - if an error occurred performing the action, the Table pattern is not supported for the current UI element, or the table cell reference was invalid/out of range.

    public boolean setCurrentView (String xpath, String viewIndex)

    Since: API Level v2

    Will set the visible view to that identified by viewIndex for the UI object / window identifed by xpath.

    Parameters
    xpath (required) - the xpath to identify the control
    viewIndex (required) - the numerical index to the view that is to be made visible.
    Returns
    • true - if successful. false - if an error occurred performing the action, the input argument was invalid, or MultipleView pattern is not supported for the current UI element.

    public boolean setCurrentView (String viewIndex)

    Since: API Level v2

    Will set the visible view to that identified by viewIndex for the last found UI object / window.

    Parameters
    viewIndex (required) - the numerical index to the view that is to be made visible.
    Returns
    • true - if successful. false - if an error occurred performing the action, the input argument was invalid, or MultipleView 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 setFocus (String xpath)

    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.

    Parameters
    xpath (required) - the xpath to identify the control
    Returns
    • true - if successful. false - if an error occurred, or the UI element is not focusable.

    public boolean setObjectValue (String xpath, String newValue)

    Since: API Level v2

    HAS LIMITED SUPPORT FROM MICROSOFT. Should use alternative mechanisms instead such as keystroke emulation.

    Parameters
    xpath (required) - the xpath to identify the control
    newValue (required) - the new string value that the UI element's value will be set to. If no string is provided, then the call will attempt to set the element value to an empty string.
    Returns
    • false - will always be returned as this function of the Value pattern is not supported for any element.

    public boolean setObjectValue (String newValue)

    Since: API Level v2

    HAS LIMITED SUPPORT FROM MICROSOFT. Should use alternative mechanisms instead such as keystroke emulation.

    Parameters
    newValue (required) - the new string value that the UI element's value will be set to. If no string is provided, then the call will attempt to set the element value to an empty string.
    Returns
    • false - will always be returned as this function of the Value pattern is not supported for any element.

    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 boolean setScrollIntoView ()

    Since: API Level v2

    If the last found UI object is out of the current view, then scroll into view if it supports the Scroll pattern

    Returns
    • true - if successful. false - if an error occurred, or the element does not support the ScrollItem pattern.

    public boolean setScrollIntoView (String xpath)

    Since: API Level v2

    If the UI object identified by xpath is out of the current view, then scroll into view if it supports the Scroll pattern

    Parameters
    xpath (required) - the xpath to identify the control
    Returns
    • true - if successful. false - if an error occurred, or the element does not support the ScrollItem pattern.

    public boolean setScrollPercent (String horizPercent, String vertPercent)

    Since: API Level v2

    Modify the scroll position of the scrollable element for horizontal and/or vertical scroll operations for the last found UI object / window. Will jump to the percent values of the horizontal and vertical scroll axis'.

    Parameters
    horizPercent (required) - the numerical percent (in integer value) of the scroll position to jump to on the horizontal axis.
    vertPercent (required) - the numerical percent (in integer value) of the scroll position to jump to on the vertical axis.
    Returns
    • true - if successful. false - if an error occurred, the input arguments were invalid, or the element does not support the Scroll pattern.

    public boolean setScrollPercent (String xpath, String horizPercent, String vertPercent)

    Since: API Level v2

    Modify the scroll position of the scrollable element for horizontal and/or vertical scroll operations for the UI object / window identified by xpath. Will jump to the percent values of the horizontal and vertical scroll axis'.

    Parameters
    xpath (required) - the xpath to identify the control
    horizPercent (required) - the numerical percent (in integer value) of the scroll position to jump to on the horizontal axis.
    vertPercent (required) - the numerical percent (in integer value) of the scroll position to jump to on the vertical axis.
    Returns
    • true - if successful. false - if an error occurred, the input arguments were invalid, or the element does not support the Scroll pattern.

    public boolean setSliderRange (String range)

    Since: API Level v2

    Will perform the action of modifying the last found UI object / window to have the slider set to the new value given in range.

    Parameters
    range (required) - the numerical value that the UI element should be set to. This integer value should be between the minimum and maximum values for the element's range property.
    Returns
    • true - if successful. false - if an error occurred, if the input arguments were invalid/out of range, or the element does not support the RangeValue pattern.

    public boolean setSliderRange (String xpath, String range)

    Since: API Level v2

    Will perform the action of modifying the UI object / window identified by xpath to have the slider set to the new value given in range.

    Parameters
    xpath (required) - the xpath to identify the control
    range (required) - the numerical value that the UI element should be set to. This integer value should be between the minimum and maximum values for the element's range property.
    Returns
    • true - if successful. false - if an error occurred, if the input arguments were invalid/out of range, or the element does not support the RangeValue pattern.

    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 boolean setVisualStatus (String xpath, String newStatus)

    Since: API Level v2

    Will attempt to set the Window Visual State to the value of "newStatus" for the UI object / window identified by the xpath.

    Parameters
    xpath (required) - the xpath to identify the control
    newStatus (required) - the new window visual status to set for the UI element [maximised/maximized/minimised/minimized/normal].
    Returns
    • true - if successful. false - if an error occurred performing the action, the Window pattern is not supported for the current UI element, or if the input arguments were invalid.

    public boolean setVisualStatus (String newStatus)

    Since: API Level v2

    Will attempt to set the Window Visual State to the value of "newStatus" for the last found UI object / window.

    Parameters
    newStatus (required) - the new window visual status to set for the UI element [maximised/maximized/minimised/minimized/normal].
    Returns
    • true - if successful. false - if an error occurred performing the action, the Window pattern is not supported for the current UI element, or if the input arguments were invalid.

    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 boolean toggle ()

    Since: API Level v2

    Performs a toggle event on the last found UI object / window.

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

    public boolean toggle (String xpath)

    Since: API Level v2

    Performs a toggle event on the UI object / window identified by xpath.

    Parameters
    xpath (required) - the xpath to identify the control
    Returns
    • true - if successful. false - if an error occurred performing the action, or the Toggle pattern is not supported for the current UI element.

    public void type (String xpath, String typeText)

    Since: API Level v2

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

    Parameters
    xpath (required) - the xpath to identify the control
    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 type (String typeText)

    Since: API Level v2

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

    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 UI element that has the focus.

    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 xpath, 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 UI element identified by xpath.

    Parameters
    xpath (required) - the xpath to identify the control
    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 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.

    public boolean waitForObjectID (String searchObjectID, String milliseconds)

    Since: API Level v2

    Search for the given object, identified by the provided automation ID, 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 waitForWindow (String searchWindow, String win_exact, String milliseconds)

    Since: API Level v2

    Search for the given 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
    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 waitForWindowByProperty (String searchText, String win_exact, String index, String property, String milliseconds)

    Since: API Level v2

    Search for the given window, defined by the given properties, 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.

    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 (optional) the text to be used to match in the parent UI element name property. If no text is provided, it will return a match to the first window found.

    win_exact (optional) if has a value of true, then the searchText value MUST match searched property exactly, however case is ignored. If not provided, will default to false.

    index (optional) The Nth occurrence to match, for use in cases where it is expected that more than one element will match the search criteria. Defaults to an index of '1'; the first found occurrence.

    property (optional) The name of the property field to search in with the searchText. Defaults to the name property field.

    milliseconds (required) the duration in milliseconds that the utility will continue to search for, if the UI element is not found.
    Returns
    • value: 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 waitForWindowDestroyed (String searchWindow, String win_exact, String milliseconds)

    Since: API Level v2

    Will wait until the matching window is 'destroyed', by either being closed or dismissed by a system event, or until the timeout has occurred. No UI element references will be retained.

    Parameters
    milliseconds (required) the duration in milliseconds that the utility will wait for to allow the window to be destroyed.
    Returns
    • value: true - if window is not found, or is destroyed in given time. false - if an error occurred or timeout occurred.