Find Method

Class

AnyWin class.

Action

Finds an object specified by an XPath locator.

Availability

This function is supported only in scripts that use the Open Agent and dynamic object recognition.

Syntax

window.Find(locator [, options])

Variable	Description
`locator`	The XPath locator or object map identifier. Defines which object to find. STRING.
`options`	Optional: Specifies options for the Find operation. Use to override the default timeout value or to specify whether a `E_WINDOW_NOT_FOUND` exception is thrown if no object is found (default) or if NULL is returned if no object is found. FINDOPTIONS.

Notes

Returns the first object that matches the locator. As long as no object matches the locator, the agent tries to find an object until the default timeout, which is specified by the option OPT_WINDOW_TIMEOUT, expires. If no object is found an E_WINDOW_NOT_FOUND exception is thrown. In the UI, you can set the OPT_WINDOW_TIMEOUT option in the Timing tab of the Agent Options dialog box. The option is called Window timeout (seconds). The default value for the option is 5 seconds.

An E_INVALID_XPATH exception is thrown if the XPath locator is syntactically incorrect. You can record the XPath query string if necessary.

The Find method returns a handle for each matching object, which is only valid as long as the object in the application exists. For example, a handle to a button in a dialog box is invalid once the dialog box is closed. Any attempts to execute functions on this handle after the dialog box closes will throw an E_WINDOW_INVALIDATED exception. Since it is a common practice to design test cases to be independent of each other and of order of execution, get new handles for the objects in each test case. In order not to duplicate the XPath query, helper functions can be created. For example:

[-] WINDOW getOkButton(WINDOW dialog)
	[ ] return dialog.find(".//PushButton[@caption = 'Ok']")

When using object maps, the corresponding object map identifier is ok, and the previous code samples look like the following:

[-] WINDOW getOkButton(WINDOW dialog)
	[ ] return dialog.Find("Ok")

Example 1

WINDOW informationDialog = Desktop.Find("//Dialog[@caption=’Information’]")
WINDOW okButton = informationDialog.Find("//PushButton[@caption='ok']")
okButton.Click()

When using object maps, the corresponding object map identifiers are Information and ok, and the previous code samples look like the following:

WINDOW informationDialog = Desktop.Find("Information")
WINDOW okButton = informationDialog.Find("ok")
okButton.Click()

Example 2

To find the dialog Information with a timeout of three seconds, and to return NULL if the dialog is not found, instead of throwing an E_WINDOW_NOT_FOUND exception, you can use code that is similar to the following:

WINDOW informationDialog = Desktop.Find("//Dialog[@caption=’Information’]", {3,FALSE})

When using object maps, if the corresponding object map identifier is Information, the previous code samples look like the following:

WINDOW informationDialog = Desktop.Find("Information", {3,FALSE})