From f414a50dd2156541d9b53ada0ad988328b8b6e80 Mon Sep 17 00:00:00 2001 From: Greg Ercolano Date: Wed, 25 Mar 2009 23:09:04 +0000 Subject: [PATCH] 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 --- FL/Fl_Browser.H | 53 ++++--- FL/Fl_Browser_.H | 283 +++++++++++++++++++----------------- src/Fl_Browser.cxx | 8 +- src/Fl_Browser_.cxx | 340 +++++++++++++++++++++++++++----------------- test/browser.cxx | 2 +- 5 files changed, 403 insertions(+), 283 deletions(-) diff --git a/FL/Fl_Browser.H b/FL/Fl_Browser.H index fd0446fca..4bd8cf617 100644 --- a/FL/Fl_Browser.H +++ b/FL/Fl_Browser.H @@ -139,46 +139,61 @@ public: 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 @@ public: sprintf("\@C%d\@.%s", color, string) 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 @@ public: [..] \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 @@ public: } /** 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); }; diff --git a/FL/Fl_Browser_.H b/FL/Fl_Browser_.H index 22a9a03f6..0d150bdd9 100644 --- a/FL/Fl_Browser_.H +++ b/FL/Fl_Browser_.H @@ -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 @@ class FL_EXPORT Fl_Browser_ : public Fl_Group { 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. -

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 leftedge() const; // x position after scrollbar & border - void *find_item(int my); // item under mouse - + int displayed(void *item) const ; // true if this item is visible + void redraw_line(void *item); // minimal update, no change in size /** - 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); - */ - + 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 ypos); // item under mouse + 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 + /** - 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: - - \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. - */ - void has_scrollbar(uchar i) {has_scrollbar_ = i;} + Values for has_scrollbar(). + */ enum { // values for has_scrollbar() - HORIZONTAL = 1, - VERTICAL = 2, - BOTH = 3, - ALWAYS_ON = 4, - HORIZONTAL_ALWAYS = 5, - VERTICAL_ALWAYS = 6, - BOTH_ALWAYS = 7 + 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 \p mode: + + - 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 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 diff --git a/src/Fl_Browser.cxx b/src/Fl_Browser.cxx index add2e3171..d6934435b 100644 --- a/src/Fl_Browser.cxx +++ b/src/Fl_Browser.cxx @@ -460,7 +460,7 @@ int Fl_Browser::full_height() const { } /** - 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 @@ void Fl_Browser::clear() { /** 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 @@ int Fl_Browser::value() const { /** 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) { 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. -

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. -

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. - -

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$". diff --git a/test/browser.cxx b/test/browser.cxx index fe78dbc4b..77da66cde 100644 --- a/test/browser.cxx +++ b/test/browser.cxx @@ -119,7 +119,7 @@ void swap_cb(Fl_Widget *, void *) { } void sort_cb(Fl_Widget *, void *) { - browser->sort(FL_SORT_ASC); + browser->sort(FL_SORT_ASCENDING); } int main(int argc, char **argv) {