o Major mods to Fl_Browser_.{cxx.H}'s doxygen docs

	o Small mods to Fl_Browser.{cxx,H}'s doxygen docs
	o FL_SORT_ASC/DESC -> FL_SORT_ASCENDING/DESCENDING (includes necessary mod to test/browser.cxx demo)

	TODO: Fl_Browser needs new '\see Related methods: ' that was initiated in Fl_Browser_



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

1 files changed, 212 insertions, 128 deletions

diff --git a/src/Fl_Browser_.cxx b/src/Fl_Browser_.cxx
index edf972f7d..1a150335c 100644
--- a/src/Fl_Browser_.cxx
+++ b/src/Fl_Browser_.cxx
@@ -36,7 +36,7 @@
 
 // This is the base class for browsers.  To be useful it must be
 // subclassed and several virtual functions defined.  The
-// Forms-compatable browser and the file chooser's browser are
+// Forms-compatible browser and the file chooser's browser are
 // subclassed off of this.
 
 // Yes, I know this should be a template...
@@ -72,22 +72,26 @@ static void hscrollbar_callback(Fl_Widget* s, void*) {
 int Fl_Browser_::scrollbar_width_ = 16;
 
 /**
-    Gets the default scrollbar size that is used by the
-    Fl_Browser_,
-    Fl_Help_View,
-    Fl_Scroll, and
-    Fl_Text_Display widgets.
+  Gets the default scrollbar size used by 
+  Fl_Browser_,
+  Fl_Help_View,
+  Fl_Scroll, and
+  Fl_Text_Display widgets.
+  \returns The default size for widget scrollbars, in pixels.
+  \todo The source code for this method needs to be moved from Fl_Browser_.cxx to Fl.cxx
 */
 int Fl::scrollbar_size() {
   return Fl_Browser_::scrollbar_width();
 }
 
 /**
-    Sets the default scrollbar size that is used by the
-    Fl_Browser_,
-    Fl_Help_View,
-    Fl_Scroll, and
-    Fl_Text_Display widgets.
+  Sets the default scrollbar size that is used by the
+  Fl_Browser_,
+  Fl_Help_View,
+  Fl_Scroll, and
+  Fl_Text_Display widgets.
+  \param[in] W The new default size for widget scrollbars, in pixels.
+  \todo The source code for this method needs to be moved from Fl_Browser_.cxx to Fl.cxx
 */
 void Fl::scrollbar_size(int W) {
   Fl_Browser_::scrollbar_width(W);
@@ -95,8 +99,10 @@ void Fl::scrollbar_size(int W) {
 
 // return where to draw the actual box:
 /**
-  This method returns the bounding box for the interior of the list, inside
+  Returns the bounding box for the interior of the list's display window, inside
   the scrollbars.
+  \param[out] X,Y,W,H The returned bounding box.\n
+                      (The original contents of these parameters are overwritten)
 */
 void Fl_Browser_::bbox(int& X, int& Y, int& W, int& H) const {
   Fl_Boxtype b = box() ? box() : FL_DOWN_BOX;
@@ -119,6 +125,8 @@ void Fl_Browser_::bbox(int& X, int& Y, int& W, int& H) const {
 /**
   This method returns the X position of the left edge of the list area
   after adjusting for the scrollbar and border, if any.
+  \returns The X position of the left edge of the list, in pixels.
+  \see Fl_Browser_::bbox()
 */
 int Fl_Browser_::leftedge() const {
   int X, Y, W, H; bbox(X, Y, W, H);
@@ -128,7 +136,10 @@ int Fl_Browser_::leftedge() const {
 // The scrollbars may be moved again by draw(), since each one's size
 // depends on whether the other is visible or not.  This skips over
 // Fl_Group::resize since it moves the scrollbars uselessly.
-/**  Repositions and/or resizes the browser.*/
+/**
+  Repositions and/or resizes the browser.
+  \param[in] X,Y,W,H The new position and size for the browser, in pixels.
+*/
 void Fl_Browser_::resize(int X, int Y, int W, int H) {
   Fl_Widget::resize(X, Y, W, H);
   // move the scrollbars so they can respond to events:
@@ -143,12 +154,14 @@ void Fl_Browser_::resize(int X, int Y, int W, int H) {
 
 // Cause minimal update to redraw the given item:
 /**
-  This method should be called when the contents of an item have changed
-  but not changed the height of the item.
+  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()
 */
-void Fl_Browser_::redraw_line(void* l) {
-  if (!redraw1 || redraw1 == l) {redraw1 = l; damage(FL_DAMAGE_EXPOSE);}
-  else if (!redraw2 || redraw2 == l) {redraw2 = l; damage(FL_DAMAGE_EXPOSE);}
+void Fl_Browser_::redraw_line(void* item) {
+  if (!redraw1 || redraw1 == item) {redraw1 = item; damage(FL_DAMAGE_EXPOSE);}
+  else if (!redraw2 || redraw2 == item) {redraw2 = item; damage(FL_DAMAGE_EXPOSE);}
   else damage(FL_DAMAGE_SCROLL);
 }
 
@@ -209,39 +222,49 @@ void Fl_Browser_::update_top() {
 // Change position(), top() will update when update_top() is called
 // (probably by draw() or handle()):
 /**
-  Gets or sets the vertical scrolling position of the list,
-  which is the pixel offset of the list items within the list
-  area.
+  Sets the vertical scroll position of the list to pixel position \p pos.
+  The position is how many pixels of the list are scrolled off the top edge
+  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()
 */
-void Fl_Browser_::position(int yy) {
-  if (yy < 0) yy = 0;
-  if (yy == position_) return;
-  position_ = yy;
-  if (yy != real_position_) redraw_lines();
+void Fl_Browser_::position(int pos) {
+  if (pos < 0) pos = 0;
+  if (pos == position_) return;
+  position_ = pos;
+  if (pos != real_position_) redraw_lines();
 }
 
 /**
-  Gets or sets the horizontal scrolling position of the list,
-  which is the pixel offset of the list items within the list
-  area.
+  Sets the horizontal scroll position of the list to pixel position \p pos.
+  The position is how many pixels of the list are scrolled off the left edge
+  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()
 */
-void Fl_Browser_::hposition(int xx) {
-  if (xx < 0) xx = 0;
-  if (xx == hposition_) return;
-  hposition_ = xx;
-  if (xx != real_hposition_) redraw_lines();
+void Fl_Browser_::hposition(int pos) {
+  if (pos < 0) pos = 0;
+  if (pos == hposition_) return;
+  hposition_ = pos;
+  if (pos != real_hposition_) redraw_lines();
 }
 
 // Tell whether item is currently displayed:
 /**
-  This method returns non-zero if item p is currently visible in
-  the list.
+  Returns non-zero if \p item 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] item The item to check
+  \returns 1 if visible, 0 if not visible.
 */
-int Fl_Browser_::displayed(void* p) const {
+int Fl_Browser_::displayed(void* item) const {
   int X, Y, W, H; bbox(X, Y, W, H);
   int yy = H+offset_;
   for (void* l = top_; l && yy > 0; l = item_next(l)) {
-    if (l == p) return 1;
+    if (l == item) return 1;
     yy -= item_height(l);
   }
   return 0;
@@ -249,12 +272,15 @@ int Fl_Browser_::displayed(void* p) const {
 
 // Ensure this item is displayed:
 // Messy because we have no idea if it is before top or after bottom:
-/**  Displays item p, scrolling the list as necessary.*/
-void Fl_Browser_::display(void* p) {
+/**
+  Displays the \p item, scrolling the list as necessary.
+  \param[in] item The item to be displayed.
+*/
+void Fl_Browser_::display(void* item) {
 
   // First special case - want to display first item in the list?
   update_top();
-  if (p == item_first()) {position(0); return;}
+  if (item == item_first()) {position(0); return;}
 
   int X, Y, W, H, Yp; bbox(X, Y, W, H);
   void* l = top_;
@@ -262,11 +288,11 @@ void Fl_Browser_::display(void* p) {
   int h1;
 
   // 2nd special case - want to display item already displayed at top of browser?
-  if (l == p) {position(real_position_+Y); return;} // scroll up a bit
+  if (l == item) {position(real_position_+Y); return;} // scroll up a bit
 
   // 3rd special case - want to display item just above top of browser?
   void* lp = item_prev(l);
-  if (lp == p) {position(real_position_+Y-item_quick_height(lp)); return;}
+  if (lp == item) {position(real_position_+Y-item_quick_height(lp)); return;}
 
 #ifdef DISPLAY_SEARCH_BOTH_WAYS_AT_ONCE
   // search for item.  We search both up and down the list at the same time,
@@ -275,7 +301,7 @@ void Fl_Browser_::display(void* p) {
   while (l || lp) {
     if (l) {
       h1 = item_quick_height(l);
-      if (l == p) {
+      if (l == item) {
 	if (Y <= H) { // it is visible or right at bottom
 	  Y = Y+h1-H; // find where bottom edge is
 	  if (Y > 0) position(real_position_+Y); // scroll down a bit
@@ -290,7 +316,7 @@ void Fl_Browser_::display(void* p) {
     if (lp) {
       h1 = item_quick_height(lp);
       Yp -= h1;
-      if (lp == p) {
+      if (lp == item) {
 	if ((Yp + h1) >= 0) position(real_position_+Yp);
 	else position(real_position_+Yp-(H-h1)/2);
 	return;
@@ -304,7 +330,7 @@ void Fl_Browser_::display(void* p) {
   l = top_;
   for (; l; l = item_next(l)) {
     h1 = item_quick_height(l);
-    if (l == p) {
+    if (l == item) {
       if (Y <= H) { // it is visible or right at bottom
 	Y = Y+h1-H; // find where bottom edge is
 	if (Y > 0) position(real_position_+Y); // scroll down a bit
@@ -321,7 +347,7 @@ void Fl_Browser_::display(void* p) {
   for (; l; l = item_prev(l)) {
     h1 = item_quick_height(l);
     Y -= h1;
-    if (l == p) {
+    if (l == item) {
       if ((Y + h1) >= 0) position(real_position_+Y);
       else position(real_position_+Y-(H-h1)/2);
       return;
@@ -331,7 +357,6 @@ void Fl_Browser_::display(void* p) {
 }
 
 // redraw, has side effect of updating top and setting scrollbar:
-
 /**
   Draws the list within the normal widget bounding box.
 */
@@ -490,6 +515,8 @@ J1:
   This method should be called when the list data is completely replaced
   or cleared. It informs the Fl_Browser_ widget that any cached
   information it has concerning the items is invalid.
+  This method does not clear the list, it just handles the follow up
+  bookkeeping after the list has been cleared.
 */
 void Fl_Browser_::new_list() {
   top_ = 0;
@@ -505,18 +532,20 @@ void Fl_Browser_::new_list() {
 // Tell it that this item is going away, and that this must remove
 // all pointers to it:
 /**
-  This method should be used when an item is deleted from the list.
-  It allows the Fl_Browser_ to discard any cached data it has
-  on the item.
+  This method should be used when \p item is being deleted from the list.
+  It allows the Fl_Browser_ to discard any cached data it has on the item.
+  This method does not actually delete the item, but handles the follow up
+  bookkeeping after the item has just been deleted.
+  \param[in] item The item being deleted.
 */
-void Fl_Browser_::deleting(void* l) {
-  if (displayed(l)) {
+void Fl_Browser_::deleting(void* item) {
+  if (displayed(item)) {
     redraw_lines();
-    if (l == top_) {
+    if (item == top_) {
       real_position_ -= offset_;
       offset_ = 0;
-      top_ = item_next(l);
-      if (!top_) top_ = item_prev(l);
+      top_ = item_next(item);
+      if (!top_) top_ = item_prev(item);
     }
   } else {
     // we don't know where this item is, recalculate top...
@@ -524,13 +553,18 @@ void Fl_Browser_::deleting(void* l) {
     offset_ = 0;
     top_ = 0;
   }
-  if (l == selection_) selection_ = 0;
-  if (l == max_width_item) {max_width_item = 0; max_width = 0;}
+  if (item == selection_) selection_ = 0;
+  if (item == max_width_item) {max_width_item = 0; max_width = 0;}
 }
 
 /**
-  This method should be used when an item is replaced in the list.
-  It allows the Fl_Browser_ to update its cache data as needed.
+  This method should be used when item \p a is being replaced by item \p b.
+  It allows the Fl_Browser_ to update its cache data as needed,
+  schedules a redraw for the item being changed, and tries to maintain the selection.
+  This method does not actually replace the item, but handles the follow up
+  bookkeeping after the item has just been replaced.
+  \param[in] a Item being replaced
+  \param[in] b Item to replace 'a'
 */
 void Fl_Browser_::replacing(void* a, void* b) {
   redraw_line(a);
@@ -540,7 +574,12 @@ void Fl_Browser_::replacing(void* a, void* b) {
 }
 
 /**
-  Exchange pointers \p a and \p b.
+  This method should be used when two items \p a and \p b are being swapped.
+  It allows the Fl_Browser_ to update its cache data as needed,
+  schedules a redraw for the two items, and tries to maintain the current selection.
+  This method does not actually swap items, but handles the follow up
+  bookkeeping after items have been swapped.
+  \param[in] a,b Items being swapped.
 */
 void Fl_Browser_::swapping(void* a, void* b) {
   redraw_line(a);
@@ -552,8 +591,14 @@ void Fl_Browser_::swapping(void* a, void* b) {
 }
 
 /**
-  This method should be used when an item is added to the list.
-  It allows the Fl_Browser_ to update its cache data as needed.
+  This method should be used when an item is in the process of
+  being inserted into the list.
+  It allows the Fl_Browser_ to update its cache data as needed,
+  scheduling a redraw for the affected lines.
+  This method does not actually insert items, but handles the 
+  follow up bookkeeping after items have been inserted.
+  \param[in] a The starting item position
+  \param[in] b The new item being inserted
 */
 void Fl_Browser_::inserting(void* a, void* b) {
   if (displayed(a)) redraw_lines();
@@ -561,52 +606,59 @@ void Fl_Browser_::inserting(void* a, void* b) {
 }
 
 /**
-  This method returns the item under mouse at my. If no item is
-  displayed at that position then NULL is returned.
+  This method returns the item under mouse y position \p ypos.
+  NULL is returned if no item is displayed at that position.
+  \param[in] ypos The y position (eg. Fl::event_y()) to find an item under.
+  \returns The item, or NULL if not found
 */
-void* Fl_Browser_::find_item(int my) {
+void* Fl_Browser_::find_item(int ypos) {
   update_top();
   int X, Y, W, H; bbox(X, Y, W, H);
-  void* l;
   int yy = Y-offset_;
-  for (l = top_; l; l = item_next(l)) {
+  for (void *l = top_; l; l = item_next(l)) {
     int hh = item_height(l); if (hh <= 0) continue;
     yy += hh;
-    if (my <= yy || yy>=(Y+H)) return l;
+    if (ypos <= yy || yy>=(Y+H)) return l;
   }
   return 0;
 }
 
 /**
-  Sets the selection state of item p to s and
-  returns 1 if the state changed or 0 if it did not.
+  Sets the selection state of \p item to \p val,
+  and returns 1 if the state changed or 0 if it did not.
   
-  <P>If docb is non-zero, select tries to call the callback
-  function for the widget.
+  If \p docallbacks is non-zero, select tries to call
+  the callback function for the widget.
+
+  \param[in] item The item whose selection state is to be changed
+  \param[in] val The new selection state (1=select, 0=de-select)
+  \param[in] docallbacks If 1, invokes widget callback if item changed.\n
+                         If 0, doesn't do callback (default).
+  \returns 1 if state was changed, 0 if not.
 */
-int Fl_Browser_::select(void* l, int i, int docallbacks) {
+int Fl_Browser_::select(void* item, int val, int docallbacks) {
   if (type() == FL_MULTI_BROWSER) {
-    if (selection_ != l) {
+    if (selection_ != item) {
       if (selection_) redraw_line(selection_);
-      selection_ = l;
-      redraw_line(l);
+      selection_ = item;
+      redraw_line(item);
     }
-    if ((!i)==(!item_selected(l))) return 0;
-    item_select(l, i);
-    redraw_line(l);
+    if ((!val)==(!item_selected(item))) return 0;
+    item_select(item, val);
+    redraw_line(item);
   } else {
-    if (i && selection_ == l) return 0;
-    if (!i && selection_ != l) return 0;
+    if (val && selection_ == item) return 0;
+    if (!val && selection_ != item) return 0;
     if (selection_) {
       item_select(selection_, 0);
       redraw_line(selection_);
       selection_ = 0;
     }
-    if (i) {
-      item_select(l, 1);
-      selection_ = l;
-      redraw_line(l);
-      display(l);
+    if (val) {
+      item_select(item, 1);
+      selection_ = item;
+      redraw_line(item);
+      display(item);
     }
   }	    
   if (docallbacks) {
@@ -620,8 +672,11 @@ int Fl_Browser_::select(void* l, int i, int docallbacks) {
   Deselects all items in the list and returns 1 if the state changed
   or 0 if it did not.
   
-  <P>If docb is non-zero, deselect tries to call the
-  callback function for the widget.
+  If the optional \p docallbacks parameter is non-zero, deselect tries
+  to call the callback function for the widget.
+
+  \param[in] docallbacks If 1, invokes widget callback if item changed.\n
+                         If 0, doesn't do callback (default).
 */
 int Fl_Browser_::deselect(int docallbacks) {
   if (type() == FL_MULTI_BROWSER) {
@@ -639,24 +694,29 @@ int Fl_Browser_::deselect(int docallbacks) {
 }
 
 /**
-  Selects item p and returns 1 if the state changed or 0 if it did
-  not. Any other items in the list are deselected.
-  
-  <P>If docb is non-zero, select_only tries to call the
-  callback function for the widget.
+  Selects \p item and returns 1 if the state changed or 0 if it did not.
+  Any other items in the list are deselected.
+  \param[in] item The \p item to select.
+  \param[in] docallbacks If 1, invokes widget callback if item changed.\n
+                         If 0, doesn't do callback (default).
 */
-int Fl_Browser_::select_only(void* l, int docallbacks) {
-  if (!l) return deselect(docallbacks);
+int Fl_Browser_::select_only(void* item, int docallbacks) {
+  if (!item) return deselect(docallbacks);
   int change = 0;
   if (type() == FL_MULTI_BROWSER) {
     for (void* p = item_first(); p; p = item_next(p))
-      if (p != l) change |= select(p, 0, docallbacks);
+      if (p != item) change |= select(p, 0, docallbacks);
   }
-  change |= select(l, 1, docallbacks);
-  display(l);
+  change |= select(item, 1, docallbacks);
+  display(item);
   return change;
 }
-/** Handles an event within the normal widget bounding box. */
+
+/**
+  Handles the \p event within the normal widget bounding box.
+  \param[in] event The event to process.
+  \returns 1 if event was processed, 0 if not.
+*/
 int Fl_Browser_::handle(int event) {
   // must do shortcuts first or the scrollbar will get them...
   if (event == FL_ENTER || event == FL_LEAVE) return 1;
@@ -873,9 +933,13 @@ J1:
   return 0;
 }
 
-/** The constructor makes an empty browser.*/
-Fl_Browser_::Fl_Browser_(int X, int Y, int W, int H, const char* l)
-  : Fl_Group(X, Y, W, H, l),
+/**
+  The constructor makes an empty browser.
+  \param[in] X,Y,W,H position and size.
+  \param[in] L The label string, may be NULL.
+*/
+Fl_Browser_::Fl_Browser_(int X, int Y, int W, int H, const char* L)
+  : Fl_Group(X, Y, W, H, L),
     scrollbar(0, 0, 0, 0, 0), // they will be resized by draw()
     hscrollbar(0, 0, 0, 0, 0)
 {
@@ -902,11 +966,20 @@ Fl_Browser_::Fl_Browser_(int X, int Y, int W, int H, const char* l)
   end();
 }
 
-/*
- * Simple bubble sort - pure lazyness on my side.
- */
+/**
+  Sort the items in the browser based on \p flags.
+  item_swap(void*, void*) and item_text(void*) must be implemented for this call.
+  \param[in] flags FL_SORT_ASCENDING -- sort in ascending order\n
+                   FL_SORT_DESCENDING -- sort in descending order\n
+		   Values other than the above will cause undefined behavior\n
+		   Other flags may appear in the future.
+  \todo Add a flag to ignore case
+*/
 void Fl_Browser_::sort(int flags) {
-  int i, j, n = -1, desc = ((flags&FL_SORT_DESC)==FL_SORT_DESC);
+  //
+  // Simple bubble sort - pure lazyness on my side.
+  //
+  int i, j, n = -1, desc = ((flags&FL_SORT_DESCENDING)==FL_SORT_DESCENDING);
   void *a =item_first(), *b, *c;
   if (!a) return;
   while (a) {
@@ -943,20 +1016,23 @@ void Fl_Browser_::sort(int flags) {
 
 /**
   This method may be provided by the subclass to return the height of the
-  item p in pixels.  Allow for two additional pixels for the list
-  selection box.  This method differs from
-  item_height in that it is only
-  called for selection and scrolling operations. The default implementation
-  calls item_height.
+  \p item, in pixels.  
+  Allow for two additional pixels for the list selection box.
+  This method differs from item_height in that it is only called for 
+  selection and scrolling operations. 
+  The default implementation calls item_height.
+  \param[in] item The item whose height to return.
+  \returns The height, in pixels.
 */
-int Fl_Browser_::item_quick_height(void* l) const {
-  return item_height(l);
+int Fl_Browser_::item_quick_height(void* item) const {
+  return item_height(item);
 }
 
 /**
-  This method may be provided to return the average height of all items, to
-  be used for scrolling. The default implementation uses the height of the first
-  item.
+  This method may be provided to return the average height of all items
+  to be used for scrolling. 
+  The default implementation uses the height of the first item.
+  \returns The average height of items, in pixels.
 */
 int Fl_Browser_::incr_height() const {
   return item_quick_height(item_first());
@@ -964,8 +1040,10 @@ int Fl_Browser_::incr_height() const {
 
 /**
   This method may be provided by the subclass to indicate the full height
-  of the item list in pixels. The default implementation computes the full
-  height from the item heights.
+  of the item list, in pixels. 
+  The default implementation computes the full height from the item heights. 
+  Includes the items that are scrolled off screen.
+  \returns The height of the entire list, in pixels.
 */
 int Fl_Browser_::full_height() const {
   int t = 0;
@@ -976,26 +1054,32 @@ int Fl_Browser_::full_height() const {
 
 /**
   This method may be provided by the subclass to indicate the full width
-  of the item list in pixels. The default implementation computes the full
-  width from the item widths.
+  of the item list, in pixels. 
+  The default implementation computes the full width from the item widths.
+  \returns The maximum width of all the items, in pixels.
 */
 int Fl_Browser_::full_width() const {
   return max_width;
 }
 
 /**
-  This method must be implemented by the subclass if it supports
-  multiple selections in the browser. The s argument specifies the
-  selection state for item p: 0 = off, 1 = on.
+  This method must be implemented by the subclass if it supports 
+  multiple selections; sets the selection state to \p val for the \p item.
+  Sets the selection state for \p item, where optional \p val is 1 (select, the default)
+  or 0 (de-select).
+  \param[in] item The item to be selected
+  \param[in] val The optional selection state; 1=select, 0=de-select.\n
+                 The default is to select the item (1).
 */
-void Fl_Browser_::item_select(void*, int) {}
+void Fl_Browser_::item_select(void *item, int val) {}
 
 /**
   This method must be implemented by the subclass if it supports
-  multiple selections in the browser. The method should return 1 if p
-  is selected and 0 otherwise.
+  multiple selections; returns the selection state for \p item.
+  The method should return 1 if \p item is selected, or 0 otherwise.
+  \param[in] item The item to test.
 */
-int Fl_Browser_::item_selected(void* l) const {return l==selection_;}
+int Fl_Browser_::item_selected(void* item) const { return item==selection_ ? 1 : 0; }
 
 //
 // End of "$Id$".