Find accessible object; evaluate 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.

 

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 - string used to identify the object. Usually it is text that is displayed in the object or before the object. Not all objects have name. By default, name can be partial and is case insensitive. Empty string ("") matches any name.

role - object type. Can be numeric ROLE_SYSTEM_x constant (e.g., ROLE_SYSTEM_PUSHBUTTON), or string that matches the part of a constant that follows ROLE_SYSTEM_ (e.g., "PUSHBUTTON"). It also can be true role string (e.g., "push button")(QM2.1.8.5). Default: 0 or "" (any).

window - container window (top-level or child). If omitted or "" - currently active window. Searches only in the first found matching window. With acc, it also can be an accessible object (Acc or IAccessible).

class - class name of immediate container window. Also can include id. Full syntax is "[id=digits] [classname]", where digits is id, and both parts are optional. Usually this window is a child window of the window. Default: "" (any). Not used if window is accessible object.

value - additional information. String. For example, value of an edit control is it's text; value of a link is its URL; value of an outline (treeview) item is it's level within the hierarchy. Most objects don't have a value. By default, value can be partial and is case insensitive. Empty string ("") matches any value.

flags:

1

name must match exactly or may contain 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.

  • Alternatively, use $ character at the beginnig.
  • Case sensitive, unless contains (?i).
4

value must match exactly or may contain wildcard characters.

  • String "*" matches objects without value.
  • Without this flag, value can be partial.
  • This flag cannot be used with flag 8.
8 value is regular expression.
  • Alternatively, use $ character at the beginnig.
  • Case sensitive, unless contains (?i).
16

Search invisible objects.

32

Search useless objects: scrollbar, grip, invisible titlebar, separator.

64

Search only immediate children.

  • Can be useful when window is accessible object.
128 (acc only)

Search in reverse order (starting from bottom).

  • Applied only to objects in the class child window. Finds the child window not in reverse order.
0x100

x and y are coordinates in window client area.

  • Ignored if window is accessible object. Then must be screen cordinates.
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.
0x1000 (acc only) Error if object not found.
0x2000 (acc only)

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, Opera, Thunderbird.
0x4000 QM 2.3.3. value is CSV containing various properties. Documented in function Acc.Find.
0x8000

Use callback function.

x, y - the object must be at this point in the window (window) or screen (flag 0x200). Default: 0 0 (any). For syntax1, it must be top-left corner coordinates. For syntax2, acc gets object that contains the point.

navig - post-navigation string. See 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 0 (constant) - 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 evaluates accessible object properties, and returns 1 if they match, or 0 if not. If window is omitted or 0 (constant), container window is not evaluated.

 

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