Author: greg.ercolano
Date: 2009-03-25 16:09:04 -0700 (Wed, 25 Mar 2009)
New Revision: 6720
Log:
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_
Modified:
branches/branch-1.3/FL/Fl_Browser.H
branches/branch-1.3/FL/Fl_Browser_.H
branches/branch-1.3/src/Fl_Browser.cxx
branches/branch-1.3/src/Fl_Browser_.cxx
branches/branch-1.3/test/browser.cxx
Modified: branches/branch-1.3/FL/Fl_Browser.H
===================================================================
--- branches/branch-1.3/FL/Fl_Browser.H 2009-03-25 16:38:28 UTC (rev 6719)
+++ branches/branch-1.3/FL/Fl_Browser.H 2009-03-25 23:09:04 UTC (rev 6720)
@@ -139,46 +139,61 @@
void swap(int a, int b);
void clear();
- /** Returns how many lines are in the browser.
- The last line number is equal to this.
- Returns 0 if browser is empty.
+ /**
+ Returns how many lines are in the browser.
+ The last line number is equal to this.
+ Returns 0 if browser is empty.
*/
- int size() const {return lines;}
+ int size() const { return lines; }
void size(int W, int H) { Fl_Widget::size(W, H); }
int topline() const ;
/** For internal use only? */
enum Fl_Line_Position { TOP, BOTTOM, MIDDLE };
void lineposition(int line, Fl_Line_Position pos);
- /** Scrolls the browser so the top item in the browser is showing the
specified \p line. */
+ /**
+ 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.
+ */
void topline(int line) { lineposition(line, TOP); }
- /** Scrolls the browser so the bottom item in the browser is showing the
specified \p line. */
+ /**
+ 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.
+ */
void bottomline(int line) { lineposition(line, BOTTOM); }
- /** Scrolls the browser so the middle item in the browser is showing the
specified \p line. */
+ /**
+ 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.
+ */
void middleline(int line) { lineposition(line, MIDDLE); }
int select(int line, int val=1);
int selected(int line) const ;
void show(int line);
/** Shows the entire Fl_Browser widget -- opposite of hide(). */
- void show() {Fl_Widget::show();}
+ void show() { Fl_Widget::show(); }
void hide(int line);
/** Hides the entire Fl_Browser widget -- opposite of show(). */
- void hide() {Fl_Widget::hide();}
+ void hide() { Fl_Widget::hide(); }
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).
*/
- void value(int line) { select(line);}
+ void value(int line) { select(line); }
const char* text(int line) const ;
void text(int line, const char* newtext);
void* data(int line) const ;
void data(int line, void* d);
Fl_Browser(int X, int Y, int W, int H, const char *L = 0);
- /** The destructor deletes all list items and destroys the browser. */
+ /**
+ The destructor deletes all list items and destroys the browser.
+ */
~Fl_Browser() { clear(); }
/**
@@ -210,24 +225,24 @@
<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_;}
+ 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
*/
- void format_char(char c) {format_char_ = c;}
+ void format_char(char c) { format_char_ = c; }
/**
Gets the current column separator character.
The default is '\\t' (tab).
*/
- char column_char() const {return column_char_;}
+ 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).
*/
- void column_char(char c) {column_char_ = c;}
+ void column_char(char c) { column_char_ = c; }
/**
Gets the current column width array.
This array is zero-terminated and specifies the widths in pixels of
@@ -250,17 +265,17 @@
[..]
\endcode
*/
- const int* column_widths() const {return 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
*/
- void column_widths(const int* arr) {column_widths_ = arr;}
+ void column_widths(const int* arr) { column_widths_ = arr; }
/**
Returns non-zero if \p line is visible.
*/
- int displayed(int line) const {return
Fl_Browser_::displayed(find_line(line));}
+ int displayed(int line) const { return
Fl_Browser_::displayed(find_line(line)); }
/**
Make the item at the specified \p line visible().
@@ -276,7 +291,7 @@
}
/** For back compatibility only. */
- void replace(int a, const char* b) {text(a, b);}
+ void replace(int a, const char* b) { text(a, b); }
void display(int line, int val=1);
};
Modified: branches/branch-1.3/FL/Fl_Browser_.H
===================================================================
--- branches/branch-1.3/FL/Fl_Browser_.H 2009-03-25 16:38:28 UTC (rev
6719)
+++ branches/branch-1.3/FL/Fl_Browser_.H 2009-03-25 23:09:04 UTC (rev
6720)
@@ -28,11 +28,6 @@
/* \file
Fl_Browser_ widget . */
-// 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
-// subclassed off of this.
-
// Yes, I know this should be a template...
#ifndef Fl_Browser__H
@@ -48,11 +43,11 @@
#define FL_HOLD_BROWSER 2 /**< type() of Fl_Hold_Browser
*/
#define FL_MULTI_BROWSER 3 /**< type() of Fl_Multi_Browser */
-#define FL_SORT_ASC 0 /**< sort browser items in ascending
alphabetic order. */
-#define FL_SORT_DESC 1 /**< sort in descending order */
+#define FL_SORT_ASCENDING 0 /**< sort browser items in ascending
alphabetic order. */
+#define FL_SORT_DESCENDING 1 /**< sort in descending order */
/**
- This is the base for browsers. To be useful it must be
+ This is the base class for browsers. To be useful it must be
subclassed and several virtual functions defined. The Forms-compatible
browser and the file chooser's browser are subclassed off of this.
@@ -91,211 +86,237 @@
protected:
// All of the following must be supplied by the subclass:
- /** This method must be provided by the subclass to return the first item in
the list. */
- virtual void *item_first() const = 0;
- /** This method must be provided by the subclass to return the item in the
list after p. */
- virtual void *item_next(void *) const = 0;
- /** This method must be provided by the subclass to return the item in the
list before p. */
- virtual void *item_prev(void *) const = 0;
- /** This method can be provided by the subclass to return the ilast item in
the list. */
- virtual void *item_last() const { return 0L; }
+ /**
+ 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()
+ */
+ 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()
+ */
+ 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()
+ */
+ 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()
+ */
+ virtual void *item_last() const { return 0L; }
/**
- This method must 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 must be provided by the subclass to return
+ the height of \p item in pixels.
+ 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()
*/
- virtual int item_height(void *) const = 0;
+ virtual int item_height(void *item) const = 0;
/**
This method must be provided by the subclass to return the width of the
- item p in pixels. Allow for two additional pixels for the list
+ \p item in pixels. Allow for two additional pixels for the list
selection box.
+ \param[in] item The item whose width is returned.
+ \returns The width of the item in pixels.
*/
- virtual int item_width(void *) const = 0;
- virtual int item_quick_height(void *) const ;
+ virtual int item_width(void *item) const = 0;
+ virtual int item_quick_height(void *item) const ;
/**
- This method must be provided by the subclass to draw the item
- p in the area indicated by x, y, w,
- and h.
+ This method must be provided by the subclass to draw the \p item
+ in the area indicated by \p X, \p Y, \p W, \p H.
*/
- virtual void item_draw(void *,int,int,int,int) const = 0;
+ virtual void item_draw(void *item,int X,int Y,int W,int H) const = 0;
/**
- This optional function returns a string that may be used for sorting.
+ This optional method returns a string (label) that may be used for
sorting.
+ \param[in] item The item whose label text is returned.
+ \returns The item's text label. (Can be NULL if blank)
*/
virtual const char *item_text(void *item) const { return 0L; }
/**
- This optional function is required for sorting browser items.
+ This optional method should be provided by the subclass
+ to efficiently swap browser items \p a and \p b, such as for sorting.
+ \param[in] a,b The two items to be swapped.
*/
- virtual void item_swap(void*, void*) { }
+ virtual void item_swap(void *a,void *b) { }
/**
- Return the item a specified index.
+ This method must be provided by the subclass
+ to return the item for the specified \p index.
+ \param[in] index The \p index of the item to be returned
+ \returns The item at the specified \p index.
*/
- virtual void *item_at(int) const { return 0L; }
+ virtual void *item_at(int index) const { return 0L; }
// you don't have to provide these but it may help speed it up:
virtual int full_width() const ; // current width of all items
virtual int full_height() const ; // current height of all items
virtual int incr_height() const ; // average height of an item
// These only need to be done by subclass if you want a multi-browser:
- virtual void item_select(void *,int=1);
- virtual int item_selected(void *) const ;
+ virtual void item_select(void *item,int val=1);
+ virtual int item_selected(void *item) const ;
// things the subclass may want to call:
- /** Returns the item the appears at the top of the list. */
- void *top() const {return top_;}
/**
+ Returns the item that appears at the top of the list.
+ */
+ void *top() const { return top_; }
+ /**
Returns the item currently selected, or NULL if there is no selection.
- <P>For multiple selection browsers this call returns the currently focused
item,
+ For multiple selection browsers this call returns the currently focused
item,
even if it is not selected. To find all selected items, call
-
Fl_Multi_Browser::selected() for every item in question.
*/
- void *selection() const {return selection_;}
+ void *selection() const { return selection_; }
void new_list(); // completely clobber all data, as though list replaced
- void deleting(void *a); // get rid of any pointers to a
+ void deleting(void *item); // get rid of any pointers to item
void replacing(void *a,void *b); // change a pointers to b
void swapping(void *a,void *b); // exchange pointers a and b
void inserting(void *a,void *b); // insert b near a
- int displayed(void *) const ; // true if this line is visible
- void redraw_line(void *); // minimal update, no change in size
- /** This method will cause the entire list to be redrawn. */
- void redraw_lines() {damage(FL_DAMAGE_SCROLL);} // redraw all of them
- void bbox(int&,int&,int&,int&) const;
+ int displayed(void *item) const ; // true if this item is visible
+ 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()
+ */
+ void redraw_lines() { damage(FL_DAMAGE_SCROLL); } // redraw all of them
+ void bbox(int &X,int &Y,int &W,int &H) const;
int leftedge() const; // x position after scrollbar & border
- void *find_item(int my); // item under mouse
+ void *find_item(int ypos); // item under mouse
- /**
- Draws the contents of the browser within the specified bounding box.
- \todo Find the implementation, if any, and document it there!
- */
- void draw(int,int,int,int);
- /*
- Handles the specified event, plus 4 extra parameters!
- \todo Find the implementation, if any, and document it there!
- fabien: I guess the answer is there is no implementation (yet?),
- so let's comment out this method that does not exist.
- int handle(int,int,int,int,int);
- */
-
void draw();
- Fl_Browser_(int,int,int,int,const char * = 0);
+ Fl_Browser_(int X,int Y,int W,int H,const char *L=0);
public:
- /** Vertical scrollbar. */
+ /**
+ Vertical scrollbar. Public, so that it can be accessed directly.
+ */
Fl_Scrollbar scrollbar;
- /** Horizontal scrollbar */
+ /**
+ Horizontal scrollbar. Public, so that it can be accessed directly.
+ */
Fl_Scrollbar hscrollbar;
- int handle(int);
- void resize(int,int,int,int);
+ int handle(int event);
+ void resize(int X,int Y,int W,int H);
- int select(void *,int=1,int docallbacks=0);
- int select_only(void *,int docallbacks=0);
+ int select(void *item,int val=1,int docallbacks=0);
+ int select_only(void *item,int docallbacks=0);
int deselect(int docallbacks=0);
/**
- Gets or sets the vertical scrolling position of the list,
- which is the pixel offset of the list items within the list
- area.
+ Gets the vertical scroll position of the list as a pixel position \p pos.
+ 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()
*/
- int position() const {return position_;}
+ int position() const { return position_; }
+ void position(int pos); // scroll to here
/**
- Gets or sets the horizontal scrolling position of the list,
- which is the pixel offset of the list items within the list
- area.
+ Gets the horizontal scroll position of the list as a pixel position \p pos.
+ 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()
*/
- int hposition() const {return hposition_;}
- void position(int); // scroll to here
+ int hposition() const { return hposition_; }
void hposition(int); // pan to here
- void display(void*); // scroll so this item is shown
- /** See Fl_Browser_::has_scrollbar(uchar) */
- uchar has_scrollbar() const {return has_scrollbar_;}
+ void display(void *item); // scroll so this item is shown
+
/**
+ Values for has_scrollbar().
+ */
+ enum { // values for has_scrollbar()
+ HORIZONTAL = 1, ///< Only show horizontal scrollbar
+ VERTICAL = 2, ///< Only show vertical scrollbar
+ BOTH = 3, ///< Show both scrollbars (default)
+ ALWAYS_ON = 4, ///< Both scrollbars always on
+ HORIZONTAL_ALWAYS = 5, ///< horizontal scrollbar always on
+ VERTICAL_ALWAYS = 6, ///< vertical scrollbar always on
+ BOTH_ALWAYS = 7 ///< both scrollbars always on
+ };
+ /**
+ Returns the current scrollbar mode, see Fl_Browser_::has_scrollbar(uchar)
+ */
+ uchar has_scrollbar() const { return has_scrollbar_; }
+ /**
+ Sets whether the widget should have scrollbars or not (default
Fl_Browser_::BOTH).
By default you can scroll in both directions, and the scrollbars
- disappear if the data will fit in the widget. has_scrollbar() changes
- this based on the value of h:
+ disappear if the data will fit in the widget.
+ has_scrollbar() changes this based on the value of \p mode:
- \li 0 - No scrollbars.
-
- \li Fl_Browser_::HORIZONTAL - Only a horizontal scrollbar.
-
- \li Fl_Browser_::VERTICAL - Only a vertical scrollbar.
-
- \li Fl_Browser_::BOTH - The default is both scrollbars.
-
- \li Fl_Browser_::HORIZONTAL_ALWAYS - Horizontal scrollbar always on,
- vertical always off.
-
- \li Fl_Browser_::VERTICAL_ALWAYS - Vertical scrollbar always on,
- horizontal always off.
-
- \li Fl_Browser_::BOTH_ALWAYS - Both always on.
+ - 0 - No scrollbars.
+
+ - Fl_Browser_::HORIZONTAL - Only a horizontal scrollbar.
+
+ - Fl_Browser_::VERTICAL - Only a vertical scrollbar.
+
+ - Fl_Browser_::BOTH - The default is both scrollbars.
+
+ - Fl_Browser_::HORIZONTAL_ALWAYS - Horizontal scrollbar always on,
+ vertical always off.
+
+ - Fl_Browser_::VERTICAL_ALWAYS - Vertical scrollbar always on,
+ horizontal always off.
+
+ - Fl_Browser_::BOTH_ALWAYS - Both always on.
*/
- void has_scrollbar(uchar i) {has_scrollbar_ = i;}
- enum { // values for has_scrollbar()
- HORIZONTAL = 1,
- VERTICAL = 2,
- BOTH = 3,
- ALWAYS_ON = 4,
- HORIZONTAL_ALWAYS = 5,
- VERTICAL_ALWAYS = 6,
- BOTH_ALWAYS = 7
- };
+ void has_scrollbar(uchar mode) { has_scrollbar_ = mode; }
/**
Gets the default text font for the lines in the browser.
+ \see Related methods: textfont(), textsize(), textcolor()
*/
- Fl_Font textfont() const {return textfont_;}
+ Fl_Font textfont() const { return textfont_; }
/**
- Sets the default text font to font \p s
+ Sets the default text font for the lines in the browser to \p font.
*/
- void textfont(Fl_Font s) {textfont_ = s;}
+ void textfont(Fl_Font font) { textfont_ = font; }
/**
- Gets the default text size for the lines in the browser.
+ Gets the default text size (in pixels) for the lines in the browser.
*/
- Fl_Fontsize textsize() const {return textsize_;}
+ Fl_Fontsize textsize() const { return textsize_; }
/**
- Sets the default text size to size \p s.
+ Sets the default text size (in pixels) for the lines in the browser to \p
size.
*/
- void textsize(Fl_Fontsize s) {textsize_ = s;}
+ void textsize(Fl_Fontsize size) { textsize_ = size; }
/**
Gets the default text color for the lines in the browser.
*/
- Fl_Color textcolor() const {return (Fl_Color)textcolor_;}
+ Fl_Color textcolor() const { return (Fl_Color)textcolor_; }
/**
- Sets the default text color to color \p n.
+ Sets the default text color for the lines in the browser to color \p col.
*/
- void textcolor(unsigned n) {textcolor_ = n;}
+ void textcolor(unsigned col) { textcolor_ = col; }
/**
- Gets the width of any scrollbars that are used.
+ Gets the current width of scrollbars in pixels.
*/
- static int scrollbar_width() {return scrollbar_width_;}
+ static int scrollbar_width() { return scrollbar_width_; }
/**
- Sets the width of any scrollbars that are used to \p b.
+ Sets the width of scrollbars to pixel size \p width.
*/
- static void scrollbar_width(int b) {scrollbar_width_ = b;}
+ static void scrollbar_width(int width) { scrollbar_width_ = width; }
/**
Moves the vertical scrollbar to the righthand side of the list.
For back compatibility.
*/
- void scrollbar_right() {scrollbar.align(FL_ALIGN_RIGHT);}
+ void scrollbar_right() { scrollbar.align(FL_ALIGN_RIGHT); }
/**
Moves the vertical scrollbar to the lefthand side of the list.
For back compatibility.
*/
- void scrollbar_left() {scrollbar.align(FL_ALIGN_LEFT);}
-
- /**
- Sort the items in the browser.
- item_swap(void*, void*) and item_text(void*) must be implemented for this
call.
- \param[in] flags no flags were defined yet. Sorting in descending order and
- sorting while ignoring case come to mind.
- */
+ void scrollbar_left() { scrollbar.align(FL_ALIGN_LEFT); }
void sort(int flags=0);
-
};
#endif
Modified: branches/branch-1.3/src/Fl_Browser.cxx
===================================================================
--- branches/branch-1.3/src/Fl_Browser.cxx 2009-03-25 16:38:28 UTC (rev
6719)
+++ branches/branch-1.3/src/Fl_Browser.cxx 2009-03-25 23:09:04 UTC (rev
6720)
@@ -460,7 +460,7 @@
}
/**
- The default height of items (including spacing in-between) in pixels.
+ The default 'average' item height (including inter-item spacing) in pixels.
This currently returns textsize() + 2.
\returns The value in pixels.
*/
@@ -629,10 +629,10 @@
/**
Adds a new line to the end of the browser.
- The text string newtext may contain format characters; see format_char() for
details.
+ The text string \p newtext may contain format characters; see format_char()
for details.
\p newtext is copied using the strdup() function, and can be NULL to make a
blank line.
- The optional void * argument \p d will be the data() for the new item.
+ The optional void* argument \p d will be the data() for the new item.
\param[in] newtext The label text used for the added item
\param[in] d Optional user data() for the item (0 if unspecified)
@@ -753,7 +753,7 @@
/**
Swap the two items \p a and \p b.
- You must call redraw() to make any changes visible.
+ Uses swapping() to ensure list updates correctly.
\param[in] a,b The two items to be swapped.
*/
void Fl_Browser::swap(FL_BLINE *a, FL_BLINE *b) {
Modified: branches/branch-1.3/src/Fl_Browser_.cxx
===================================================================
--- branches/branch-1.3/src/Fl_Browser_.cxx 2009-03-25 16:38:28 UTC (rev
6719)
+++ branches/branch-1.3/src/Fl_Browser_.cxx 2009-03-25 23:09:04 UTC (rev
6720)
@@ -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 @@
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 @@
// 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 @@
/**
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 @@
// 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 @@
// 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 @@
// 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 @@
// 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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
}
// redraw, has side effect of updating top and setting scrollbar:
-
/**
Draws the list within the normal widget bounding box.
*/
@@ -490,6 +515,8 @@
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 @@
// 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 @@
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 @@
}
/**
- 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 @@
}
/**
- 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 @@
}
/**
- 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 @@
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 @@
}
/**
- 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 @@
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 @@
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 @@
/**
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 @@
/**
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 @@
/**
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$".
Modified: branches/branch-1.3/test/browser.cxx
===================================================================
--- branches/branch-1.3/test/browser.cxx 2009-03-25 16:38:28 UTC (rev
6719)
+++ branches/branch-1.3/test/browser.cxx 2009-03-25 23:09:04 UTC (rev
6720)
@@ -119,7 +119,7 @@
}
void sort_cb(Fl_Widget *, void *) {
- browser->sort(FL_SORT_ASC);
+ browser->sort(FL_SORT_ASCENDING);
}
int main(int argc, char **argv) {
_______________________________________________
fltk-commit mailing list
[email protected]
http://lists.easysw.com/mailman/listinfo/fltk-commit
