Acc acc(name [role] [window] [class] [value] [flags] [x y] [navig] [waits] [matchindex]) int acctest(object name [role] [window] [class] [value] [flags] [x y])
Acc acc(x y [window] [flags2]) int acctest(object x y [window] [flags2])
Acc acc(mouse) int acctest(object mouse)
Acc acc(hwnd) int acctest(object hwnd)
Acc acc int acctest(object)
Acc acc(object navig)
Acc acc(htmlelement)
name - string, used to identify object. For example, text on a button control is its name, while the name for edit control can be static text that immediately precedes the control in the tabbing order. Not all objects have name. By default, name can be partial and is case insensitive. Empty string ("") matches any name.
role - type of object. 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). Although role is optional part, you should always use it, unless you are using callback function to enumerate all objects.
window - container window (top-level or child). If omitted or "" - currently active window. With function acc, it also can be an accessible object (QM 2.1.8.6). The function searches only in the first found matching window.
class - class name of immediate container window. Usually this window is a child window of the window. The string also can include a child id. Full syntax is "[id=digits] [classname]", where digits is child id, and both parts are optional. Default: "" (any). Not used if window is accessible object.
value - additional information. String. For example, value of edit control is it's text; value of link is URL; value of outline (treeview) item is it's level within hierarchy. Most objects don't have a value. This part also can be object's description (flag 0x400). By default, value can be partial and is case insensitive. Empty string ("") matches any value.
flags - combination of values listed below. Default: 0.
| 1 | name must match exactly or may contain wildcard characters (*?). String "*" matches objects with no name. Without this flag, name can be partial. This flag cannot be used with flag 2. |
| 2 | name is regular expression. Not necessary if name begins with $ (but not $$). Case sensitive, unless contains (?i). |
| 4 | value must match exactly or may contain wildcard characters. This flag cannot be used with flag 8. |
| 8 | value is regular expression. Not necessary if value begins with $ (but not $$). Case sensitive, unless contains (?i). |
| 16 | search invisible objects. Not necessary if role specifies menuitem or menupopup. |
| 32 | search useless objects (scrollbar, grip, invisible menubar and titlebar, separator). Filtering also depends on role. To search all object without any filters, set flags 16 and 32, and don't use role. |
| 64 | search only immediate child objects or elements. |
| 128 | search in reverse order (starting from bottom) (acc only). |
| 0x100 | x and y are coordinates in window client area. If window is IAccessible interface pointer, x and y must be screen cordinates, regardless of this flag. |
| 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. State constant names begin with STATE_SYSTEM_. |
| 0x1000 | throw error if object not found (acc only). |
| 0x8000 |
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, retrieves an object that contains the point.
navig - post-navigation string. See remarks.
waits - max number of seconds to wait for the object. Does not wait for window. Default: 0.
matchindex (QM 2.2.0) - 1-based index of matched object in the window (window). Use when there are several objects (in the window) that match other properties (name, role, class, value, flags, x, y). If omitted, 0 or 1, will find first matching object. Using matchindex 2 will find next matching object, and so on.
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).
object - accessible object. Variable of Acc type.
htmlelement - html element. Variable of Htm or IHTMLElement type.
Function acc finds an accessible object within window window. The type of the return value is Acc. If object not found, returns empty object (to check, use if(a.a=0) ...) or generates error (flag 0x1000). Error if window does not exist.
Syntax1: Finds accessible object whose name and other properties match the specified properties.
Syntax2: Finds 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: Finds object from mouse pointer position.
Syntax4: Returns accessible object for window (hwnd) itself. Window can be child or top-level. To get window handle from accessible object, use child function.
Syntax5: Returns accessible object that has focus.
Syntax6: Returns adjacent object.
Syntax7: Returns accessible object that matches html element htmlelement.
Function 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 object and insert this function, use the Find Accessible Object dialog.
The Acc type has two member variables: a (pointer to IAccessible interface of the object) and elem (0, or some integer value used to identify smaller objects in some objects). If object is not found a is 0.
The navig string can be used to get an adjacent object. After acc finds the specified object, it navigates from the found object (or object, in case of syntax6) to another object according to the navig string. In the navig string, you can use one or more of the following words or abbreviations:
| up, down, left, right | spatial navigation. |
| next, previous | logical navigation. |
| parent | navigate to parent object. |
| first, last | navigate to first or last child object. |
| child | navigate to the specified child object. To specify child object, append 1-based child index (1 is the default). This usually is faster than using multiple next. For example, "child5" usually does the same job as "first next4", but is faster. |
Each string can be followed by a number that specifies the number of navigation operations in the specified direction. Post-navigation is useful when wanted object, for example, does not have neither name nor value (e.g., empty edit field). Then you can specify an adjacent (more descriptive) object, and use navig to get the object you actually need. Post-navigation also can be used to reduce search time. To view relationship 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" (from found object, navigate to its parent, then navigate to next object two times, get 15-th child, get first child).
A window can have thousands of accessible objects, although often many of them are invisible. Several objects can have same name and other properties. To improve performance and minimize risk to find wrong object, you should always use role, window and class. One drawback of Active Accessibility - finding an object is much slower than finding child window (id, child). For some applications and large web pages, it is normal to spend several seconds while searching. 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 object in web page), and use post-navigation to navigate to desired object. If object is in bottom, you can try "Search in reverse order" option. With web pages in Internet Explorer and IE-based browsers, you can use function htm (find html element) instead of acc.
Acc a=acc("Google Search" "PUSHBUTTON" " Internet Explorer" "Internet Explorer_Server" "" 0x1001) a.DoDefaultAction