From f91d96253665065361519885ccfb72f31322e281 Mon Sep 17 00:00:00 2001 From: Greg Ercolano Date: Fri, 27 Mar 2009 16:52:31 +0000 Subject: [PATCH] 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 git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6726 ea41ed52-d2ee-0310-a9c1-e6b18d33e121 --- FL/Fl_Browser.H | 30 +++++++++++++++++++++++------- FL/Fl_Browser_.H | 38 ++++++++++++++++++++++---------------- src/Fl_Browser.cxx | 34 +++++++++++++++++++++++++++++++--- src/Fl_Browser_.cxx | 8 +++++--- src/Fl_Browser_load.cxx | 6 +++++- 5 files changed, 86 insertions(+), 30 deletions(-) diff --git a/FL/Fl_Browser.H b/FL/Fl_Browser.H index 4bd8cf617..8b144a039 100644 --- a/FL/Fl_Browser.H +++ b/FL/Fl_Browser.H @@ -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 - sprintf("\@C%d\@.%s", color, string) and it will work even if the + 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_; } /** 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)); diff --git a/FL/Fl_Browser_.H b/FL/Fl_Browser_.H index 0d150bdd9..ee977880b 100644 --- a/FL/Fl_Browser_.H +++ b/FL/Fl_Browser_.H @@ -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_; } /** diff --git a/src/Fl_Browser.cxx b/src/Fl_Browser.cxx index d6934435b..454db71e9 100644 --- a/src/Fl_Browser.cxx +++ b/src/Fl_Browser.cxx @@ -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; diff --git a/src/Fl_Browser_.cxx b/src/Fl_Browser_.cxx index 1a150335c..91c8b4e1c 100644 --- a/src/Fl_Browser_.cxx +++ b/src/Fl_Browser_.cxx @@ -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) { diff --git a/src/Fl_Browser_load.cxx b/src/Fl_Browser_load.cxx index bd9118d33..892f6ed00 100644 --- a/src/Fl_Browser_load.cxx +++ b/src/Fl_Browser_load.cxx @@ -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;