mirrors/fltk
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Doxgen mods for Fl_Browser*:

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



git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6726 ea41ed52-d2ee-0310-a9c1-e6b18d33e121
This commit is contained in:
Greg Ercolano 2009-03-27 16:52:31 +00:00
parent 4d82b14831
commit f91d962536
5 changed files with 86 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
FL/Fl_Browser.H
View File

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

38
FL/Fl_Browser_.H
View File

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

34
src/Fl_Browser.cxx
View File

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

8
src/Fl_Browser_.cxx
View File

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

6
src/Fl_Browser_load.cxx
View File

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