From 58548b781d7c3f0fa6c8c72c63dece888a02ea43 Mon Sep 17 00:00:00 2001 From: Fabien Costantini Date: Sun, 14 Sep 2008 12:45:42 +0000 Subject: Doxygen Documentation WP2 done. git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6235 ea41ed52-d2ee-0310-a9c1-e6b18d33e121 --- FL/Fl_Browser.H | 99 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 99 insertions(+) (limited to 'FL/Fl_Browser.H') diff --git a/FL/Fl_Browser.H b/FL/Fl_Browser.H index 6b05f824c..447150a4a 100644 --- a/FL/Fl_Browser.H +++ b/FL/Fl_Browser.H @@ -36,6 +36,35 @@ struct FL_BLINE; +/** + The Fl_Browser widget displays a scrolling list of text + lines, and manages all the storage for the text. This is not a text + editor or spreadsheet! But it is useful for showing a vertical list of + named objects to the user. +

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 * + 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 + 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 + 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_. +*/ class FL_EXPORT Fl_Browser : public Fl_Browser_ { FL_BLINE *first; // the array of lines @@ -78,14 +107,25 @@ 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. + */ int size() const {return lines;} void size(int W, int H) { Fl_Widget::size(W, H); } int topline() const ; enum Fl_Line_Position { TOP, BOTTOM, MIDDLE }; void lineposition(int, Fl_Line_Position); + /** + The first form returns the current top line in the browser. If there + is no vertical scrollbar then this will always return 1. +

The second form 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); } int select(int, int=1); @@ -104,13 +144,72 @@ public: void data(int, void* v); Fl_Browser(int, int, int, int, const char* = 0); + /** The destructor deletes all list items and destroys the browser.*/ ~Fl_Browser() { clear(); } + /** + The first form gets the current format code prefix character, which by + default is @. A string of formatting codes at the start of + each column are stripped off and used to modify how the rest of the + line is printed: +

+ 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 + string starts with a digit or has the format character in it. +

The second form sets the current prefix to c. Set the + prefix to 0 to disable formatting. + */ char format_char() const {return format_char_;} + /** See uchar Fl_Browser::format_char() const */ void format_char(char c) {format_char_ = c;} + /** + The first form gets the current column separator character. By default + this is '\t' (tab). +

The second form sets the column separator to c. This will + only have an effect if you also set column_widths(). + */ char column_char() const {return column_char_;} + /** + The first form gets the current column separator character. By default + this is '\t' (tab). +

The second form sets the column separator to c. This will + only have an effect if you also set column_widths(). + */ void column_char(char c) {column_char_ = c;} + /** + The first form 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 makes + there are no columns. +

The second form sets the current array to w. Make sure the + last entry is zero. + */ const int* column_widths() const {return column_widths_;} + /** See const int *Fl_Browser::column_widths() const */ void column_widths(const int* l) {column_widths_ = l;} int displayed(int n) const {return Fl_Browser_::displayed(find_line(n));} -- cgit v1.2.3