Warning: Incorrectly used filter functions can decrease system performance and stability. To create them, you should understand everything in this topic.
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 have sense when using with triggers that "eat" trigger event ("Eat" is checked in Properties).
A macro that has a trigger (key, mouse or window) 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 as follows:
/ function# iid FILTER&f
iid is identifier of the macro that is about to run (that is, the macro (or one of macros) to which this filter function is assigned). Usually, the function returns iid to allow it, or 0 to discard.
f is variable of type FILTER, which is defined as follows:
type FILTER hwnd hwnd2 x y hit !itype !ttype !tkey !tmod !tkey2 []!tmon []!tht
hwnd - handle of top-level window. For window triggers, it is the trigger-window. For mouse click triggers - the window you click on. For other triggers - active window.
hwnd2 - handle of child window or top-level window. For hot-key triggers, it is the window that has focus (can be 0). For mouse triggers, it is the window that contains the mouse pointer.
x and y - mouse coordinates. Used only with mouse triggers.
hit - hit-test code. Used only with mouse triggers. Hit-test constants are defined in WinConstants.
Other members provide some info about the macro, and are the same as in the QMITEM.
QM 2.2.0: For mouse triggers, hwnd2 and hit sometimes can be different than in previous versions, although in most cases they are the same.
The function's return value defines what action should QM take:
| Return value | Action |
| iid | allow to run the macro. If there are more macros that have the same trigger, they 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). The filter function also can return macro name instead of id. |
| 0 | discard the trigger. If there are more macros that have the same trigger, they also will not run. |
| -1 | discard with filtering (if "Eat" is checked in the Properties dialog). Usually, -1 is used when the filter function itself starts other macro (mac). |
| -2 | skip this macro. If there are more macros that have same trigger, they possibly will run. |
| -3 | run this macro as usually. |
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 the f structure, function receives useful 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. Note that the information that the function receives in the f structure has different meaning for different types of triggers. If a filter function is designed for one type of trigger, it often cannot be used with other type of trigger.
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 commands, etc). The trigger is discarded if the filter function does not return within 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)) may not work.
All filter functions run in one special thread.
Several filter function templates are available. When you create a filter function from a template, you must edit the copied filter function: replace strings, set variables, etc. The samples2.qml file contains several sample filter functions.
When you edit a filter function and want to apply the changes, click the Save button.