Doxgen mods for Fl_Browser*:

o Added \see for all methods that seemed to need it
	o Fix to has_scroll() enum docs as per Albrecht's comments
	o Other small doc tweaks



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

FL/Fl_Browser.H

@@ -115,11 +115,13 @@ protected:
   /** Swap the items \p a and \p b.
       You must call redraw() to make any changes visible.
       \param[in] a,b the items to be swapped.
+      \see swap(int,int), item_swap()
    */
   void item_swap(void *a, void *b) { swap((FL_BLINE*)a, (FL_BLINE*)b); }
   /** Return the item at specified \p line.
       \param[in] line The line of the item to return. (1 based)
       \returns The item, or NULL if line out of range.
+      \see item_at(), find_line(), lineno()
    */
   void *item_at(int line) const { return (void*)find_line(line); }
 
@@ -155,18 +157,21 @@ public:
     Scrolls the browser so the top item in the browser
     is showing the specified \p line.
     \param[in] line The line to be displayed at the top.
+    \see topline(), middleline(), bottomline(), displayed(), lineposition()
    */
   void topline(int line) { lineposition(line, TOP); }
   /**
     Scrolls the browser so the bottom item in the browser
     is showing the specified \p line.
     \param[in] line The line to be displayed at the bottom.
+    \see topline(), middleline(), bottomline(), displayed(), lineposition()
    */
   void bottomline(int line) { lineposition(line, BOTTOM); }
   /**
     Scrolls the browser so the middle item in the browser
     is showing the specified \p line.
     \param[in] line The line to be displayed in the middle.
+    \see topline(), middleline(), bottomline(), displayed(), lineposition()
    */
   void middleline(int line) { lineposition(line, MIDDLE); }
 
@@ -181,8 +186,10 @@ public:
   int visible(int line) const ;
 
   int value() const ;
-  /** Sets the browser's value(), which selects the specified \p line.
+  /**
-      This is the same as calling select(line).
+    Sets the browser's value(), which selects the specified \p line.
+    This is the same as calling select(line).
+    \see select(), selected(), value(), item_select(), item_selected()
    */
   void value(int line) { select(line); }
   const char* text(int line) const ;
@@ -222,25 +229,27 @@ public:
 
     Notice that the '\@.' command can be used to reliably
     terminate the parsing.  To print a random string in a random color, use 
-    <tt>sprintf("\@C%d\@.%s", color, string)</tt> and it will work even if the
+    <tt>sprintf("@C%d@.%s", color, string)</tt> and it will work even if the
     string starts with a digit or has the format character in it.
   */
   char format_char() const { return format_char_; }
   /**
     Sets the current format code prefix character to \p c.
     The default prefix is '\@'.  Set the prefix to 0 to disable formatting.
-    \see uchar Fl_Browser::format_char() const
+    \see format_char() for list of '\@' codes
   */
   void format_char(char c) { format_char_ = c; }
   /**
     Gets the current column separator character.
     The default is '\\t' (tab).
+    \see column_char(), column_widths()
   */
   char column_char() const { return column_char_; }
   /**
     Sets the column separator to c.
     This will only have an effect if you also set column_widths().
     The default is '\\t' (tab).
+    \see column_char(), column_widths()
   */
   void column_char(char c) { column_char_ = c; }
   /**
@@ -264,16 +273,23 @@ public:
   b->add("root\t13115\t0.0\t0.0\t1352\t0\ttty2\tSW\tAug30\t0:00\t@b@f/sbin/mingetty tty2");
   [..]
     \endcode
+    \see column_char(), column_widths()
   */
   const int* column_widths() const { return column_widths_; }
   /**
     Sets the current array to \p arr.  Make sure the last entry is zero.
-    \see const int *Fl_Browser::column_widths() const
+    \see column_char(), column_widths()
   */
   void column_widths(const int* arr) { column_widths_ = arr; }
 
   /**
-    Returns non-zero if \p line is visible.
+    Returns non-zero if \p line has been scrolled to a position where it is being displayed.
+    Checks to see if the item's vertical position is within the top and bottom
+    edges of the display window. This does NOT take into account the hide()/show()
+    status of the widget or item.
+    \param[in] line The line to be checked
+    \returns 1 if visible, 0 if not visible.
+    \see topline(), middleline(), bottomline(), displayed(), lineposition()
   */
   int displayed(int line) const { return Fl_Browser_::displayed(find_line(line)); }
 
@@ -282,7 +298,7 @@ public:
     Functionally similar to show(int line).
     If \p line is out of range, redisplay top or bottom of list as appropriate.
     \param[in] line The line to be made visible.
-    \see show(int)
+    \see show(int), hide(int), display(), visible(), make_visible()
   */
   void make_visible(int line) {
     if (line < 1) Fl_Browser_::display(find_line(1));

FL/Fl_Browser_.H

@@ -89,25 +89,25 @@ protected:
   /**
     This method must be provided by the subclass 
     to return the first item in the list.
-    \see Related methods: item_first(), item_next(), item_last(), item_prev()
+    \see item_first(), item_next(), item_last(), item_prev()
    */
   virtual void *item_first() const = 0;
   /**
     This method must be provided by the subclass
     to return the item in the list after \p item.
-    \see Related methods: item_first(), item_next(), item_last(), item_prev()
+    \see item_first(), item_next(), item_last(), item_prev()
    */
   virtual void *item_next(void *item) const = 0;
   /**
     This method must be provided by the subclass
     to return the item in the list before \p item.
-    \see Related methods: item_first(), item_next(), item_last(), item_prev()
+    \see item_first(), item_next(), item_last(), item_prev()
    */
   virtual void *item_prev(void *item) const = 0;
   /**
     This method must be provided by the subclass
     to return the last item in the list.
-    \see Related methods: item_first(), item_next(), item_last(), item_prev()
+    \see item_first(), item_next(), item_last(), item_prev()
    */
   virtual void *item_last() const { return 0L; }
   /** 
@@ -116,7 +116,7 @@ protected:
     Allow for two additional pixels for the list selection box.
     \param[in] item The item whose height is returned.
     \returns The height of the specified \p item in pixels.
-    \see Related methods: item_height(), item_width(), item_quick_height()
+    \see item_height(), item_width(), item_quick_height()
   */
   virtual int item_height(void *item) const = 0;
   /**
@@ -182,7 +182,7 @@ protected:
   void redraw_line(void *item); // minimal update, no change in size
   /**
     This method will cause the entire list to be redrawn.
-    \see Related methods: redraw_lines(), redraw_line()
+    \see redraw_lines(), redraw_line()
    */
   void redraw_lines() { damage(FL_DAMAGE_SCROLL); } // redraw all of them
   void bbox(int &X,int &Y,int &W,int &H) const;
@@ -214,7 +214,7 @@ public:
     The position returned is how many pixels of the list are scrolled off the top edge
     of the screen.  Example: A position of '3' indicates the top 3 pixels of 
     the list are scrolled off the top edge of the screen.
-    \see Related methods: position(), hposition()
+    \see position(), hposition()
   */
   int position() const { return position_; }
   void position(int pos); // scroll to here
@@ -223,7 +223,7 @@ public:
     The position returned is how many pixels of the list are scrolled off the left edge
     of the screen. Example: A position of '18' indicates the left 18 pixels of
     the list are scrolled off the left edge of the screen.
-    \see Related methods: position(), hposition()
+    \see position(), hposition()
   */
   int hposition() const { return hposition_; }
   void hposition(int); // pan to here
@@ -232,14 +232,20 @@ public:
   /**
     Values for has_scrollbar().
    */
+  /** Anonymous enum bit flags for has_scrollbar().
+     -  bit 0: horizontal
+     -  bit 1: vertical
+     -  bit 2: 'always' (to be combined with bits 0 and 1)
+     -  bit 3-31: reserved for future use
+   */
   enum { // values for has_scrollbar()
-    HORIZONTAL = 1,		///< Only show horizontal scrollbar
+    HORIZONTAL = 1,		///< Only show horizontal scrollbar.
-    VERTICAL = 2,		///< Only show vertical scrollbar
+    VERTICAL = 2,		///< Only show vertical scrollbar.
-    BOTH = 3,			///< Show both scrollbars (default)
+    BOTH = 3,			///< Show both scrollbars. (default)
-    ALWAYS_ON = 4,		///< Both scrollbars always on
+    ALWAYS_ON = 4,		///< Specified scrollbar(s) should 'always' be shown (to be used with HORIZONTAL/VERTICAL)
-    HORIZONTAL_ALWAYS = 5,	///< horizontal scrollbar always on
+    HORIZONTAL_ALWAYS = 5,	///< Horizontal scrollbar always on.
-    VERTICAL_ALWAYS = 6,	///< vertical scrollbar always on
+    VERTICAL_ALWAYS = 6,	///< Vertical scrollbar always on.
-    BOTH_ALWAYS = 7		///< both scrollbars always on
+    BOTH_ALWAYS = 7		///< Both scrollbars always on.
   };
   /**
     Returns the current scrollbar mode, see Fl_Browser_::has_scrollbar(uchar)
@@ -271,7 +277,7 @@ public:
 
   /**
     Gets the default text font for the lines in the browser.
-    \see Related methods: textfont(), textsize(), textcolor()
+    \see textfont(), textsize(), textcolor()
   */
   Fl_Font textfont() const { return textfont_; }
   /**

src/Fl_Browser.cxx

@@ -63,6 +63,7 @@ struct FL_BLINE {	// data is in a linked list of these
   }
   \endcode
   \returns The first item, or NULL if list is empty.
+  \see item_first(), item_last(), item_next(), item_prev()
 */
 void* Fl_Browser::item_first() const {return first;}
 
@@ -70,7 +71,7 @@ void* Fl_Browser::item_first() const {return first;}
   Returns the next item after \p item.
   \param[in] item The 'current' item
   \returns The next item after \p item, or NULL if there are none after this one.
-  \see item_first()
+  \see item_first(), item_last(), item_next(), item_prev()
 */
 void* Fl_Browser::item_next(void* item) const {return ((FL_BLINE*)item)->next;}
 
@@ -78,7 +79,7 @@ void* Fl_Browser::item_next(void* item) const {return ((FL_BLINE*)item)->next;}
   Returns the previous item before \p item.
   \param[in] item The 'current' item
   \returns The previous item before \p item, or NULL if there none before this one.
-  \see item_last()
+  \see item_first(), item_last(), item_next(), item_prev()
 */
 void* Fl_Browser::item_prev(void* item) const {return ((FL_BLINE*)item)->prev;}
 
@@ -92,6 +93,7 @@ void* Fl_Browser::item_prev(void* item) const {return ((FL_BLINE*)item)->prev;}
   }
   \endcode
   \returns The last item, or NULL if list is empty.
+  \see item_first(), item_last(), item_next(), item_prev()
 */
 void* Fl_Browser::item_last() const {return last;}
 
@@ -99,6 +101,7 @@ void* Fl_Browser::item_last() const {return last;}
   See if \p item is selected.
   \param[in] item The item whose selection state is to be checked.
   \returns 1 if selected, 0 if not.
+  \see select(), selected(), value(), item_select(), item_selected()
 */
 int Fl_Browser::item_selected(void* item) const {
   return ((FL_BLINE*)item)->flags&SELECTED;
@@ -107,6 +110,7 @@ int Fl_Browser::item_selected(void* item) const {
   Change the selection state of \p item to the value \p val.
   \param[in] item The item to be changed.
   \param[in] val The new selection state: 1 selects, 0 de-selects.
+  \see select(), selected(), value(), item_select(), item_selected()
 */
 void Fl_Browser::item_select(void *item, int val) {
   if (val) ((FL_BLINE*)item)->flags |= SELECTED;
@@ -135,6 +139,7 @@ const char *Fl_Browser::item_text(void *item) const {
 
   \param[in] line The line number of the item to return. (1 based)
   \returns The returned item.
+  \see item_at(), find_line(), lineno()
 */
 FL_BLINE* Fl_Browser::find_line(int line) const {
   int n; FL_BLINE* l;
@@ -158,6 +163,7 @@ FL_BLINE* Fl_Browser::find_line(int line) const {
   Caveat: See efficiency note in find_line().
   \param[in] item The item to be found
   \returns The line number of the item, or 0 if not found.
+  \see item_at(), find_line(), lineno()
 */
 int Fl_Browser::lineno(void *item) const {
   FL_BLINE* l = (FL_BLINE*)item;
@@ -192,6 +198,7 @@ int Fl_Browser::lineno(void *item) const {
   You must call redraw() to make any changes visible.
   \param[in] line The line number to be removed. (1 based) Must be in range!
   \returns Pointer to browser item that was removed (and is no longer valid).
+  \see add(), insert(), remove(), swap(int,int), clear()
 */
 FL_BLINE* Fl_Browser::_remove(int line) {
   FL_BLINE* ttt = find_line(line);
@@ -214,6 +221,7 @@ FL_BLINE* Fl_Browser::_remove(int line) {
   You must call redraw() to make any changes visible.
   \param[in] line Line to be removed. (1 based) \n
                   If \p line is out of range, no action is taken.
+  \see add(), insert(), remove(), swap(int,int), clear()
 */
 void Fl_Browser::remove(int line) {
   if (line < 1 || line > lines) return;
@@ -342,6 +350,8 @@ void Fl_Browser::data(int line, void* d) {
   This takes into account embedded \@ codes within the text() label.
   \param[in] item The item whose height is returned.
   \returns The height of the item in pixels.
+  \see item_height(), item_width(),\n
+       incr_height(), full_height()
 */
 int Fl_Browser::item_height(void *item) const {
   FL_BLINE* l = (FL_BLINE*)item;
@@ -398,6 +408,8 @@ int Fl_Browser::item_height(void *item) const {
   This takes into account embedded \@ codes within the text() label.
   \param[in] item The item whose width is returned.
   \returns The width of the item in pixels.
+  \see item_height(), item_width(),\n
+       incr_height(), full_height()
 */
 int Fl_Browser::item_width(void *item) const {
   char* str = ((FL_BLINE*)item)->txt;
@@ -454,6 +466,8 @@ int Fl_Browser::item_width(void *item) const {
   This returns the accumulated height of *all* the items in the browser
   that are not hidden with hide(), including items scrolled off screen.
   \returns The accumulated size of all the visible items in pixels.
+  \see item_height(), item_width(),\n
+       incr_height(), full_height()
 */
 int Fl_Browser::full_height() const {
   return full_height_;
@@ -463,6 +477,8 @@ int Fl_Browser::full_height() const {
   The default 'average' item height (including inter-item spacing) in pixels.
   This currently returns textsize() + 2.
   \returns The value in pixels.
+  \see item_height(), item_width(),\n
+       incr_height(), full_height()
 */
 int Fl_Browser::incr_height() const {
   return textsize()+2;
@@ -576,6 +592,8 @@ Fl_Browser::Fl_Browser(int X, int Y, int W, int H, const char *L)
   Updates the browser so that \p line is shown at position \p pos.
   \param[in] line line number. (1 based)
   \param[in] pos position.
+  \see topline(), middleline(), bottomline(), \n
++: Command not found.
 */
 void Fl_Browser::lineposition(int line, Fl_Line_Position pos) {
   if (line<1) line = 1;
@@ -612,6 +630,7 @@ int Fl_Browser::topline() const {
 
 /**
   Removes all the lines in the browser.
+  \see add(), insert(), remove(), swap(int,int), clear()
 */
 void Fl_Browser::clear() {
   for (FL_BLINE* l = first; l;) {
@@ -636,6 +655,7 @@ void Fl_Browser::clear() {
 
   \param[in] newtext The label text used for the added item
   \param[in] d Optional user data() for the item (0 if unspecified)
+  \see add(), insert(), remove(), swap(int,int), clear()
 */
 void Fl_Browser::add(const char* newtext, void* d) {
   insert(lines+1, newtext, d);
@@ -673,6 +693,7 @@ void* Fl_Browser::data(int line) const {
   \param[in] line The line number of the item to be changed. (1 based)
   \param[in] val The new selection state (1=select, 0=de-select).
   \returns 1 if the state changed, 0 if not.
+  \see select(), selected(), value(), item_select(), item_selected()
 */
 int Fl_Browser::select(int line, int val) {
   if (line < 1 || line > lines) return 0;
@@ -683,6 +704,7 @@ int Fl_Browser::select(int line, int val) {
   Returns 1 if specified \p line is selected, 0 if not.
   \param[in] line The line being checked (1 based)
   \returns 1 if item selected, 0 if not.
+  \see select(), selected(), value(), item_select(), item_selected()
   */
 int Fl_Browser::selected(int line) const {
   if (line < 1 || line > lines) return 0;
@@ -695,6 +717,7 @@ int Fl_Browser::selected(int line) const {
   This changes the full_height() if the state was changed.
   redraw() is called automatically if a change occurred.
   \param[in] line The line to be shown. (1 based)
+  \see show(int), hide(int), display(), visible(), make_visible()
 */
 void Fl_Browser::show(int line) {
   FL_BLINE* t = find_line(line);
@@ -712,6 +735,7 @@ void Fl_Browser::show(int line) {
   When a line is made invisible, lines below it are moved up in the display.
   redraw() is called automatically if a change occurred.
   \param[in] line The line to be hidden. (1 based)
+  \see show(int), hide(int), display(), visible(), make_visible()
 */
 void Fl_Browser::hide(int line) {
   FL_BLINE* t = find_line(line);
@@ -726,7 +750,7 @@ void Fl_Browser::hide(int line) {
   For back compatibility.
   This calls show(line) if \p val is true, and hide(line) otherwise.
   If \p val is not specified, the default is 1 (makes the line visible).
-  \see show(int line), hide(int line)
+  \see show(int), hide(int), display(), visible(), make_visible()
 */
 void Fl_Browser::display(int line, int val) {
   if (line < 1 || line > lines) return;
@@ -737,6 +761,7 @@ void Fl_Browser::display(int line, int val) {
   Returns non-zero if the specified \p line is visible, 0 if hidden.
   Use show(int), hide(int), or make_visible(int) to change an item's visible state.
   \param[in] line The line in the browser to be tested. (1 based)
+  \see show(int), hide(int), display(), visible(), make_visible()
 */
 int Fl_Browser::visible(int line) const {
   if (line < 1 || line > lines) return 0;
@@ -746,6 +771,7 @@ int Fl_Browser::visible(int line) const {
 /**
   Returns the line number of the currently selected line, or 0 if none.
   \returns The line number of current selection, or 0 if none selected.
+  \see select(), selected(), value(), item_select(), item_selected()
 */
 int Fl_Browser::value() const {
   return lineno(selection());
@@ -755,6 +781,7 @@ int Fl_Browser::value() const {
   Swap the two items \p a and \p b.
   Uses swapping() to ensure list updates correctly.
   \param[in] a,b The two items to be swapped.
+  \see swap(int,int), item_swap()
 */
 void Fl_Browser::swap(FL_BLINE *a, FL_BLINE *b) {
 
@@ -799,6 +826,7 @@ void Fl_Browser::swap(FL_BLINE *a, FL_BLINE *b) {
   Swaps two browser lines \p a and \p b.
   You must call redraw() to make any changes visible.
   \param[in] a,b The two lines to be swapped. (both 1 based)
+  \see swap(int,int), item_swap()
 */
 void Fl_Browser::swap(int a, int b) {
   if (a < 1 || a > lines || b < 1 || b > lines) return;

src/Fl_Browser_.cxx

@@ -157,7 +157,7 @@ void Fl_Browser_::resize(int X, int Y, int W, int H) {
   This method should be called when the contents of \p item has changed,
   but not its height.
   \param[in] item The item that needs to be redrawn.
-  \see Related methods: redraw_lines(), redraw_line()
+  \see redraw_lines(), redraw_line()
 */
 void Fl_Browser_::redraw_line(void* item) {
   if (!redraw1 || redraw1 == item) {redraw1 = item; damage(FL_DAMAGE_EXPOSE);}
@@ -227,7 +227,7 @@ void Fl_Browser_::update_top() {
   of the screen. Example: A position of '3' scrolls the top three pixels of
   the list off the top edge of the screen.
   \param[in] pos The vertical position (in pixels) to scroll the browser to.
-  \see Related methods: position(), hposition()
+  \see position(), hposition()
 */
 void Fl_Browser_::position(int pos) {
   if (pos < 0) pos = 0;
@@ -242,7 +242,7 @@ void Fl_Browser_::position(int pos) {
   of the screen. Example: A position of '18' scrolls the left 18 pixels of the list
   off the left edge of the screen.
   \param[in] pos The horizontal position (in pixels) to scroll the browser to.
-  \see Related methods: position(), hposition()
+  \see position(), hposition()
 */
 void Fl_Browser_::hposition(int pos) {
   if (pos < 0) pos = 0;
@@ -259,6 +259,7 @@ void Fl_Browser_::hposition(int pos) {
   status of the widget or item.
   \param[in] item The item to check
   \returns 1 if visible, 0 if not visible.
+  \see display(), displayed()
 */
 int Fl_Browser_::displayed(void* item) const {
   int X, Y, W, H; bbox(X, Y, W, H);
@@ -275,6 +276,7 @@ int Fl_Browser_::displayed(void* item) const {
 /**
   Displays the \p item, scrolling the list as necessary.
   \param[in] item The item to be displayed.
+  \see display(), displayed()
 */
 void Fl_Browser_::display(void* item) {
 

src/Fl_Browser_load.cxx

@@ -37,6 +37,9 @@
   was any error in opening or reading the file, in which case errno
   is set to the system error.  The data() of each line is set
   to NULL.
+  \param[in] filename The filename to load
+  \returns 1 if OK, 0 on error (errno has reason)
+  \see add()
 */
 int Fl_Browser::load(const char *filename) {
 #define MAXFL_BLINE 1024
@@ -54,8 +57,9 @@ int Fl_Browser::load(const char *filename) {
 	    newtext[i] = 0;
 	    add(newtext);
 	    i = 0;
-	} else
+	} else {
 	    newtext[i++] = c;
+	}
     } while (c >= 0);
     fclose(fl);
     return 1;