Find accessible object; compare properties

Note: In QM 2.3.3 and later, there are functions of Acc class that replace acc/acctest. They are simpler to use. Use acc/acctest if you want to make the macro compatible with older QM versions. Also, here you can find more info than in Acc.Find help (it calls acc).

 

Syntax1 - get specified object

Acc acc(name [role] [window] [class] [value] [flags] [x y] [navig] [waitS] [matchindex])
int acctest(object name [role] [window] [class] [value] [flags] [x y])

 

Syntax2 - get object from point

Acc acc(x y [window] [flags2])
int acctest(object x y [window] [flags2])

 

Syntax3 - get object from mouse pointer position

Acc acc(mouse)
int acctest(object mouse)

 

Syntax4 - get object from window handle

Acc acc(hwnd)
int acctest(object hwnd)

 

Syntax5 - get focused object

Acc acc
int acctest(object)

 

Syntax6 - get adjacent object

Acc acc(object navig)

 

Syntax7 - get object from html element

Acc acc(htmlelement)

 

Parameters

name - object name.

role - object type. Supported are all role types that are returned by Acc.Role:

window - container window (top-level or child).

class - class name of direct container window. Usually it is a child window of the window.

value - object value.

flags:

1

name is full or with wildcard characters (*?).

  • String "*" matches objects without name.
  • Without this flag, name can be partial.
  • This flag cannot be used with flag 2.
2 name is regular expression.
  • Case sensitive, unless contains (?i).
4

value is full or with wildcard characters.

  • String "*" matches objects without value.
8 value is regular expression.
  • Case sensitive, unless contains (?i).
16

Search invisible objects too (and their descendants).

32

Search useless objects too (and their descendants): scrollbar, grip, invisible titlebar, separator.

64

Search only direct children.

  • Can be useful when window is accessible object.
128

Search in reverse order (starting from bottom).

  • Applied only to objects in the class child window. Finds the child window not in reverse order.
  • This flag is not used with acctest.
0x1000

Error if object not found.

  • This flag is not used with acctest.
0x2000

QM 2.3.3. Search only in web page, and only in the visible one (even if flag 16).

  • Makes acc faster, especially with browsers other than IE (or IE-based).
  • class is ignored.
  • window must be the browser window. Cannot be a control or accessible object.
  • This flag can be used with IE, IE-based browsers, Firefox, Chrome, Thunderbird.
  • QM 2.3.4: fixed bug: in browsers other than IE, does not find the root web page object if role is not "DOCUMENT".
  • This flag is not used with acctest.
0x4000 QM 2.3.3. value is CSV containing various properties. Documented in function Acc.Find.
0x10000

QM 2.4.3. This flag removes a 1-2 s delay in some web pages in Firefox.

  • Use with pages where even finding DOCUMENT takes 1-2 s. It happens if the DOCUMENT always has "busy" state. Only with flag 0x2000.
  • For reliability also use waitS (see below).

Obsolete flags

These flags are not used with Acc class functions. Now these properties can be specified in CSV (see flag 0x4000).

0x100

x and y are coordinates in window client area.

  • Ignored if window is accessible object. Then must be screen coordinates.
0x200 x and y are coordinates in the screen.
0x300 x and y are coordinates in the work area of the screen.
0x400 value is description.
0x800

Check object's state.

  • x must be state.
  • y must be state mask (state flags that must match must be 1, others - 0). If y is -1 (0xFFFFFFFF), state must match exactly.
  • Object state constants are documented in MSDN. Example: STATE_SYSTEM_READONLY.
0x8000

Use callback function.

 

x, y - the object must be at this point in the window. Default: 0 0 (any).

navig - post-navigation string. Read in Remarks.

waitS - time (seconds) to wait for the object in the window.

matchindex (QM 2.2.0) - 1-based index of matched object in the window. Use when there are several objects (in the window) that match other properties (name, role, class, value, flags, x, y).

 

flags2 - combination of values listed below. Default: 0.

1 x and y are coordinates in client area of window.
2 x and y are coordinates in the screen.
3 x and y are coordinates in the work area of the screen.

hwnd - handle of some window (child or top-level).

mouse - literal mouse.

object - accessible object. Variable of Acc type.

htmlelement - html element. Variable of Htm or IHTMLElement type.

 

Remarks

Syntax1: Finds accessible object whose name and other properties match the specified properties.

 

Syntax2: Gets object from the specified point in the window. If window is omitted or "" - active window. If window is literal 0 - any window (x and y are screen coordinates).

 

Syntax3: Gets object from mouse pointer position.

 

Syntax4: Gets accessible object of window (hwnd) itself. Window can be child or top-level. To get window handle from accessible object, use child function.

 

Syntax5: Gets the focused accessible object.

 

Syntax6: Gets adjacent object.

 

Syntax7: Gets accessible object that matches html element htmlelement.

 

acc should be assigned to a variable of type Acc. If object not found, the variable will be empty. You can use code like if(a.a=0) out "not found". Or use flag 0x1000 (error if not found) and err. Always error if window does not exist.

 

acctest compares accessible object properties with the specified, and returns 1 if they match, or 0 if not. If window is omitted or literal 0, does not compare it.

 

To capture accessible objects and create code, use the "Find Accessible Object" dialog. Starting from QM 2.3.3, it inserts code like Acc a.Find(...). The Find function calls acc, therefore all its parameters are similar.

 

The navig string can be used to get an adjacent object. Let's call it post-navigation. After acc finds the specified object, it navigates from the found object to another object according to the navig string. In the string you can use one or more of the following words or abbreviations:

up, down, left, right Spatial navigation. Most objects don't support it.
next, previous Next or previous sibling.
parent Parent.
first, last First or last child.
child Child x. To specify child object, append 1-based child index.

Each word can be followed by a number that specifies the number of navigation operations in the specified direction. For example, use "next3" instead of "next next next".

 

Post-navigation is useful when the wanted object cannot be uniquely identified (does not have name, etc). Then you can find an adjacent object, and use navig to get the object you actually need. Post-navigation also can be used to reduce search time. To view relationships between objects, use the "Find accessible object" dialog. Navigation does not always work in all directions. Sometimes, invisible objects are skipped (except with parent and child). Example of navig string: "pa n2 c15 f" (get parent, get next object two times, get 15-th child, get first child).

 

acc is much slower than similar functions id and child. If window or web page has stable structure (hierarchy), post-navigation can significantly reduce search time. You can specify some object in top of hierarchy (e.g., PANE or DOCUMENT object in web page), and use post-navigation to navigate to the object you need.

 

acc is mostly used with web pages. There are two faster alternatives. With Internet Explorer and IE-based browsers you can use function htm (find html element). With Firefox and Chrome try to check 'as Firefox node' in the 'Find accessible object' dialog.

 

Example

Acc a=acc("Google Search" "PUSHBUTTON" " Internet Explorer" "Internet Explorer_Server" "" 0x1001)
a.DoDefaultAction