doc: split middle button emulation into a separate page

Easier to link to from bug reports

Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>

3 files changed, 36 insertions, 0 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