Author: greg.ercolano
Date: 2009-03-27 09:52:31 -0700 (Fri, 27 Mar 2009)
New Revision: 6726
Log:
Doxgen mods for Fl_Browser*:
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
Modified:
branches/branch-1.3/FL/Fl_Browser.H
branches/branch-1.3/FL/Fl_Browser_.H
branches/branch-1.3/src/Fl_Browser.cxx
branches/branch-1.3/src/Fl_Browser_.cxx
branches/branch-1.3/src/Fl_Browser_load.cxx
Modified: branches/branch-1.3/FL/Fl_Browser.H
===================================================================
--- branches/branch-1.3/FL/Fl_Browser.H 2009-03-27 00:02:20 UTC (rev 6725)
+++ branches/branch-1.3/FL/Fl_Browser.H 2009-03-27 16:52:31 UTC (rev 6726)
@@ -115,11 +115,13 @@
/** 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 @@
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 @@
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 @@
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...@.%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 @@
b->add("root\t13115\t0.0\t0.0\t1352\t0\ttty2\tSW\tAug30\t0:0...@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 @@
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));
Modified: branches/branch-1.3/FL/Fl_Browser_.H
===================================================================
--- branches/branch-1.3/FL/Fl_Browser_.H 2009-03-27 00:02:20 UTC (rev
6725)
+++ branches/branch-1.3/FL/Fl_Browser_.H 2009-03-27 16:52:31 UTC (rev
6726)
@@ -89,25 +89,25 @@
/**
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 @@
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 @@
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 @@
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 @@
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 @@
/**
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 @@
/**
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_; }
/**
Modified: branches/branch-1.3/src/Fl_Browser.cxx
===================================================================
--- branches/branch-1.3/src/Fl_Browser.cxx 2009-03-27 00:02:20 UTC (rev
6725)
+++ branches/branch-1.3/src/Fl_Browser.cxx 2009-03-27 16:52:31 UTC (rev
6726)
@@ -63,6 +63,7 @@
}
\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 @@
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 @@
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 @@
}
\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 @@
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 @@
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 @@
\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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
/**
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 @@
\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 @@
\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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
/**
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 @@
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 @@
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;
Modified: branches/branch-1.3/src/Fl_Browser_.cxx
===================================================================
--- branches/branch-1.3/src/Fl_Browser_.cxx 2009-03-27 00:02:20 UTC (rev
6725)
+++ branches/branch-1.3/src/Fl_Browser_.cxx 2009-03-27 16:52:31 UTC (rev
6726)
@@ -157,7 +157,7 @@
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 @@
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 @@
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 @@
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 @@
/**
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) {
Modified: branches/branch-1.3/src/Fl_Browser_load.cxx
===================================================================
--- branches/branch-1.3/src/Fl_Browser_load.cxx 2009-03-27 00:02:20 UTC (rev
6725)
+++ branches/branch-1.3/src/Fl_Browser_load.cxx 2009-03-27 16:52:31 UTC (rev
6726)
@@ -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 @@
newtext[i] = 0;
add(newtext);
i = 0;
- } else
+ } else {
newtext[i++] = c;
+ }
} while (c >= 0);
fclose(fl);
return 1;
_______________________________________________
fltk-commit mailing list
[email protected]
http://lists.easysw.com/mailman/listinfo/fltk-commit
