Improve documentation on mouse and keyboard events

FL/Fl.H

@@ -707,7 +707,7 @@ public:
     \retval FL_MIDDLE_MOUSE
     \retval FL_RIGHT_MOUSE
     \retval FL_BACK_MOUSE
-    \retval FL_FORWARD_MOUSE.
+    \retval FL_FORWARD_MOUSE
     \see Fl::event_buttons(), Fl::event_state()
   */
   static int event_button() { return e_keysym - FL_Button; }

documentation/src/enumerations.dox

@@ -98,6 +98,8 @@ FL_RELEASE events:
   - FL_LEFT_MOUSE    - the left mouse button
   - FL_MIDDLE_MOUSE  - the middle mouse button
   - FL_RIGHT_MOUSE   - the right mouse button
+  - FL_BACK_MOUSE    - the back mouse button (side button 1)
+  - FL_FORWARD_MOUSE - the forward mouse button (side button 2)
 
 
 \section enumerations_event_key Fl::event_key() Values
@@ -140,6 +142,7 @@ FL_KEYBOARD and FL_SHORTCUT events:
   - FL_Alt_L - The left alt key.
   - FL_Alt_R - The right alt key.
   - FL_Delete - The delete key.
+  - FL_Alt_Gr - The AltGr key on some international keyboards.
 
 
 \section enumerations_event_state Fl::event_state() Values
@@ -161,7 +164,9 @@ value:
   - FL_BUTTON1 - Mouse button 1 is pushed.
   - FL_BUTTON2 - Mouse button 2 is pushed.
   - FL_BUTTON3 - Mouse button 3 is pushed.
-  - FL_BUTTONS - Any mouse button is pushed.
+  - FL_BUTTON4 - Mouse button 4 (back) is pushed.
+  - FL_BUTTON5 - Mouse button 5 (forward) is pushed.
+  - FL_BUTTONS - Any mouse button (1..5) is pushed.
   - FL_BUTTON(n) - Mouse button \p n ( where <tt>n > 0</tt>) is pushed.
 
 \section enumerations_alignment Alignment Values

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
+methods can be used to find the amount to scroll horizontally (dx) and
-vertically.
+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