Window/object enumeration callback function

A callback function is a user-defined function. You pass its address to a function that supports callback functions, and then that function calls your callback function, usually multiple times, for example for each found object of some kind, providing information about the object.

 

In this topic described callback functions used with functions win, child, acc and Acc.Find. Some other functions also support callback functions in a similar way.

 

Callback functions can be used when you need to: 1. Get array of windows/objects. 2. Compare more properties of windows/objects. 3. Display list or tree. 4. Make faster by skipping some big useless objects. 5. ...

 

The callback function is called for each window/object whose all specified properties match. To call the callback function for all windows/objects, all other arguments should be empty ("" or 0). With win, to include hidden windows, insert opt hidden 1 before.

win, child

With functions win and child, callback function and its argument can be specified in propCSV, like F"callback={&Function} {aValue}". Before QM 2.3.4, used x y and flag 0x8000.

 

When searching, win and child functions enumerate top-level or child windows. The callback function is called for each matching window.

 

The callback function must begin with:

 

function# hwnd cbParam

 

hwnd - handle of the found window.

cbParam - callback function argument passed to win or child.

 

The callback function can return 1 to continue enumeration or 0 to stop (let win or child return hwnd). For example, it can test some additional window properties (rectangle, text inside, etc) and, if they match, return 0, else return 1.

 

A template is available in menu -> File -> New -> Templates.

acc, Acc.Find

Similarly, with functions acc and Acc.Find, the callback function must begin with:

 

function# Acc&a level cbParam

 

a - the found object.

level - its level in the hierarchy. If class is specified, it is level beginning from that child window. When searching in web page (flag 0x2000), it is level from the root object of the web page (DOCUMENT or PANE).

cbParam - y argument of acc.

 

The callback function can return 0 to stop searching, 1 to continue and search possible children, or 2 to continue and skip children.

 

A template is available in menu -> File -> New -> Templates.