From d9abdb2ecdd6eba450492cdbeb3414d862b4b04e Mon Sep 17 00:00:00 2001 From: "Peter F. Patel-Schneider" Date: Sun, 13 Mar 2022 08:28:51 -0400 Subject: [PATCH] docs: document rule Setting: condition --- docs/index.md | 7 ++++--- docs/rules.md | 40 +++++++++++++++++++++++++++++----------- 2 files changed, 33 insertions(+), 14 deletions(-) diff --git a/docs/index.md b/docs/index.md index 822e37cb..fe738ac5 100644 --- a/docs/index.md +++ b/docs/index.md @@ -147,9 +147,10 @@ for the step-by-step procedure for manual installation. "Ignore this setting". The mouse has to be reset (e.g., by turning it off and on again) before this fix will take effect. -- Many gaming mice and keyboards have both the ONBOARD PROFILES feature and the REPORT RATE feature. - On these devices changing the Polling Rate setting requires modifying a setting in - the ONBOARD PROFILES feature, which can modify how the device works. Changing the +- Many gaming mice and keyboards have the ONBOARD PROFILES feature. + This feature can override other features, including polling rate and key lighting. + On these devices, the Polling Rate setting turns off + the ONBOARD PROFILES feature which then changes how the device works. Changing the Polling Rate setting to "Ignore this setting" (see above) prevents Solaar from modifying the ONBOARD PROFILES feature. The device has to be reset (e.g., by turning it off and on again) before this fix will take effect. diff --git a/docs/rules.md b/docs/rules.md index fe58dc65..673a5b4c 100644 --- a/docs/rules.md +++ b/docs/rules.md @@ -66,26 +66,44 @@ A Or condition is true if its last evaluated component evaluates to a true value. `And` conditions take a sequence of components are evaluted the same as rules. -`Process` conditions are true if the process for focus input window -or the window's Window manager class or instance name starts with their string argument. -`MouseProcess` conditions are true if the process for the window under the mouse -or the window's Window manager class or instance name starts with their string argument. `Feature` conditions are if true if the name of the feature of the current notification is their string argument. `Report` conditions are if true if the report number in the current notification is their integer argument. -`Modifiers` conditions take either a string or a sequence of strings, which -can only be `Shift`, `Control`, `Alt`, and `Super`. -Modifiers conditions are true if their argument is the current keyboard -modifiers. -`Key` conditions are true if the Logitech name of the last diverted key or button down is their + +`Key` conditions are true if the Logitech name of the last diverted key or button pressed is their string argument. Alternatively, if the argument is a list `[name, action]` where `action` is either `'pressed'` or `'released'`, the key down or key up events of `name` argument are matched, respectively. Logitech key and button names are shown in the `Key/Button Diversion` setting. Some keyboards have Gn, Mn, or MR keys, which are diverted using the 'Divert G Keys' setting. + +`Modifiers` conditions take either a string or a sequence of strings, which +can only be `Shift`, `Control`, `Alt`, and `Super`. +Modifiers conditions are true if their argument is the current keyboard +modifiers. + +`Process` conditions are true if the process for focus input window +or the window's Window manager class or instance name starts with their string argument. +`MouseProcess` conditions are true if the process for the window under the mouse +or the window's Window manager class or instance name starts with their string argument. + +`Setting` conditions checks the value of a Solaar setting on a device. +`Setting` conditions take three or four arguments, depending on the setting: +the Serial number or Unit ID of a device, as shown in Solaar's detail pane, +or null for the device that initiated rule processing; +the internal name of a setting (which can be found from solaar config ); +one or two arguments for the setting. +For settings that use keys or buttons as an argument the Logtech name can be used +as shown in the Solaar main window for these settings, +or the numeric value for the key or button. +For settings that use gestures as an argument the internal name of the gesture is used, +which can be found in the GESTURE2_GESTURES_LABELS structure in lib/logitech_receiver/settings_templates. +For settings that need one of a set of names as an argument the name can be used or its internal integer value, +as used in the Solaar config file. + `Test` and `TestBytes` conditions are true if their test evaluates to true on the feature, report, and data of the current notification. -Test conditions can return a number instead of a boolean. +`TestBytes` conditions can return a number instead of a boolean. `TestBytes` conditions consist of a sequence of three or four integers and use the first two to select bytes of the notification data. @@ -95,7 +113,7 @@ with its third element is non-zero. The value of these test conditions is the result of the and. Four-element `TestBytes` conditions are true if the selected bytes form a signed integer between the third and fourth elements. -The value of these test condition is the signed value of the selected bytes +The value of these conditions is the signed value of the selected bytes if that is non-zero otherwise True. `Test` conditions are mnemonic shorthands for meaningful feature,