Each line in the browser is identified by number. The numbers + + Each line in the browser is identified by number. The numbers start at one (this is so that zero can be reserved for "no line" in the selective browsers). Unless otherwise noted, the methods do not check to see if the passed line number is in range and legal. It must - always be greater than zero and <= size().
-Each line contains a null-terminated string of text and a void * + always be greater than zero and <= size(). + + Each line contains a null-terminated string of text and a void * data pointer. The text string is displayed, the void * pointer can be used by the callbacks to reference the object the text - describes.
-The base does nothing when the user clicks on it. The + describes. + + The base class does nothing when the user clicks on it. The subclasses Fl_Select_Browser, Fl_Hold_Browser, and Fl_Multi_Browser react to user clicks to select lines in - the browser and do callbacks.
-The base called + the browser and do callbacks. + + The base class Fl_Browser_ provides the scrolling and selection mechanisms of this and all the subclasses, but the dimensions and appearance of each item are determined by the subclass. You can use Fl_Browser_ to display information other than text, or text that is dynamically produced from your own data structures. If you find that loading the browser is a lot of work or is inefficient, you may want to make a - subof Fl_Browser_. + subclass of Fl_Browser_. + + Some common coding patterns used for working with Fl_Browser: + \code + // How to loop through all the items in the browser + for ( int t=1; t<=browser->size(); t++ ) { // index 1 based..! + printf("item #%d, label='%s'\n", t, browser->text(t)); + } + \endcode + + Note: If you are subclassing Fl_Browser, it's more efficient + to use the protected methods item_first() and item_next(), since + Fl_Browser internally uses linked lists to manage the browser's items. + For more info, see find_item(int). */ class FL_EXPORT Fl_Browser : public Fl_Browser_ { @@ -84,39 +101,47 @@ protected: // required routines for Fl_Browser_ subclass: void* item_first() const ; - void* item_next(void*) const ; - void* item_prev(void*) const ; + void* item_next(void* item) const ; + void* item_prev(void* item) const ; void* item_last()const ; - int item_selected(void*) const ; - void item_select(void*, int); - int item_height(void*) const ; - int item_width(void*) const ; - void item_draw(void*, int, int, int, int) const ; + int item_selected(void* item) const ; + void item_select(void* item, int val); + int item_height(void* item) const ; + int item_width(void* item) const ; + void item_draw(void* item, int X, int Y, int W, int H) const ; int full_height() const ; int incr_height() const ; const char *item_text(void *item) const; + /** Swap the items \p a and \p b. + You must call redraw() to make any changes visible. + \param[in] a,b the items to be swapped. + */ void item_swap(void *a, void *b) { swap((FL_BLINE*)a, (FL_BLINE*)b); } - void *item_at(int ix) const { return (void*)find_line(ix); } + /** Return the item at specified \p line. + \param[in] line The line of the item to return. (1 based) + \returns The item, or NULL if line out of range. + */ + void *item_at(int line) const { return (void*)find_line(line); } - FL_BLINE* find_line(int) const ; - FL_BLINE* _remove(int) ; - void insert(int, FL_BLINE*); - int lineno(void*) const ; + FL_BLINE* find_line(int line) const ; + FL_BLINE* _remove(int line) ; + void insert(int line, FL_BLINE* item); + int lineno(void *item) const ; void swap(FL_BLINE *a, FL_BLINE *b); public: - void remove(int); - void add(const char*, void* = 0); - void insert(int, const char*, void* = 0); + void remove(int line); + void add(const char* newtext, void* d = 0); + void insert(int line, const char* newtext, void* d = 0); void move(int to, int from); int load(const char* filename); 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 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;} void size(int W, int H) { Fl_Widget::size(W, H); } @@ -124,32 +149,36 @@ public: int topline() const ; /** For internal use only? */ enum Fl_Line_Position { TOP, BOTTOM, MIDDLE }; - void lineposition(int, Fl_Line_Position); - /** Scrolls the browser so the top line in the browser is n. */ - void topline(int l) { lineposition(l, TOP); } - /** Scrolls the browser so the bottom line in the browser is n. */ - void bottomline(int l) { lineposition(l, BOTTOM); } - /** Scrolls the browser so the middle line in the browser is n. */ - void middleline(int l) { lineposition(l, 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. */ + void topline(int line) { lineposition(line, TOP); } + /** Scrolls the browser so the bottom item in the browser is showing the specified \p line. */ + void bottomline(int line) { lineposition(line, BOTTOM); } + /** Scrolls the browser so the middle item in the browser is showing the specified \p line. */ + void middleline(int line) { lineposition(line, MIDDLE); } - int select(int, int=1); - int selected(int) const ; - void show(int n); + 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 hide(int n); + void hide(int line); + /** Hides the entire Fl_Browser widget -- opposite of show(). */ void hide() {Fl_Widget::hide();} - int visible(int n) const ; + int visible(int line) const ; int value() const ; - /** Sets the browser's value, i.e. selected line, to \p v */ - void value(int v) {select(v);} - const char* text(int) const ; - void text(int, const char*); - void* data(int) const ; - void data(int, void* v); + /** 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);} + 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, int, int, int, const char* = 0); - /** The destructor deletes all list items and destroys the browser.*/ + Fl_Browser(int X, int Y, int W, int H, const char *L = 0); + /** The destructor deletes all list items and destroys the browser. */ ~Fl_Browser() { clear(); } /** @@ -190,50 +219,65 @@ public: void format_char(char c) {format_char_ = c;} /** Gets the current column separator character. - By default this is '\\t' (tab). + The default is '\\t' (tab). */ 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;} /** - Gets the current column width array. This array is - zero-terminated and specifies the widths in pixels of each column. The - text is split at each column_char() and each part is formatted - into it's own column. After the last column any remaining text is - formatted into the space between the last column and the right edge of - the browser, even if the text contains instances of column_char() . - The default value is a one-element array of just a zero, which means - there are no columns. + Gets the current column width array. + This array is zero-terminated and specifies the widths in pixels of + each column. The text is split at each column_char() and each part is + formatted into it's own column. After the last column any remaining + text is formatted into the space between the last column and the + right edge of the browser, even if the text contains instances of + column_char() . The default value is a one-element array of just + a zero, which means there are no columns. + + Example: + \code + Fl_Browser *b = new Fl_Browser(..); + int widths[] = { 50, 50, 50, 70, 70, 40, 40, 70, 70, 50, 0 }; // widths for each column + b->column_widths(widths); // assign array to widget + b->column_char('\t'); // use tab as the column character + b->add("USER\tPID\tCPU\tMEM\tVSZ\tRSS\tTTY\tSTAT\tSTART\tTIME\tCOMMAND"); + b->add("root\t2888\t0.0\t0.0\t1352\t0\ttty3\tSW\tAug15\t0:00\t@b@f/sbin/mingetty tty3"); + b->add("root\t13115\t0.0\t0.0\t1352\t0\ttty2\tSW\tAug30\t0:00\t@b@f/sbin/mingetty tty2"); + [..] + \endcode */ const int* column_widths() const {return column_widths_;} /** - Sets the current array to w. Make sure the last entry is zero. + 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* l) {column_widths_ = l;} + void column_widths(const int* arr) {column_widths_ = arr;} /** - Returns non-zero if line \p n is visible. + Returns non-zero if \p line is visible. */ - int displayed(int n) const {return Fl_Browser_::displayed(find_line(n));} + int displayed(int line) const {return Fl_Browser_::displayed(find_line(line));} /** - Redisplays so that line \p n is visible. - If \p n is out of range, redisplay top or botton of list as appropriate. + Make the item at the specified \p line visible(). + Functionally similar to show(int line). + If \p line is out of range, redisplay top or bottom of list as appropriate. + \param[in] line The line to be made visible. + \see show(int) */ - void make_visible(int n) { - if (n < 1) Fl_Browser_::display(find_line(1)); - else if (n > lines) Fl_Browser_::display(find_line(lines)); - else Fl_Browser_::display(find_line(n)); + void make_visible(int line) { + if (line < 1) Fl_Browser_::display(find_line(1)); + else if (line > lines) Fl_Browser_::display(find_line(lines)); + else Fl_Browser_::display(find_line(line)); } /** For back compatibility only. */ void replace(int a, const char* b) {text(a, b);} - - void display(int, int=1); + void display(int line, int val=1); }; #endif diff --git a/src/Fl_Browser.cxx b/src/Fl_Browser.cxx index 59bf61912..dbc4afd9b 100644 --- a/src/Fl_Browser.cxx +++ b/src/Fl_Browser.cxx @@ -53,28 +53,88 @@ struct FL_BLINE { // data is in a linked list of these char txt[1]; // start of allocated array }; +/** + Returns the very first item in the list. + Example of use: + \code + // Walk the browser from beginning to end + for ( void *i=item_first(); i; i=item_next(i) ) { + printf("item label='%s'\n", item_text(i)); + } + \endcode + \returns The first item, or NULL if list is empty. +*/ void* Fl_Browser::item_first() const {return first;} -void* Fl_Browser::item_next(void* l) const {return ((FL_BLINE*)l)->next;} +/** + Returns the next item after \p item. + \param[in] item The 'current' item + \returns The next item after \p item, or NULL if there are none after this one. + \see item_first() +*/ +void* Fl_Browser::item_next(void* item) const {return ((FL_BLINE*)item)->next;} -void* Fl_Browser::item_prev(void* l) const {return ((FL_BLINE*)l)->prev;} +/** + Returns the previous item before \p item. + \param[in] item The 'current' item + \returns The previous item before \p item, or NULL if there none before this one. + \see item_last() +*/ +void* Fl_Browser::item_prev(void* item) const {return ((FL_BLINE*)item)->prev;} +/** + Returns the very last item in the list. + Example of use: + \code + // Walk the browser in reverse, from end to start + for ( void *i=item_last(); i; i=item_prev(i) ) { + printf("item label='%s'\n", item_text(i)); + } + \endcode + \returns The last item, or NULL if list is empty. +*/ void* Fl_Browser::item_last() const {return last;} -int Fl_Browser::item_selected(void* l) const { - return ((FL_BLINE*)l)->flags&SELECTED;} - -void Fl_Browser::item_select(void* l, int v) { - if (v) ((FL_BLINE*)l)->flags |= SELECTED; - else ((FL_BLINE*)l)->flags &= ~SELECTED; +/** + See if \p item is selected. + \param[in] item The item whose selection state is to be checked. + \returns 1 if selected, 0 if not. +*/ +int Fl_Browser::item_selected(void* item) const { + return ((FL_BLINE*)item)->flags&SELECTED; +} +/** + Change the selection state of \p item to the value \p val. + \param[in] item The item to be changed. + \param[in] v The new selection state: 1 selects, 0 de-selects. +*/ +void Fl_Browser::item_select(void *item, int val) { + if (val) ((FL_BLINE*)item)->flags |= SELECTED; + else ((FL_BLINE*)item)->flags &= ~SELECTED; } +/** + Returns the label text for \p item. + \param[in] item The item whose label text is returned. + \returns The item's text string. (Can be NULL) +*/ const char *Fl_Browser::item_text(void *item) const { return ((FL_BLINE*)item)->txt; } /** - Return entry for line number \a line. + Returns the item for specified \p line. + + Note: This call is slow. It's fine for e.g. responding to user + clicks, but slow if called often, such as in a tight sorting loop. + Finding an item 'by line' involves a linear lookup on the internal + linked list. The performance hit can be significant if the browser's + contents is large, and the method is called often (e.g. during a sort). + If you're writing a subclass, use the protected methods item_first(), + item_next(), etc. to access the internal linked list more efficiently. + + \param[in] line The line number of the item to return. (1 based) + \returns The returned item. */ FL_BLINE* Fl_Browser::find_line(int line) const { int n; FL_BLINE* l; @@ -94,11 +154,13 @@ FL_BLINE* Fl_Browser::find_line(int line) const { } /** - Returns line number corresponding to data \a v, - zero if not found. + Returns line number corresponding to \p item, or zero if not found. + Caveat: See efficiency note in find_line(). + \param[in] item The item to be found + \returns The line number of the item, or 0 if not found. */ -int Fl_Browser::lineno(void* v) const { - FL_BLINE* l = (FL_BLINE*)v; +int Fl_Browser::lineno(void *item) const { + FL_BLINE* l = (FL_BLINE*)item; if (!l) return 0; if (l == cache) return cacheline; if (l == first) return 1; @@ -107,7 +169,7 @@ int Fl_Browser::lineno(void* v) const { ((Fl_Browser*)this)->cache = first; ((Fl_Browser*)this)->cacheline = 1; } - // assumme it is near cache, search both directions: + // assume it is near cache, search both directions: FL_BLINE* b = cache->prev; int bnum = cacheline-1; FL_BLINE* f = cache->next; @@ -125,9 +187,11 @@ int Fl_Browser::lineno(void* v) const { } /** - Remove entry for given line number. - \param[in] line line number. Must be in range! - \returns pointer to browser entry. + Removes the item at the specified \p line. + Caveat: See efficiency note in find_line(). + You must call redraw() to make any changes visible. + \param[in] line The line number to be removed. (1 based) Must be in range! + \returns Pointer to browser item that was removed (and is no longer valid). */ FL_BLINE* Fl_Browser::_remove(int line) { FL_BLINE* ttt = find_line(line); @@ -146,7 +210,10 @@ FL_BLINE* Fl_Browser::_remove(int line) { } /** - Remove line \a line and make the browser one line shorter. + Remove entry for given \p line number, making the browser one line shorter. + You must call redraw() to make any changes visible. + \param[in] line Line to be removed. (1 based) \n + If \p line is out of range, no action is taken. */ void Fl_Browser::remove(int line) { if (line < 1 || line > lines) return; @@ -154,44 +221,56 @@ void Fl_Browser::remove(int line) { } /** - Insert a new line \a t \e before line \a n. - If \a n > size() then the line is added to the end. + Insert specified \p item above \p line. + If \p line > size() then the line is added to the end. + + Caveat: See efficiency note in find_line(). + + \param[in] line The new line will be inserted above this line (1 based). + \param[in] item The the item to be added. */ -void Fl_Browser::insert(int line, FL_BLINE* t) { +void Fl_Browser::insert(int line, FL_BLINE* item) { if (!first) { - t->prev = t->next = 0; - first = last = t; + item->prev = item->next = 0; + first = last = item; } else if (line <= 1) { - inserting(first, t); - t->prev = 0; - t->next = first; - t->next->prev = t; - first = t; + inserting(first, item); + item->prev = 0; + item->next = first; + item->next->prev = item; + first = item; } else if (line > lines) { - t->prev = last; - t->prev->next = t; - t->next = 0; - last = t; + item->prev = last; + item->prev->next = item; + item->next = 0; + last = item; } else { FL_BLINE* n = find_line(line); - inserting(n, t); - t->next = n; - t->prev = n->prev; - t->prev->next = t; - n->prev = t; + inserting(n, item); + item->next = n; + item->prev = n->prev; + item->prev->next = item; + n->prev = item; } cacheline = line; - cache = t; + cache = item; lines++; - full_height_ += item_height(t); - redraw_line(t); + full_height_ += item_height(item); + redraw_line(item); } /** - Insert a new entry \e before given line. - \param[in] line if \a line > size(), the entry will be added at the end. - \param[in] newtext text entry for the new line. - \param[in] d pointer to data associated with the new line. + Insert a new entry whose label is \p newtext \e above given \p line, optional data \p d. + + Text 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() of the new item. + + \param[in] line Line position for insert. (1 based) \n + If \p line > size(), the entry will be added at the end. + \param[in] newtext The label text for the new line. + \param[in] d Optional pointer to user data to be associated with the new line. */ void Fl_Browser::insert(int line, const char* newtext, void* d) { int l = strlen(newtext); @@ -204,8 +283,10 @@ void Fl_Browser::insert(int line, const char* newtext, void* d) { } /** - Line \a from is removed and reinserted at \a to; \a to - is calculated after the line is removed. + Line \p from is removed and reinserted at \p to. + Note: \p to is calculated \e after line \p from gets removed. + \param[in] to Destination line number (calculated \e after line \p from is removed) + \param[in] from Line number of item to be moved */ void Fl_Browser::move(int to, int from) { if (from < 1 || from > lines) return; @@ -213,8 +294,15 @@ void Fl_Browser::move(int to, int from) { } /** - Sets the text for line \a line to text \a newtext. - Does nothing if \a line is out of range. + Sets the text for the specified \p line to \p newtext. + + Text 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. + + Does nothing if \p line is out of range. + + \param[in] line The line of the item whose text will be changed. (1 based) + \param[in] newtext The new string to be assigned to the item. */ void Fl_Browser::text(int line, const char* newtext) { if (line < 1 || line > lines) return; @@ -239,8 +327,10 @@ void Fl_Browser::text(int line, const char* newtext) { } /** - Sets the data for line \a line to \a d. - Does nothing if \a line is out of range. + Sets the user data for specified \p line to \p d. + Does nothing if \p line is out of range. + \param[in] line The line of the item whose data() is to be changed. (1 based) + \param[in] d The new data to be assigned to the item. (can be NULL) */ void Fl_Browser::data(int line, void* d) { if (line < 1 || line > lines) return; @@ -248,10 +338,13 @@ void Fl_Browser::data(int line, void* d) { } /** - Returns height of line \p lv. + Returns height of \p item in pixels. + This takes into account embedded \@ codes within the text() label. + \param[in] item The item whose height is returned. + \returns The height of the item in pixels. */ -int Fl_Browser::item_height(void* lv) const { - FL_BLINE* l = (FL_BLINE*)lv; +int Fl_Browser::item_height(void *item) const { + FL_BLINE* l = (FL_BLINE*)item; if (l->flags & NOTDISPLAYED) return 0; int hmax = 2; // use 2 to insure we don't return a zero! @@ -300,8 +393,14 @@ int Fl_Browser::item_height(void* lv) const { return hmax; // previous version returned hmax+2! } -int Fl_Browser::item_width(void* v) const { - char* str = ((FL_BLINE*)v)->txt; +/** + Returns width of \p item in pixels. + This takes into account embedded \@ codes within the text() label. + \param[in] item The item whose width is returned. + \returns The width of the item in pixels. +*/ +int Fl_Browser::item_width(void *item) const { + char* str = ((FL_BLINE*)item)->txt; const int* i = column_widths(); int ww = 0; @@ -350,16 +449,34 @@ int Fl_Browser::item_width(void* v) const { return ww + int(fl_width(str)) + 6; } +/** + The height of the entire list of all visible() items in pixels. + This returns the accumulated height of *all* the items in the browser + that are not hidden with hide(), including items scrolled offscreen. + \returns The accumulated size of all the visible items in pixels. +*/ int Fl_Browser::full_height() const { return full_height_; } +/** + The default height of items (including spacing in-between) in pixels. + This currently returns textsize() + 2. + \returns The value in pixels. +*/ int Fl_Browser::incr_height() const { return textsize()+2; } -void Fl_Browser::item_draw(void* v, int X, int Y, int W, int H) const { - char* str = ((FL_BLINE*)v)->txt; +/** + Draws \p item at the position specified by \p X \p Y \p W \p H. + The \p W and \p H values are used for clipping. + Should only be called within the context of an FLTK draw(). + \param[in] item The item to be drawn + \param[in] X,Y,W,H position and size. +*/ +void Fl_Browser::item_draw(void* item, int X, int Y, int W, int H) const { + char* str = ((FL_BLINE*)item)->txt; const int* i = column_widths(); while (W > 6) { // do each tab-separated field @@ -388,7 +505,7 @@ void Fl_Browser::item_draw(void* v, int X, int Y, int W, int H) const { case 'c': talign = FL_ALIGN_CENTER; break; case 'r': talign = FL_ALIGN_RIGHT; break; case 'B': - if (!(((FL_BLINE*)v)->flags & SELECTED)) { + if (!(((FL_BLINE*)item)->flags & SELECTED)) { fl_color((Fl_Color)strtol(str, &str, 10)); fl_rectf(X, Y, w1, H); } else strtol(str, &str, 10); @@ -424,7 +541,7 @@ void Fl_Browser::item_draw(void* v, int X, int Y, int W, int H) const { } BREAK: fl_font(font, tsize); - if (((FL_BLINE*)v)->flags & SELECTED) + if (((FL_BLINE*)item)->flags & SELECTED) lcol = fl_contrast(lcol, selection_color()); if (!active_r()) lcol = fl_inactive(lcol); fl_color(lcol); @@ -456,8 +573,8 @@ Fl_Browser::Fl_Browser(int X, int Y, int W, int H, const char *L) } /** - Updates the browser so that \a line is shown at position \a pos. - \param[in] line line number. + Updates the browser so that \p line is shown at position \p pos. + \param[in] line line number. (1 based) \param[in] pos position. */ void Fl_Browser::lineposition(int line, Fl_Line_Position pos) { @@ -485,8 +602,9 @@ void Fl_Browser::lineposition(int line, Fl_Line_Position pos) { } /** - Returns the current top line in the browser. If there - is no vertical scrollbar then this will always return 1. + Returns the line that is currently visible at the top of the browser. + If there is no vertical scrollbar then this will always return 1. + \returns The lineno() of the top() of the browser. */ int Fl_Browser::topline() const { return lineno(top()); @@ -509,10 +627,15 @@ void Fl_Browser::clear() { } /** - Adds a new line to the end of the browser. The text is copied using - the strdup() function. It may also be NULL to make a - blank line. The void * argument \a d is returned as the data() - of the new item. + Adds a new line to the end of the browser. + + The text string 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. + + \param[in] newtext The label text used for the added item + \param[in] d Optional user data() for the item (0 if unspecified) */ void Fl_Browser::add(const char* newtext, void* d) { insert(lines+1, newtext, d); @@ -520,7 +643,11 @@ void Fl_Browser::add(const char* newtext, void* d) { } /** - Returns data entry for line \p line, or NULL if out of range. + Returns the label text for the specified \p line. + Return value can be NULL if \p line is out of range or unset. + The parameter \p line is 1 based. + \param[in] line The line number of the item whose text is returned. (1 based) + \returns The text string (can be NULL) */ const char* Fl_Browser::text(int line) const { if (line < 1 || line > lines) return 0; @@ -528,7 +655,12 @@ const char* Fl_Browser::text(int line) const { } /** - Returns the data for line \p line, or NULL if \p line is out of range. + Returns the user data() for specified \p line. + Return value can be NULL if \p line is out of range or no user data() was defined. + The parameter \p line is 1 based (1 will be the first item in the list). + \param[in] line The line number of the item whose data() is returned. (1 based) + \returns The user data pointer (can be NULL) + */ void* Fl_Browser::data(int line) const { if (line < 1 || line > lines) return 0; @@ -536,23 +668,34 @@ void* Fl_Browser::data(int line) const { } /** - Sets the selection state of entry \a line. - \param[in] line line number. - \param[in] v new selection state. + Sets the selection state of the item at \p line to the value \p val. + If \p val is not specified, the default is 1 (selects the item). + \param[in] line The line number of the item to be changed. (1 based) + \param[in] val The new selection state (1=select, 0=de-select). \returns 1 if the state changed, 0 if not. */ -int Fl_Browser::select(int line, int v) { +int Fl_Browser::select(int line, int val) { if (line < 1 || line > lines) return 0; - return Fl_Browser_::select(find_line(line), v); + return Fl_Browser_::select(find_line(line), val); } -/** Returns 1 if line \a line is selected, 0 if it is not selected.*/ +/** + Returns 1 if specified \p line is selected, 0 if not. + \param[in] line The line being checked (1 based) + \returns 1 if item selected, 0 if not. + */ int Fl_Browser::selected(int line) const { if (line < 1 || line > lines) return 0; return find_line(line)->flags & SELECTED; } -/** Makes line \a line visible for selection. */ +/** + Makes \p line visible, and available for selection by user. + Opposite of hide(int). + This changes the full_height() if the state was changed. + redraw() is called automatically if a change occurred. + \param[in] line The line to be shown. (1 based) +*/ void Fl_Browser::show(int line) { FL_BLINE* t = find_line(line); if (t->flags & NOTDISPLAYED) { @@ -563,8 +706,12 @@ void Fl_Browser::show(int line) { } /** - Makes line \a line invisible, preventing selection by the user. + Makes \p line invisible, preventing selection by the user. The line can still be selected under program control. + This changes the full_height() if the state was changed. + When a line is made invisible, lines below it are moved up in the display. + redraw() is called automatically if a change occurred. + \param[in] line The line to be hidden. (1 based) */ void Fl_Browser::hide(int line) { FL_BLINE* t = find_line(line); @@ -577,17 +724,19 @@ void Fl_Browser::hide(int line) { /** For back compatibility. - - This calls show(line) if \a v is true, and hide(line) otherwise. + This calls show(line) if \p val is true, and hide(line) otherwise. + If \p val is not specified, the default is 1 (makes the line visible). \see show(int line), hide(int line) */ -void Fl_Browser::display(int line, int v) { +void Fl_Browser::display(int line, int val) { if (line < 1 || line > lines) return; - if (v) show(line); else hide(line); + if (val) show(line); else hide(line); } /** - Returns a non-zero value if line \a line is visible. + Returns non-zero if the specified \p line is visible, 0 if hidden. + Use show(int), hide(int), or make_visible(int) to change an item's visible state. + \param[in] line The line in the browser to be tested. (1 based) */ int Fl_Browser::visible(int line) const { if (line < 1 || line > lines) return 0; @@ -595,15 +744,17 @@ int Fl_Browser::visible(int line) const { } /** - Gets the browser's value. - \returns line number of current selection, or 0 if no selection. + Returns the line number of the currently selected line, or 0 if none. + \returns The line number of current selection, or 0 if none selected. */ int Fl_Browser::value() const { return lineno(selection()); } /** - Swap two lines, \p a and \p b + Swap the two items \p a and \p b. + You must call redraw() to make any changes visible. + \param[in] a,b The two items to be swapped. */ void Fl_Browser::swap(FL_BLINE *a, FL_BLINE *b) { @@ -644,12 +795,16 @@ void Fl_Browser::swap(FL_BLINE *a, FL_BLINE *b) { cache = 0; } -/** Swaps two lines in the browser.*/ -void Fl_Browser::swap(int ai, int bi) { - if (ai < 1 || ai > lines || bi < 1 || bi > lines) return; - FL_BLINE* a = find_line(ai); - FL_BLINE* b = find_line(bi); - swap(a,b); +/** + Swaps two browser lines \p a and \p b. + You must call redraw() to make any changes visible. + \param[in] a,b The two lines to be swapped. (both 1 based) +*/ +void Fl_Browser::swap(int a, int b) { + if (a < 1 || a > lines || b < 1 || b > lines) return; + FL_BLINE* ai = find_line(a); + FL_BLINE* bi = find_line(b); + swap(ai,bi); } //