docs: document changed Smart Shift and Mouse Gestures processing

docs/capabilities.md

@@ -150,10 +150,10 @@ the sensitivity (DPI) of the mouse by pressing the button and moving the mouse l
 Other mice (such as the MX Master 3) don't have a button specific for this purpose
 but have buttons that can be used for it.
 
-The `DPI Sliding Adjustment` setting,
-which is only present on devices that support this capability in Solaar,
-assigns a button to adjust sensitivity.
-Pressing the button when the button is diverted causes the mouse pointer to stop moving.
+The `Key/Button Diversion` setting can assign buttons to adjust sensitivity by setting the value for the button to `Sliding DPI`.
+This capability is only present if the device supports changing the DPI in this way.
+
+Pressing a button when it is set to `Sliding DPI` causes the mouse pointer to stop moving.
 When the button is released a new Sensitivity (DPI) value is applied to the mouse,
 depending on how far right or left the mouse is moved.   If the mouse is moved only a little bit
 the previous value that was set is applied to the mouse.
@@ -165,15 +165,13 @@ Some mice (such as the MX Master 3) have a button that is supposed to be used to
 create up/down/left/right mouse gestures.  Other mice (such as the MX Vertical) don't
 have a button specific for this purpose but have buttons that can be used for it.
 
-The `Mouse Gestures` setting,
-which is only present on devices that support this capability in Solaar,
-assigns a button for mouse gestures.
-Pressing the button when the button is diverted causes the mouse pointer to stop moving.
-When the button is released a `MOUSE_GESTURE` notification with the total mouse movements
-while the button was pressed are sent to the Solaar rule system.
+The `Key/Button Diversion` setting can assign buttons to initiate mous gestures by setting the value for the button to `Mouse Gestures`.
+This capability is only present if the device can support it.
 
-Mouse gesture conditions in Solaar rules can be used to detect these notifications.
-For more information on mouse gesture rules conditions see
+Pressing a button when it is set to `Mouse Gestures` causes the mouse pointer to stop moving.
+When the button is released a `MOUSE_GESTURE` notification with the mouse movements and diverted key presses
+is sent to the Solaar rule system so that rules can detect these notifications.
+For more information on Mouse Gestures rule conditions see
 [the rules page](https://pwr-solaar.github.io/Solaar/rules).
 
 ## System Tray

docs/rules.md

@@ -144,12 +144,14 @@ A `thumb_wheel_down` test is the rotation amount of a `THUMB WHEEL` downward rot
 same but for `LOWRES WHEEL` and `HIRES WHEEL`.
 `True` and `False` tests return True and False, respectively.
 
-`Mouse Gesture` conditions are true if the actions taken while the mouse's 'Gesture' button is held match the configured list when the 'Gesture' button is released.
-The available actions are `Mouse Up`, `Mouse Down`, `Mouse Left`, `Mouse Right`, `Mouse Up-left`, `Mouse Up-Right`, `Mouse Down-left`, `Mouse Down-right`, and buttons that are diverted.
-An example would be mapping `Mouse Up` -> `Mouse Up`. To perform this gesture, you would hold down the 'Gesture' button, move the mouse upwards, pause momentarily, move the mouse upwards, and release the 'Gesture' button.
-Another example would be mapping `Back Button` -> `Back Button`. With this one, you would hold down the 'Gesture' button, double-tap the 'Back' button, and then release the 'Gesture' button.
-Mouse movements and buttons can be mixed and chained together however you like.
-It's possible to create a `No-op` gesture by clicking 'Delete' on the initial Action when you first create the rule. This gesture will trigger when you simply click the 'Gesture' button.
+`Mouse Gesture` conditions are true if the actions (mouse movements and diverted key presses) taken while a mouse gestures button is held down match the arguments of the condition.
+Mouse gestures buttons can be set using the 'Key/Button Diversion' setting, by changing the value to `Mouse Gestures'.
+The arguments of a Mouse Gesture condition can be a direction, i.e., `Mouse Up`, `Mouse Down`, `Mouse Left`, `Mouse Right`, `Mouse Up-left`, `Mouse Up-Right`, `Mouse Down-left`, or `Mouse Down-right`, or the Logitech name of a key.
+If the first argument is the Logitech name of a key then that argument is matched against the button that was held down to initiate mouse gesture processing.
+So, for example, a Mouse Gesture condition of `Mouse Up` -> `Mouse Up` would match pressing any Mouse Gestures button, moving the mouse upwards, pausing momentarily, moving the mouse upwards again, and releasing the button.
+The condition `Smart Shift` -> 'Mouse Down` -> `Back Button` would match pressing the Smart Shift button (provided that it is a Mouse Gestures button!) moving the mouse downwards, clicking the Back button (provided that it is diverted!), and then releasing the Smart Shift button.
+Directions and buttons can be mixed and chained together however you like.
+It's possible to create a `No-op` gesture by clicking 'Delete' on the initial Action when you first create the rule. This gesture will trigger when you simply click a Mouse Gestures button.
 
 `Setting` conditions check device settings of devices, provided the device is on-line.
 The first arguments to the condition are the Serial number or Unit ID of a device, as shown in Solaar's detail pane,

lib/logitech_receiver/settings_templates.py

@@ -449,7 +449,7 @@ class ReprogrammableKeys(_Settings):
     name = 'reprogrammable-keys'
     label = _('Key/Button Actions')
     description = (
-        _('Change the action for the key or button.') + '\n' +
+        _('Change the action for the key or button.') + '  ' + _('Overridden by diversion.') + '\n' +
         _('Changing important actions (such as for the left mouse button) can result in an unusable system.')
     )
     feature = _F.REPROG_CONTROLS_V4