Warning: Incorrectly used filter functions can decrease system performance and stability.
Filter functions usually are used to narrow trigger scope. A filter function is called when QM is about to start the macro to which the filter function is assigned. Depending on filter function's return value, QM starts macro, or not, or starts other macro. You can make the macro specific to a certain window, window part, control, mouse pointer position, time, whatever. Filter functions are especially useful with triggers that "eat" trigger event ("Eat" is checked in Properties).
A macro that has a trigger (key, mouse, window or autotext) can have a filter function. To assign a filter function, use the Filter Function dialog, which appears when you click the FF button in the Properties dialog. To use an existing filter function, click "Use" and select one from the drop-down list. To create new, click "New" (or click "Copy" and select an existing filter function) and optionally type the name for the new filter function. Alternatively, you can specify a filter function directly in the Trigger field on the toolbar.
A filter function is an usual user-defined function. You must write code for it. It must begin with:
/ function# iid FILTER&f
iid - identifier of the macro that is about to run (a macro to which this filter function is assigned).
f - variable of type FILTER:
type FILTER hwnd hwnd2 x y hit !itype !ttype !tkey !tmod !tkey2 []!tmon []!tht
hwnd - handle of top-level window.
hwnd2 - handle of child window or top-level window.
x, y - mouse coordinates. Used only with mouse triggers.
hit - hit-test code of mouse trigger. Hit-test codes documented in WM_NCHITTEST page.
Other members provide some info about the macro. The same as in QMITEM.
Return values for key, mouse and window triggers:
| Return value | Action |
|---|---|
| iid | run the macro. Other macros that have same trigger will not run. |
| id or name of some other macro | run other macro. For example, the filter function can select a macro from a list of macros that should run from one main trigger depending on other conditions (active window, mouse pointer position, etc). |
| 0 | don't run. Other macros that have same trigger also will not run. |
| -1 | don't run, but eat the trigger event (if "Eat" is checked in the Properties dialog). Usually -1 is used when the filter function itself starts other macro (mac). |
| -2 | don't run. Other macros that have same trigger possibly will run. |
Return values for autotext triggers:
| Return value | Action |
|---|---|
| iid | run the autotext list item. Other autotext lists that have same trigger will not run. |
| 0 or -1 | don't run. Other autotext lists that have same trigger also will not run. |
| -2 | don't run. Other autotext lists that have same trigger possibly will run. |
Possible various variants of usage of filter functions. Often a filter function is specific to a single macro, but it also can be assigned to several macros that have different triggers. If several macros must have the same trigger, but run e.g. in different windows, assign the trigger and filter function to one of them (or to the filter function itself); the filter function evaluates conditions and depending on results allows starting different macros.
In iid and f variables the function receives information about the trigger. To evaluate it, you can use functions sel, wintest, getwintext, getwinclass, GetWinId, GetWinStyle, GetWinXY, child, childtest, id, qmitem, getmacro and other. Information that the function receives in f has different meaning for different trigger types (keyboard, mouse, etc). If a filter function is created for one trigger type, often it cannot be used with other trigger types.
While filter function runs, other application waits and cannot process user input. Therefore filter functions must be as fast as possible. They must only evaluate conditions, also can start other macros (mac), but itself MUST NOT CONTAIN MACRO COMMANDS (such as mouse, window, wait, dialogs, etc). Max allowed time is 1 second. You can use perf to measure the time.
Filter function runs while the target application is processing some input event. For this reason, some code that communicates with that window (e.g., acc(mouse)) in some cases may not work.
All filter functions of key, mouse and window triggers run in one special thread. All filter functions of text triggers run in QM main thread.
If a filter function is disabled, macros to which it is assigned run like without a filter function.
Several filter function templates are available.
When you edit a filter function, to apply the changes click Save or Compile button.