Completed and corrected Fl and related Fl_Window documentation, added cross references, especially to back compatibility functions to the new ones.

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

FL/Fl.H

@@ -388,18 +388,20 @@ public:
   */
   static void get_mouse(int &,int &); // platform dependent
   /**
-    The first form returns non-zero if the most recent FL_PUSH or
+    Returns non zero if we had a double click event.
-    FL_KEYBOARD was a "double click".  Returns N-1 for
+    \retval Non-zero if the most recent FL_PUSH or FL_KEYBOARD was a "double click".  
-    N clicks.  A double click is counted if the same button is pressed
+    \retval  N-1 for  N clicks. 
+    A double click is counted if the same button is pressed
     again while event_is_click() is true.
     
-    <P>The second form directly sets the number returned by 
-    Fl::event_clicks().  This can be used to set it to zero so that
-    later code does not think an item was double-clicked.
    */
   static int event_clicks()	{return e_clicks;}
   /**
-    See int event_clicks()
+    Manually sets the number returned by Fl::event_clicks().  
+    This can be used to set it to zero so that
+    later code does not think an item was double-clicked.
+    \param[in] i correspond to no double-click if 0, i+1 mouse clicks otherwise
+    \see int event_clicks()
   */
   static void event_clicks(int i) {e_clicks = i;}
   /**
@@ -418,8 +420,10 @@ public:
   */
   static void event_is_click(int i) {e_is_click = i;}
   /**
-    Returns which mouse button caused te current event. This returns garbage if the
+    Gets which particular mouse button caused the current event. 
-    most recent event was not a FL_PUSH or FL_RELEASE event.
+    This returns garbage if the most recent event was not a FL_PUSH or FL_RELEASE event.
+    \retval FL_LEFT_MOUSE \retval FL_MIDDLE_MOUSE \retval FL_RIGHT_MOUSE.
+    \see Fl::event_buttons()
   */
   static int event_button()	{return e_keysym-FL_Button;}
   /**
@@ -450,11 +454,20 @@ public:
   static int event_state()	{return e_state;}
   /** See int event_state() */
   static int event_state(int i) {return e_state&i;}
+  /** Gets which key on the keyboard was last pushed.
+      \retval 0 if the last event was not a key press or release.
+    \see int event_key(int) */
+  static int event_key()	{return e_keysym;}
   /**
-    Fl::event_key() returns which key on the keyboard was last
+    If NumLock is deactivated, FLTK translates events from the 
-    pushed.  It returns zero if the last event was not a key press or release.
+    numeric keypad into the corresponding arrow key events. 
-    
+    event_key() returns the translated key code, whereas
-    <P>Fl::event_key(int) returns true if the given key was held
+    event_original_key() returns the keycode before 
+    NumLock translation.
+  */
+  static int event_original_key(){return e_original_keysym;}
+  /** 
+    Returns true if the given \a key was held
     down (or pressed) <I>during</I> the last event.  This is constant until
     the next event is read from the server.
     
@@ -495,23 +508,13 @@ public:
     <P>On WIN32 Fl::get_key(FL_KP_Enter) and 
     Fl::event_key(FL_KP_Enter) do not work.
   */
-  static int event_key()	{return e_keysym;}
+  static int event_key(int key);
-  /**
-    If NumLock is deactivated, FLTK translates events from the 
-    numeric keypad into the corresponding arrow key events. 
-    event_key() returns the translated key code, whereas
-    event_original_key() returns the keycode before 
-    NumLock translation.
-  */
-  static int event_original_key(){return e_original_keysym;}
-  /** See int event_key() */
-  static int event_key(int);
   /** 
-    Returns true if the given key is held down <I>now</I>.  
+    Returns true if the given \a key is held down <I>now</I>.  
     Under X this requires a round-trip to the server and is <I>
-    much</I> slower than Fl::event_key(int). See event_key().
+    much</I> slower than Fl::event_key(int). \see event_key(int)
   */
-  static int get_key(int); // platform dependent
+  static int get_key(int key); // platform dependent
   /** Returns the text associated with the current FL_PASTE or FL_DND_RELEASE event. */
   static const char* event_text() {return e_text;}
   /**
@@ -536,10 +539,12 @@ public:
 
   // event destinations:
   static int handle(int, Fl_Window*);
-  /** See Fl_Widget* belowmouse(Fl_Widget*) */
+  /**  Gets the widget that is below the mouse. 
+       \see  belowmouse(Fl_Widget*) */
   static Fl_Widget* belowmouse() {return belowmouse_;}
   static void belowmouse(Fl_Widget*);
-  /** See Fl_Widget* pushed(Fl_Widget*) */
+  /** Sets the widget that is being pushed 
+      \see Fl_Widget* pushed(Fl_Widget*) */
   static Fl_Widget* pushed()	{return pushed_;}
   static void pushed(Fl_Widget*);
   /** Gets the current Fl::focus() widget. \sa Fl::focus(Fl_Widget*) */
@@ -577,7 +582,8 @@ public:
   static int dnd(); // platform dependent
 
   // These are for back-compatibility only:
-  /** See Fl_Widget* selection_owner(Fl_Widget*) */
+  /**  back-compatibility only: Gets the widget owning the current selection  
+       \see Fl_Widget* selection_owner(Fl_Widget*) */
   static Fl_Widget* selection_owner() {return selection_owner_;}
   static void selection_owner(Fl_Widget*);
   static void selection(Fl_Widget &owner, const char*, int len);
@@ -696,13 +702,14 @@ public:
   static int draw_box_active();
 
   // back compatibility:
-  /** for back compatibility. sets the (*fatal)() callback. */
   /** \addtogroup fl_windows 
     @{ */
+  /** For back compatibility, sets the void Fl::fatal handler callback */
   static void set_abort(void (*f)(const char*,...)) {fatal = f;}
   static void (*atclose)(Fl_Window*,void*);
   static void default_atclose(Fl_Window*,void*);
-  /** for back compatibility. sets the (*atclose)() callback. */
+  /** For back compatibility, sets the Fl::atclose handler callback. You
+      can now simply change the callback for the window instead \see Fl_Window::callback(Fl_Callback*) */
   static void set_atclose(void (*f)(Fl_Window*,void*)) {atclose = f;}
   /**   @} */
 
@@ -715,16 +722,16 @@ public:
   /** Returns non-zero if the Alt key is pressed. */
   static int event_alt() {return e_state&FL_ALT;}
   /**
-    Returns the button state bits; if non-zero, then at least one
+    Returns the mouse buttons state bits; if non-zero, then at least one
-    button is pressed.  This function returns the button state at the 
+    button is pressed now.  This function returns the button state at the 
     time of the event. During an FL_RELEASE event, the state 
     of the released button will be 0. To find out, which button 
-    caused an FL_RELEASE event, you can use 
+    caused an FL_RELEASE event, you can use Fl::event_button() instead.
-    Fl::event_button() instead.
+    \return a bit mask value like { [FL_BUTTON1] | [FL_BUTTON2] | [FL_BUTTON3] }
   */
   static int event_buttons() {return e_state&0x7f000000;}
   /**
-    Returns non-zero if button 1 is currently held down.
+    Returns non-zero if mouse button 1 is currently held down.
     For more details, see Fl::event_buttons().
   */
   static int event_button1() {return e_state&FL_BUTTON1;}

FL/Fl_Window.H

@@ -343,7 +343,7 @@ public:
     draws a slow graphic. <B>Danger: incremental update is very hard to
     debug and maintain!</B>
     <P>This method only works for the Fl_Window and 
-    Fl_Gl_Window classes.
+    Fl_Gl_Window derived classes.
   */
   void make_current();
 

src/Fl.cxx

@@ -754,7 +754,7 @@ void Fl::focus(Fl_Widget *o) {
 static char dnd_flag = 0; // make 'belowmouse' send DND_LEAVE instead of LEAVE
 
 /**
-    Get or set the widget that is below the mouse.  This is for
+    Sets the widget that is below the mouse.  This is for
     highlighting buttons.  It is not used to send FL_PUSH or 
     FL_MOVE directly, for several obscure reasons, but those events
     typically go to this widget.  This is also the first widget tried for 
@@ -782,7 +782,7 @@ void Fl::belowmouse(Fl_Widget *o) {
 }
 
 /**
-    Get or set the widget that is being pushed. FL_DRAG or 
+    Sets the widget that is being pushed. FL_DRAG or 
     FL_RELEASE (and any more FL_PUSH) events will be sent to
     this widget.
     
@@ -1291,8 +1291,7 @@ int Fl_Window::handle(int ev)
 ////////////////////////////////////////////////////////////////
 // Back compatibility cut & paste functions for fltk 1.1 only:
 
-/**
+/** Back-compatibility only: The single-argument call can be used to
-    The single-argument selection_owner(x) call can be used to
     move the selection to another widget or to set the owner to
     NULL, without changing the actual text of the
     selection. FL_SELECTIONCLEAR is sent to the previous
@@ -1318,7 +1317,7 @@ void Fl::selection(Fl_Widget &owner, const char* text, int len) {
   Fl::copy(text, len, 0);
 }
 
-/**
+/** Backward compatibility only:
   Set things up so the receiver widget will be called with an  FL_PASTE event some
   time in the future for the specified clipboard. The reciever
   should be prepared to be called <I>directly</I> by this, or for
@@ -1326,6 +1325,7 @@ void Fl::selection(Fl_Widget &owner, const char* text, int len) {
   allows the window system to take as long as necessary to retrieve
   the paste buffer (or even to screw up completely) without complex
   and error-prone synchronization code in FLTK.
+  \see Fl::paste(Fl_Widget &receiver, int clipboard)
 */
 void Fl::paste(Fl_Widget &receiver) {
   Fl::paste(receiver, 0);

src/Fl_Window.cxx

@@ -168,17 +168,14 @@ void Fl::default_atclose(Fl_Window* window, void* v) {
   window->hide();
   Fl_Widget::default_callback(window, v); // put on Fl::read_queue()
 }
-
+/** Back compatibility: default window callback handler \see Fl::set_atclose() */
 void (*Fl::atclose)(Fl_Window*, void*) = default_atclose;
-/**
+/** Back compatibility: Sets the default callback v for win to call on close event */
-   Sets the default callback v for win to call on close event.
-   <P> For back compatibility only.
-*/
 void Fl_Window::default_callback(Fl_Window* win, void* v) {
   Fl::atclose(win, v);
 }
 
-/**  Returns the last window that was made current. */
+/**  Returns the last window that was made current. \see Fl_Window::make_current() */
 Fl_Window *Fl_Window::current() {
   return current_;
 }

src/screen_xywh.cxx

@@ -151,12 +151,10 @@ int Fl::screen_count() {
 }
 
 /**
-  Gets the bounding box of a screen. The first form gets the
+  Gets the bounding box of a screen 
-  bounding box for the screen the mouse pointer is in. The second
+  where the mouse pointer is in. 
-  form gets the bounding box for the screen that contains the
+  \param[out]  X,Y,W,H the corresponding screen bounding box
-  specified coordinates. The last form gets the bounding box for
+  \param[in] mx, my the mouse absolute screen position
-  the numbered screen, where n is a number from 0 to the
-  number of screens less 1.
 */
 void Fl::screen_xywh(int &X, int &Y, int &W, int &H, int mx, int my) {
   if (!num_screens) screen_init();
@@ -222,8 +220,10 @@ void Fl::screen_xywh(int &X, int &Y, int &W, int &H, int mx, int my) {
 }
 
 /**
-  Returns the screen bounding rect for the given screen. 
+  Gets the screen bounding rect for the given screen. 
-  See void screen_xywh(int &x, int &y, int &w, int &h, int mx, int my) 
+  \param[out]  X,Y,W,H the corresponding screen bounding box
+  \param[in] n the screen number (0 to Fl::screen_count() - 1)
+  \see void screen_xywh(int &x, int &y, int &w, int &h, int mx, int my) 
 */
 void Fl::screen_xywh(int &X, int &Y, int &W, int &H, int n) {
   if (!num_screens) screen_init();