Improve documentation on mouse and keyboard events

1 files changed, 58 insertions, 4 deletions

diff --git a/documentation/src/events.dox b/documentation/src/events.dox
index 8ac2747dc..9ca663a74 100644
--- a/documentation/src/events.dox
+++ b/documentation/src/events.dox
@@ -23,7 +23,7 @@ This static information remains valid until the next event
 is read from the window system, so it is ok to look at it outside
 of the
 \p handle()
-method.
+method, for instance in a callback.
 
 Event numbers can be converted to their actual names using the \ref fl_eventnames[] array
 defined in \#include <FL/names.h>; see next chapter for details.
@@ -36,6 +36,40 @@ method to accept and process specific events.
 
 \section events_mouse Mouse Events
 
+Classic mice provide two or three buttons:
+  - a primary (left) button, typically used to point and click on objects
+  - a secondary (right) button, typically used to open special menus etc.
+  - a middle button for other special events.
+
+The primary and secondary mouse buttons can usually be inverted by system
+setup functions for left handed usage. FLTK always sends the mouse button
+number according to the "logical" mouse button, i.e. such a setup is
+transparent for application programmers.
+
+The middle button was later replaced by a scroll wheel to allow scrolling
+text or other objects in a window or widget vertically. Pushing the scroll
+wheel down acts like pushing the middle mouse button.
+
+If the scroll wheel is used to scroll while the Shift key is held, the
+scrolling direction is horizontal rather than vertical.
+
+Some mice may even have a "scroll ball" or similar (touch) feature. These
+mice support horizontal and vertical scrolling simultaneously.
+
+Newer mice add even more buttons, called "side buttons":
+  - a "back" button, typically used to "go back", e.g. in browsers
+  - a "forward" button, typically used to "go forward", e.g. in browsers
+
+FLTK handles up to five buttons since version 1.4.0 across all supported
+platforms. Note that Windows doesn't support more than five buttons
+whereas other platforms may support more. FLTK ignores other buttons as
+long as they send "mouse button" events.
+
+Some gaming mice with five or more buttons may send their button clicks
+as keyboard events which will be handled like normal text input by FLTK.
+This has not been tested though.
+
+
 \subsection events_fl_push FL_PUSH
 
 A mouse button has gone down with the mouse pointing at this
@@ -63,7 +97,7 @@ another widget.
 
 \subsection events_fl_drag FL_DRAG
 
-The mouse has moved with a button held down. The current
+The mouse has moved with at least one button held down. The current
 button state is in
 Fl::event_state().
 The mouse position is in
@@ -74,6 +108,22 @@ Fl::event_y().
 In order to receive \p FL_DRAG events, the widget must
 return non-zero when handling \p FL_PUSH.
 
+Moving the mouse keeps sending FL_DRAG events as long as at least one
+button is held down. If any buttons are pushed and released during the
+drag operation FLTK sends FL_PUSH and FL_RELEASE events even while dragging.
+The current button status can be found in Fl::event_state() and in
+Fl::event_buttons().
+
+When the last button has been released FLTK sends FL_MOVE events again.
+Note: The button released last need not necessarily be the one that
+started the drag operation.
+
+Since FLTK 1.4.0 dragging is supported for all five supported mouse buttons,
+for instance the user can drag the mouse while the "back" button is held down.
+Warning: This may or may not be compatible with other applications for
+drag-and-drop operations \b between applications and lead to unexpected behavior.
+
+
 \subsection events_fl_release FL_RELEASE
 
 A mouse button has been released. You can find out what button by calling
@@ -82,6 +132,7 @@ Fl::event_button().
 In order to receive the \p FL_RELEASE event, the widget must
 return non-zero when handling \p FL_PUSH.
 
+
 \subsection events_fl_move FL_MOVE
 
 The mouse has moved without any mouse buttons held down.
@@ -92,14 +143,17 @@ widget.
 In order to receive \p FL_MOVE events, the widget must
 return non-zero when handling \p FL_ENTER.
 
+
 \subsection events_fl_mousewheel FL_MOUSEWHEEL
 
 The user has moved the mouse wheel. The
 Fl::event_dx()
 and
 Fl::event_dy()
-methods can be used to find the amount to scroll horizontally and
-vertically.
+methods can be used to find the amount to scroll horizontally (dx) and
+vertically (dy). On mice with a single scroll wheel holding the Shift key
+on the keyboard while scrolling sends horizontal scroll events.
+
 
 \section events_focus Focus Events