Documentation updates, also fixing STR #2574, trying to make clear

which events invisible and inactive widgets can get.


git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@8623 ea41ed52-d2ee-0310-a9c1-e6b18d33e121

1 files changed, 41 insertions, 52 deletions

diff --git a/documentation/src/events.dox b/documentation/src/events.dox
index 73920feaf..2cbeba67a 100644
--- a/documentation/src/events.dox
+++ b/documentation/src/events.dox
@@ -128,47 +128,40 @@ This indicates an \e attempt to give a widget the keyboard focus.
 
 If a widget wants the focus, it should change itself to
 display the fact that it has the focus, and return non-zero from its
-\p handle()
-method.  It then becomes the
-Fl::focus()
-widget and gets
-\p FL_KEYDOWN, \p FL_KEYUP, and \p FL_UNFOCUS
-events.
+\p handle() method. It then becomes the Fl::focus() widget and gets
+\p FL_KEYDOWN, \p FL_KEYUP, and \p FL_UNFOCUS events.
 
-The focus will change either because the window manager
-changed which window gets the focus, or because the user tried
-to navigate using tab, arrows, or other keys. You can check
-Fl::event_key()
-to figure out why it moved. For navigation it will be the key
-pressed and interaction with the window manager it will be zero.
+The focus will change either because the window manager changed which
+window gets the focus, or because the user tried to navigate using tab,
+arrows, or other keys. You can check Fl::event_key() to figure out why
+it moved. For navigation it will be the key pressed and for interaction
+with the window manager it will be zero.
 
 \subsection events_fl_unfocus FL_UNFOCUS
 
-This event is sent to the previous
-Fl::focus()
-widget when another widget gets the focus or the window loses focus.
+This event is sent to the previous Fl::focus() widget when another
+widget gets the focus or the window loses focus.
 
 \section events_keyboard Keyboard Events
 
-\subsection events_fl_keydown FL_KEYDOWN, FL_KEYUP
+\subsection events_fl_keydown FL_KEYBOARD, FL_KEYDOWN, FL_KEYUP
 
-A key was pressed or released. The key can be found in
-Fl::event_key().
-The text that the key should insert can be found with
-Fl::event_text()
-and its length is in
-Fl::event_length().
-If you use the key, then 
-\p handle()
-should return 1. If you
+A key was pressed (FL_KEYDOWN) or released (FL_KEYUP). FL_KEYBOARD
+is a synonym for FL_KEYDOWN, and both names are used interchangeably
+in this documentation.
+
+The key can be found in Fl::event_key().
+The text that the key should insert can be found with Fl::event_text()
+and its length is in Fl::event_length().
+
+If you use the key, then \p handle() should return 1. If you
 return zero then FLTK assumes you ignored the key and will
 then attempt to send it to a parent widget. If none of them want
 it, it will change the event into a \p FL_SHORTCUT event.
 FL_KEYBOARD events are also generated by the character palette/map.
 
-To receive \p FL_KEYBOARD events you must also
-respond to the \p FL_FOCUS and \p FL_UNFOCUS
-events.
+To receive \p FL_KEYBOARD events you must also respond to the
+\p FL_FOCUS and \p FL_UNFOCUS events.
 
 If you are writing a text-editing widget you may also want to call the
 Fl::compose()
@@ -181,10 +174,8 @@ because focus may have changed between events.
 
 \subsection events_fl_shortcut FL_SHORTCUT
 
-If the
-Fl::focus()
-widget is zero or ignores an \p FL_KEYBOARD event then
-FLTK tries sending this event to every widget it can, until one
+If the Fl::focus() widget is zero or ignores an \p FL_KEYBOARD event
+then FLTK tries sending this event to every widget it can, until one
 of them returns non-zero. \p FL_SHORTCUT is first sent to
 the Fl::belowmouse() widget, then its parents and
 siblings, and eventually to every widget in the window, trying
@@ -246,16 +237,20 @@ class
 \p handle()
 method!</I>
 
+\note	The events in this chapter ("Widget Events"), i.e.
+	FL_ACTIVATE, FL_DEACTIVATE, FL_SHOW, and FL_HIDE,
+	are the only events deactivated and invisible widgets
+	can usually get, depending on their states. Under certain
+	circumstances, there may also be FL_LEAVE or FL_UNFOCUS
+	events delivered to deactivated or hidden widgets.
+
 \section events_clipboard Clipboard Events
 
 \subsection events_fl_paste FL_PASTE
 
-You should get this event some time after you call
-Fl::paste().
-The contents of
-Fl::event_text()
-is the text to insert and the number of characters is in
-Fl::event_length().
+You should get this event some time after you call Fl::paste().
+The contents of Fl::event_text() is the text to insert and the
+number of characters is in Fl::event_length().
 
 \subsection events_fl_selectionclear FL_SELECTIONCLEAR
 
@@ -268,8 +263,8 @@ selection indication. Most modern programs ignore this.
 \section events_dnd Drag and Drop Events
 
 FLTK supports drag and drop of text and files from any 
-application on the desktop to an FLTK widget. Text is transfered using
-the current code page. Files are received as a list of full path
+application on the desktop to an FLTK widget. Text is transferred
+using UTF-8 encoding. Files are received as a list of full path
 and file names, separated by newline. On some platforms, path
 names are prepended with <tt>%file://</tt>.
 See Fl::dnd() for drag and drop from an FLTK widget.
@@ -305,7 +300,6 @@ The user has released the mouse button dropping data into
 the widget. If the widget returns 1, it will receive the data in
 the immediately following \p FL_PASTE event.
 
-<!-- NEED 6in -->
 
 \section events_event_xxx Fl::event_*() methods
 
@@ -345,17 +339,15 @@ event by returning 1. FLTK will then remove the event and wait for further event
 from the host. If the widget's handle function returns 0, FLTK may redistribute
 the event based on a few rules.
 
-Most events are sent directly to the
-\p handle()
-method
+Most events are sent directly to the \p handle() method
 of the Fl_Window that the window system says they
 belong to.  The window (actually the Fl_Group that
 Fl_Window is a subclass of) is responsible for sending
 the events on to any child widgets.  To make the
 Fl_Group code somewhat easier, FLTK sends some events
 (\p FL_DRAG, \p FL_RELEASE, \p FL_KEYBOARD,
-\p FL_SHORTCUT, \p FL_UNFOCUS, and
-\p FL_LEAVE) directly to leaf widgets. These procedures
+\p FL_SHORTCUT, \p FL_UNFOCUS, and \p FL_LEAVE)
+directly to leaf widgets. These procedures
 control those leaf widgets:
 
 \li Fl::add_handler()
@@ -364,7 +356,7 @@ control those leaf widgets:
 \li Fl::grab()
 \li Fl::modal()
 \li Fl::pushed()
-\li Fl::release()
+\li Fl::release() (deprecated, see Fl::grab(0))
 \li Fl_Widget::take_focus()
 
 FLTK propagates events along the widget hierarchy depending on the kind of event
@@ -377,11 +369,8 @@ is below the click position. If that widget uses the given event, the widget
 is marked "pushed" and will receive all following mouse motion (FL_DRAG) events
 until the mouse button is released.
 
-\todo Is this correct? IMHO, mouse motion (FL_MOVE) events are sent to the
-belowmouse() widget, i.e. the widget that returned 1 on an FL_ENTER event.
-The pushed() widget will usually get an FL_FOCUS event and becomes the focus()
-widget if it returns 1 on FL_FOCUS, and will then get keyboard events (see
-below).
+Mouse motion (FL_MOVE) events are sent to the Fl::belowmouse() widget, i.e.
+the widget that returned 1 on the last FL_ENTER event.
 
 Mouse wheel events are sent to the window that caused the event. The window
 propagates the event down the tree, first to the widget that is below the