diff options
| -rw-r--r-- | doc/Makefile.am | 1 | ||||
| -rw-r--r-- | doc/middle-button-emulation.dox | 34 | ||||
| -rw-r--r-- | doc/page-hierarchy.dox | 1 | ||||
| -rw-r--r-- | src/libinput.h | 23 |
4 files changed, 43 insertions, 16 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am index e033229..88877d4 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -13,6 +13,7 @@ header_files = \ $(srcdir)/device-configuration-via-udev.dox \ $(srcdir)/faqs.dox \ $(srcdir)/gestures.dox \ + $(srcdir)/middle-button-emulation.dox \ $(srcdir)/normalization-of-relative-motion.dox \ $(srcdir)/palm-detection.dox \ $(srcdir)/page-hierarchy.dox \ diff --git a/doc/middle-button-emulation.dox b/doc/middle-button-emulation.dox new file mode 100644 index 0000000..16ec476 --- /dev/null +++ b/doc/middle-button-emulation.dox @@ -0,0 +1,34 @@ +/** +@page middle_button_emulation Middle button emulation + +Middle button emulation provides users with the ability to generate a middle +click even when the device does not have a physical middle button available. + +When middle button emulation is enabled, a simultaneous press of the left +and right button generates a middle mouse button event. Releasing the +buttons generates a middle mouse button release, the left and right button +events are discarded otherwise. + +The middle button release event may be generated when either button is +released, or when both buttons have been released. The exact behavior is +device-dependent, libinput will implement the behavior that is most +appropriate to the physical device. + +The middle button emulation behavior when combined with other device +buttons, including a physical middle button is device-dependent. +For example, @ref clickpad_softbuttons provides a middle button area when +middle button emulation is disabled. That middle button area disappears +when middle button emulation is enabled - a middle click can then only be +triggered by a simultaneous left + right click. + +Some devices provide middle mouse button emulation but do not allow +enabling/disabling that emulation. Likewise, some devices may allow middle +button emulation but have it disabled by default. This is the case for most +mouse-like devices where a middle button is detected. + +libinput provides libinput_device_config_middle_emulation_set_enabled() to +enable or disable middle button emulation. See @ref faq_configure_wayland +and @ref faq_configure_xorg for info on how to enable or disable middle +button emulation in the Wayland compositor or the X stack. + +*/ diff --git a/doc/page-hierarchy.dox b/doc/page-hierarchy.dox index 4be6109..092178e 100644 --- a/doc/page-hierarchy.dox +++ b/doc/page-hierarchy.dox @@ -17,6 +17,7 @@ @page pointers Mice, Trackballs, etc. - @subpage motion_normalization +- @subpage middle_button_emulation @page tablets Graphics Tablets diff --git a/src/libinput.h b/src/libinput.h index 83e58b6..397c6f6 100644 --- a/src/libinput.h +++ b/src/libinput.h @@ -4569,8 +4569,7 @@ enum libinput_config_middle_emulation_state { * @ingroup config * * Check if middle mouse button emulation configuration is available on this - * device. See libinput_device_config_middle_emulation_set_enabled() for - * details. + * device. See @ref middle_button_emulation for details. * * @note Some devices provide middle mouse button emulation but do not allow * enabling/disabling that emulation. These devices return zero in @@ -4597,19 +4596,7 @@ libinput_device_config_middle_emulation_is_available( * button event. Releasing the buttons generates a middle mouse button * release, the left and right button events are discarded otherwise. * - * The middle button release event may be generated when either button is - * released, or when both buttons have been released. The exact behavior is - * device-dependent. - * - * The middle button emulation behavior when combined with other device - * buttons, including a physical middle button is device-dependent. - * For example, @ref clickpad_softbuttons provides a middle button area when - * middle button emulation is disabled. That middle button area disappears - * when middle button emulation is enabled - a middle click can then only be - * triggered by a simultaneous left + right click. - * - * @note Some devices provide middle mouse button emulation but do not allow - * enabling/disabling that emulation. + * See @ref middle_button_emulation for details. * * @param device The device to configure * @param enable @ref LIBINPUT_CONFIG_MIDDLE_EMULATION_DISABLED to @@ -4632,6 +4619,8 @@ libinput_device_config_middle_emulation_set_enabled( * @ingroup config * * Check if configurable middle button emulation is enabled on this device. + * See @ref middle_button_emulation for details. + * * If the device does not have configurable middle button emulation, this * function returns @ref LIBINPUT_CONFIG_MIDDLE_EMULATION_DISABLED. * @@ -4656,7 +4645,9 @@ libinput_device_config_middle_emulation_get_enabled( * @ingroup config * * Check if configurable middle button emulation is enabled by default on - * this device. If the device does not have configurable middle button + * this device. See @ref middle_button_emulation for details. + * + * If the device does not have configurable middle button * emulation, this function returns @ref * LIBINPUT_CONFIG_MIDDLE_EMULATION_DISABLED. * |