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

FL/Fl_Browser.H

@@ -3,7 +3,7 @@
 //
 // Browser header file for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2010 by Bill Spitzak and others.
+// Copyright 1998-2011 by Bill Spitzak and others.
 //
 // This library is free software; you can redistribute it and/or
 // modify it under the terms of the GNU Library General Public
@@ -28,7 +28,7 @@
 /* \file
    Fl_Browser widget . */
 
-// Forms-compatable browser.  Probably useful for other
+// Forms-compatible browser.  Probably useful for other
 // lists of textual data.  Notice that the line numbers
 // start from 1, and 0 means "no line".
 

FL/Fl_Widget.H

@@ -162,7 +162,7 @@ protected:
   */
   enum {
         INACTIVE        = 1<<0,   ///< the widget can't receive focus, and is disabled but potentially visible
-        INVISIBLE       = 1<<1,   ///< the widget is not drawn but can receive events
+        INVISIBLE       = 1<<1,   ///< the widget is not drawn, but can receive a few special events
         OUTPUT          = 1<<2,   ///< for output only
         NOBORDER        = 1<<3,   ///< don't draw a decoration (Fl_Window)
         FORCE_POSITION  = 1<<4,   ///< don't let the window manager position the window (Fl_Window)
@@ -660,14 +660,17 @@ public:
   int visible_r() const;
 
   /** Makes a widget visible.
-      An invisible widget never gets redrawn and does not get events.  
+
+      An invisible widget never gets redrawn and does not get keyboard
+      or mouse events, but can receive a few other events like FL_SHOW.
+
       The visible() method returns true if the widget is set to be
       visible. The visible_r() method returns true if the widget and
       all of its parents are visible. A widget is only visible if
       visible() is true on it <I>and all of its parents</I>.
 
-      Changing it will send FL_SHOW or FL_HIDE events to 
+      Changing it will send FL_SHOW or FL_HIDE events to the widget.
-      the widget. <I>Do not change it if the parent is not visible, as this 
+      <I>Do not change it if the parent is not visible, as this
       will send false FL_SHOW or FL_HIDE events to the widget</I>.
       redraw() is called if necessary on this or the parent.
 
@@ -748,8 +751,8 @@ public:
   void clear_output() {flags_ &= ~OUTPUT;}
 
   /** Returns if the widget is able to take events.
-      This is the same as (active() && !output()
+      This is the same as (active() && !output() && visible())
-      && visible()) but is faster.
+      but is faster.
       \retval 0 if the widget takes no events
    */
   unsigned int takesevents() const {return !(flags_&(INACTIVE|INVISIBLE|OUTPUT));}

FL/dirent.h

@@ -3,7 +3,7 @@
 //
 // Directory header file for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2010 by Bill Spitzak and others.
+// Copyright 1998-2011 by Bill Spitzak and others.
 //
 // This library is free software; you can redistribute it and/or
 // modify it under the terms of the GNU Library General Public
@@ -26,7 +26,7 @@
 //
 
 
-// this file is for back-compatability only
+// this file is for back-compatibility only
 #include "filename.H"
 
 //

FL/forms.H

@@ -3,7 +3,7 @@
 //
 // Forms emulation header file for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2010 by Bill Spitzak and others.
+// Copyright 1998-2011 by Bill Spitzak and others.
 //
 // This library is free software; you can redistribute it and/or
 // modify it under the terms of the GNU Library General Public
@@ -674,7 +674,7 @@ inline int fl_show_choices(const char* c,int n,const char* b1,const char* b2,
 #include "Fl_File_Chooser.H"
 inline int do_matching(char* a, const char* b) {return fl_filename_match(a,b);}
 
-// Forms-compatable file chooser (implementation in fselect.C):
+// Forms-compatible file chooser (implementation in fselect.C):
 FL_EXPORT char* fl_show_file_selector(const char* message,const char* dir,
 			    const char* pat,const char* fname);
 FL_EXPORT char*	fl_get_directory();

FL/gl.h

@@ -3,7 +3,7 @@
 //
 // OpenGL header file for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2010 by Bill Spitzak and others.
+// Copyright 1998-2011 by Bill Spitzak and others.
 //
 // You must include this instead of GL/gl.h to get the Microsoft
 // APIENTRY stuff included (from <windows.h>) prior to the OpenGL
@@ -73,7 +73,7 @@ FL_EXPORT void gl_start();
 FL_EXPORT void gl_finish();
 
 FL_EXPORT void gl_color(Fl_Color i);
-/** back compatability */
+/** back compatibility */
 inline void gl_color(int c) {gl_color((Fl_Color)c);}
 
 FL_EXPORT void gl_rect(int x,int y,int w,int h);

FL/glut.H

@@ -3,7 +3,7 @@
 //
 // GLUT emulation header file for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2010 by Bill Spitzak and others.
+// Copyright 1998-2011 by Bill Spitzak and others.
 //
 // This library is free software; you can redistribute it and/or
 // modify it under the terms of the GNU Library General Public
@@ -407,7 +407,7 @@ FL_EXPORT GLUTproc glutGetProcAddress(const char *procName);
 
 //inline void glutVideoPan(int x, int y, int width, int height);
 
-// Font argument must be a void* for compatability, so...
+// Font argument must be a void* for compatibility, so...
 /** fltk glut font/size attributes used in the glutXXX functions */
 struct Fl_Glut_Bitmap_Font {Fl_Font font; Fl_Fontsize size;};
 

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()
+\p handle() method. It then becomes the Fl::focus() widget and gets
-method.  It then becomes the
+\p FL_KEYDOWN, \p FL_KEYUP, and \p FL_UNFOCUS events.
-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
+The focus will change either because the window manager changed which
-changed which window gets the focus, or because the user tried
+window gets the focus, or because the user tried to navigate using tab,
-to navigate using tab, arrows, or other keys. You can check
+arrows, or other keys. You can check Fl::event_key() to figure out why
-Fl::event_key()
+it moved. For navigation it will be the key pressed and for interaction
-to figure out why it moved. For navigation it will be the key
+with the window manager it will be zero.
-pressed and interaction with the window manager it will be zero.
 
 \subsection events_fl_unfocus FL_UNFOCUS
 
-This event is sent to the previous
+This event is sent to the previous Fl::focus() widget when another
-Fl::focus()
+widget gets the focus or the window loses 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
+A key was pressed (FL_KEYDOWN) or released (FL_KEYUP). FL_KEYBOARD
-Fl::event_key().
+is a synonym for FL_KEYDOWN, and both names are used interchangeably
-The text that the key should insert can be found with
+in this documentation.
-Fl::event_text()
+
-and its length is in
+The key can be found in Fl::event_key().
-Fl::event_length().
+The text that the key should insert can be found with Fl::event_text()
-If you use the key, then 
+and its length is in Fl::event_length().
-\p handle()
+
-should return 1. If you
+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
+To receive \p FL_KEYBOARD events you must also respond to the
-respond to the \p FL_FOCUS and \p FL_UNFOCUS
+\p FL_FOCUS and \p FL_UNFOCUS events.
-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
+If the Fl::focus() widget is zero or ignores an \p FL_KEYBOARD event
-Fl::focus()
+then FLTK tries sending this event to every widget it can, until one
-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
+You should get this event some time after you call Fl::paste().
-Fl::paste().
+The contents of Fl::event_text() is the text to insert and the
-The contents of
+number of characters is in Fl::event_length().
-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
+application on the desktop to an FLTK widget. Text is transferred
-the current code page. Files are received as a list of full path
+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
+Most events are sent directly to the \p handle() method
-\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_SHORTCUT, \p FL_UNFOCUS, and \p FL_LEAVE)
-\p FL_LEAVE) directly to leaf widgets. These procedures
+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
+Mouse motion (FL_MOVE) events are sent to the Fl::belowmouse() widget, i.e.
-belowmouse() widget, i.e. the widget that returned 1 on an FL_ENTER event.
+the widget that returned 1 on the last 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 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 

src/Fl_PostScript.cxx

@@ -3,7 +3,7 @@
 //
 // PostScript device support for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 2010 by Bill Spitzak and others.
+// Copyright 2010-2011 by Bill Spitzak and others.
 //
 // This library is free software; you can redistribute it and/or
 // modify it under the terms of the GNU Library General Public
@@ -867,7 +867,7 @@ void Fl_PostScript_Graphics_Driver::line_style(int style, int width, char* dashe
     linedash_[0]=0;
   char width0 = 0;
   if(!width){
-    width=1; //for screen drawing compatability
+    width=1; //for screen drawing compatibility
     width0=1;
   }
   

src/Fl_win32.cxx

@@ -1561,7 +1561,7 @@ Fl_X* Fl_X::make(Fl_Window* w) {
     w->redraw(); // force draw to happen
   }
   // If we've captured the mouse, we dont want to activate any
-  // other windows from the code, or we loose the capture.
+  // other windows from the code, or we lose the capture.
   ShowWindow(x->xid, !showit ? SW_SHOWMINNOACTIVE :
 	     (Fl::grab() || (style & WS_POPUP)) ? SW_SHOWNOACTIVATE : SW_SHOWNORMAL);
 

src/Fl_x.cxx

@@ -3,7 +3,7 @@
 //
 // X specific code for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2010 by Bill Spitzak and others.
+// Copyright 1998-2011 by Bill Spitzak and others.
 //
 // This library is free software; you can redistribute it and/or
 // modify it under the terms of the GNU Library General Public
@@ -1253,7 +1253,7 @@ int fl_handle(const XEvent& thisevent)
           len = fl_utf8encode(XKeysymToUcs(keysym), buffer);
           if (len < 1) len = 1;
           // ignore all effects of shift on the keysyms, which makes it a lot
-          // easier to program shortcuts and is Windoze-compatable:
+          // easier to program shortcuts and is Windoze-compatible:
           keysym = XKeycodeToKeysym(fl_display, keycode, 0);
         }
       }