diff options
Diffstat (limited to 'FL')
| -rw-r--r-- | FL/Fl_Browser.H | 99 | ||||
| -rw-r--r-- | FL/Fl_Browser_.H | 123 | ||||
| -rw-r--r-- | FL/Fl_Check_Browser.H | 13 | ||||
| -rw-r--r-- | FL/Fl_File_Browser.H | 36 | ||||
| -rw-r--r-- | FL/Fl_Hold_Browser.H | 17 | ||||
| -rw-r--r-- | FL/Fl_Multi_Browser.H | 16 | ||||
| -rw-r--r-- | FL/Fl_Select_Browser.H | 16 | ||||
| -rw-r--r-- | FL/Fl_Widget.H | 3 |
8 files changed, 316 insertions, 7 deletions
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. + <P>Each line in the browser is identified by number. <I>The numbers + start at one</I> (this is so that zero can be reserved for "no line" in + the selective browsers). <I>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().</I></P> + <P>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. </P> + <P>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. </P> + <P>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. + <P>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: + <UL> + <LI>@. Print rest of line, don't look for more '@' signs </LI> + <LI>@@ Print rest of line starting with '@' </LI> + <LI>@l Use a <BIG>large</BIG> (24 point) font </LI> + <LI>@m Use a <BIG>medium large</BIG> (18 point) font </LI> + <LI>@s Use a <SMALL>small</SMALL> (11 point) font </LI> + <LI>@b Use a <B>bold</B> font (adds FL_BOLD to font) </LI> + <LI>@i Use an <I>italic</I> font (adds FL_ITALIC to font) </LI> + <LI>@f or @t Use a fixed-pitch + font (sets font to FL_COURIER) </LI> + <LI>@c Center the line horizontally </LI> + <LI>@r Right-justify the text </LI> + <LI>@B0, @B1, ... @B255 Fill the backgound with + fl_color(n) </LI> + <LI>@C0, @C1, ... @C255 Use fl_color(n) to draw the text </LI> + <LI>@F0, @F1, ... Use fl_font(n) to draw the text </LI> + <LI>@S1, @S2, ... Use point size n to draw the text </LI> + <LI>@u or @_ Underline the text. </LI> + <LI>@- draw an engraved line through the middle. </LI> + </UL> + 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. + <P>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). + <P>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). + <P>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. + <P>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));} diff --git a/FL/Fl_Browser_.H b/FL/Fl_Browser_.H index 7db4be5c3..f8ee3ca1c 100644 --- a/FL/Fl_Browser_.H +++ b/FL/Fl_Browser_.H @@ -45,6 +45,21 @@ #define FL_HOLD_BROWSER 2 #define FL_MULTI_BROWSER 3 +/** + This is the base for browsers. To be useful it must be + subclassed and several virtual functions defined. The Forms-compatible + browser and the file chooser's browser are subclassed off of this. + <P>This has been designed so that the subhas complete control + over the storage of the data, although because next() and + prev() functions are used to index, it works best as a linked list + or as a large block of characters in which the line breaks must be + searched for. </P> + <P>A great deal of work has been done so that the "height" of a data + object does not need to be determined until it is drawn. This is + useful if actually figuring out the size of an object requires + accessing image data or doing stat() on a file or doing some + other slow operation. +*/ class FL_EXPORT Fl_Browser_ : public Fl_Group { int position_; // where user wants it scrolled to int real_position_; // the current vertical scrolling position @@ -68,12 +83,30 @@ class FL_EXPORT Fl_Browser_ : public Fl_Group { protected: // All of the following must be supplied by the subclass: - virtual void *item_first() const = 0; - virtual void *item_next(void *) const = 0; - virtual void *item_prev(void *) const = 0; + /** This method must be provided by the subclass to return the first item in the list. */ + virtual void *item_first() const = 0; + /** This method must be provided by the subclass to return the item in the list after p. */ + virtual void *item_next(void *) const = 0; + /** This method must be provided by the subclass to return the item in the list before p. */ + virtual void *item_prev(void *) const = 0; + /** + This method must be provided by the subclass to return the height of the + item p in pixels. Allow for two additional pixels for the list + selection box. + */ virtual int item_height(void *) const = 0; + /** + This method must be provided by the subclass to return the width of the + item p in pixels. Allow for two additional pixels for the list + selection box. + */ virtual int item_width(void *) const = 0; virtual int item_quick_height(void *) const ; + /** + This method must be provided by the subclass to draw the item + p in the area indicated by x, y, w, + and h. + */ virtual void item_draw(void *,int,int,int,int) const = 0; // you don't have to provide these but it may help speed it up: virtual int full_width() const ; // current width of all items @@ -84,7 +117,16 @@ protected: virtual int item_selected(void *) const ; // things the subclass may want to call: + /** Returns the item the appears at the top of the list. */ void *top() const {return top_;} + /** + Returns the item currently selected, or NULL if there is no selection. + + <P>For multiple selection browsers this call returns the currently focused item, + even if it is not selected. To find all selected items, call + + Fl_Multi_Browser::selected() for every item in question. + */ void *selection() const {return selection_;} void new_list(); // completely clobber all data, as though list replaced void deleting(void *a); // get rid of any pointers to a @@ -93,10 +135,17 @@ protected: void inserting(void *a,void *b); // insert b near a int displayed(void *) const ; // true if this line is visible void redraw_line(void *); // minimal update, no change in size + /** This method will cause the entire list to be redrawn. */ void redraw_lines() {damage(FL_DAMAGE_SCROLL);} // redraw all of them void bbox(int&,int&,int&,int&) const; int leftedge() const; // x position after scrollbar & border void *find_item(int my); // item under mouse + /** + The first form draws the list within the normal widget bounding box. + + <P>The second form draws the contents of the browser within the + specified bounding box. + */ void draw(int,int,int,int); int handle(int,int,int,int,int); @@ -114,13 +163,51 @@ public: int select(void *,int=1,int docallbacks=0); int select_only(void *,int docallbacks=0); int deselect(int docallbacks=0); + /** + Gets or sets the vertical scrolling position of the list, + which is the pixel offset of the list items within the list + area. + */ int position() const {return position_;} + /** + Gets or sets the horizontal scrolling position of the list, + which is the pixel offset of the list items within the list + area. + */ int hposition() const {return hposition_;} void position(int); // scroll to here void hposition(int); // pan to here void display(void*); // scroll so this item is shown - + /** See Fl_Browser_::has_scrollbar(uchar) */ uchar has_scrollbar() const {return has_scrollbar_;} + /** + By default you can scroll in both directions, and the scrollbars + disappear if the data will fit in the widget. has_scrollbar() changes + this based on the value of h: + + <UL> + + <LI>0 - No scrollbars. + + <LI>Fl_Browser_::HORIZONTAL - Only a horizontal + scrollbar. + + <LI>Fl_Browser_::VERTICAL - Only a vertical + scrollbar. + + <LI>Fl_Browser_::BOTH - The default is both + scrollbars. + + <LI>Fl_Browser_::HORIZONTAL_ALWAYS - Horizontal + scrollbar always on, vertical always off. + + <LI>Fl_Browser_::VERTICAL_ALWAYS - Vertical + scrollbar always on, horizontal always off. + + <LI>Fl_Browser_::BOTH_ALWAYS - Both always on. + + </UL> + */ void has_scrollbar(uchar i) {has_scrollbar_ = i;} enum { // values for has_scrollbar() HORIZONTAL = 1, @@ -132,18 +219,46 @@ public: BOTH_ALWAYS = 7 }; + /** + The first form gets the default text font for the lines in the + browser. + + <P>The second form sets the default text font to font + */ Fl_Font textfont() const {return textfont_;} + /** + The first form gets the default text font for the lines in the + browser. + + <P>The second form sets the default text font to font + */ void textfont(Fl_Font s) {textfont_ = s;} + /** + The first form gets the default text size for the lines in the + browser. + + <P>The second form sets the default text size to size + */ Fl_Fontsize textsize() const {return textsize_;} void textsize(Fl_Fontsize s) {textsize_ = s;} + /** + The first form gets the default text color for the lines in the + browser. + + <P>The second form sets the default text color to color + */ Fl_Color textcolor() const {return (Fl_Color)textcolor_;} void textcolor(unsigned n) {textcolor_ = n;} + /** Sets or gets the width of any scrollbars that are used. */ static void scrollbar_width(int b) {scrollbar_width_ = b;} + /** Sets or gets the width of any scrollbars that are used. */ static int scrollbar_width() {return scrollbar_width_;} // for back compatability: + /** This method moves the vertical scrollbar to the righthand side of the list. */ void scrollbar_right() {scrollbar.align(FL_ALIGN_RIGHT);} + /** This method moves the vertical scrollbar to the lefthand side of the list. */ void scrollbar_left() {scrollbar.align(FL_ALIGN_LEFT);} }; diff --git a/FL/Fl_Check_Browser.H b/FL/Fl_Check_Browser.H index 713f5cd56..a69e69288 100644 --- a/FL/Fl_Check_Browser.H +++ b/FL/Fl_Check_Browser.H @@ -31,6 +31,10 @@ #include "Fl.H" #include "Fl_Browser_.H" +/** + The Fl_Check_Browser widget displays a scrolling list of text + lines that may be selected and/or checked by the user. +*/ class FL_EXPORT Fl_Check_Browser : public Fl_Browser_ { /* required routines for Fl_Browser_ subclass: */ @@ -69,6 +73,7 @@ class FL_EXPORT Fl_Check_Browser : public Fl_Browser_ { public: Fl_Check_Browser(int x, int y, int w, int h, const char *l = 0); + /** The destructor deletes all list items and destroys the browser. */ ~Fl_Check_Browser() { clear(); } int add(char *s); // add an (unchecked) item int add(char *s, int b); // add an item and set checked @@ -76,14 +81,22 @@ class FL_EXPORT Fl_Check_Browser : public Fl_Browser_ { int remove(int item); // delete an item. Returns nitems() // inline const char * methods to avoid breaking binary compatibility... + /** See int Fl_Check_Browser::add(char *s) */ int add(const char *s) { return add((char *)s); } + /** See int Fl_Check_Browser::add(char *s) */ int add(const char *s, int b) { return add((char *)s, b); } void clear(); // delete all items + /** + Returns how many lines are in the browser. The last line number is equal to + this. + */ int nitems() const { return nitems_; } + /** Returns how many items are currently checked. */ int nchecked() const { return nchecked_; } int checked(int item) const; void checked(int item, int b); + /** Equivalent to Fl_Check_Browser::checked(item, 1). */ void set_checked(int item) { checked(item, 1); } void check_all(); void check_none(); diff --git a/FL/Fl_File_Browser.H b/FL/Fl_File_Browser.H index aed0647d5..747bd5c9e 100644 --- a/FL/Fl_File_Browser.H +++ b/FL/Fl_File_Browser.H @@ -41,6 +41,7 @@ // Fl_File_Browser class... // +/** The Fl_File_Browser widget displays a list of filenames, optionally with file-specific icons. */ class FL_EXPORT Fl_File_Browser : public Fl_Browser { int filetype_; @@ -57,20 +58,55 @@ class FL_EXPORT Fl_File_Browser : public Fl_Browser public: enum { FILES, DIRECTORIES }; + /** + The constructor creates the Fl_File_Browser widget at the specified position and size. + The destructor destroys the widget and frees all memory that has been allocated. + */ Fl_File_Browser(int, int, int, int, const char * = 0); + /** Sets or gets the size of the icons. The default size is 20 pixels. */ uchar iconsize() const { return (iconsize_); }; + /** Sets or gets the size of the icons. The default size is 20 pixels. */ void iconsize(uchar s) { iconsize_ = s; redraw(); }; + /** + Sets or gets the filename filter. The pattern matching uses + the fl_filename_match() + function in FLTK. + */ void filter(const char *pattern); + /** + Sets or gets the filename filter. The pattern matching uses + the fl_filename_match() + function in FLTK. + */ const char *filter() const { return (pattern_); }; + /** + Loads the specified directory into the browser. If icons have been + loaded then the correct icon is associated with each file in the list. + + <P>The sort argument specifies a sort function to be used with + fl_filename_list(). + */ int load(const char *directory, Fl_File_Sort_F *sort = fl_numericsort); Fl_Fontsize textsize() const { return Fl_Browser::textsize(); }; void textsize(Fl_Fontsize s) { Fl_Browser::textsize(s); iconsize_ = (uchar)(3 * s / 2); }; + /** + Sets or gets the file browser type, FILES or + DIRECTORIES. When set to FILES, both + files and directories are shown. Otherwise only directories are + shown. + */ int filetype() const { return (filetype_); }; + /** + Sets or gets the file browser type, FILES or + DIRECTORIES. When set to FILES, both + files and directories are shown. Otherwise only directories are + shown. + */ void filetype(int t) { filetype_ = t; }; }; diff --git a/FL/Fl_Hold_Browser.H b/FL/Fl_Hold_Browser.H index 6b5545b34..e09d52be6 100644 --- a/FL/Fl_Hold_Browser.H +++ b/FL/Fl_Hold_Browser.H @@ -30,9 +30,24 @@ #include "Fl_Browser.H" +/** + The Fl_Hold_Browser is a subclass of Fl_Browser + which lets the user select a single item, or no items by clicking on + the empty space. As long as the mouse button is held down the item + pointed to by it is highlighted, and this highlighting remains on when + the mouse button is released. Normally the callback is done when the + user releases the mouse, but you can change this with when(). + <P>See Fl_Browser for methods to add and remove lines from the browser. +*/ class Fl_Hold_Browser : public Fl_Browser { public: - Fl_Hold_Browser(int X,int Y,int W,int H,const char *l=0) + /** + Creates a new Fl_Hold_Browser widget using the given + position, size, and label string. The default boxtype is FL_DOWN_BOX. + The constructor specializes Fl_Browser() by setting the type to FL_HOLD_BROWSER. + The destructor destroys the widget and frees all memory that has been allocated. + */ + Fl_Hold_Browser(int X,int Y,int W,int H,const char *l=0) : Fl_Browser(X,Y,W,H,l) {type(FL_HOLD_BROWSER);} }; diff --git a/FL/Fl_Multi_Browser.H b/FL/Fl_Multi_Browser.H index 17b31f3e9..0bd1c1f7c 100644 --- a/FL/Fl_Multi_Browser.H +++ b/FL/Fl_Multi_Browser.H @@ -30,8 +30,24 @@ #include "Fl_Browser.H" +/** + The Fl_Multi_Browser class is a subclass of Fl_Browser + which lets the user select any set of the lines. The user interface + is Macintosh style: clicking an item turns off all the others and + selects that one, dragging selects all the items the mouse moves over, + and shift + click toggles the items. This is different then how forms + did it. Normally the callback is done when the user releases the + mouse, but you can change this with when(). + <P>See Fl_Browser for methods to add and remove lines from the browser. +*/ class Fl_Multi_Browser : public Fl_Browser { public: + /** + Creates a new Fl_Multi_Browser widget using the given + position, size, and label string. The default boxtype is FL_DOWN_BOX. + The constructor specializes Fl_Browser() by setting the type to FL_MULTI_BROWSER. + The destructor destroys the widget and frees all memory that has been allocated. + */ Fl_Multi_Browser(int X,int Y,int W,int H,const char *L=0) : Fl_Browser(X,Y,W,H,L) {type(FL_MULTI_BROWSER);} }; diff --git a/FL/Fl_Select_Browser.H b/FL/Fl_Select_Browser.H index c055e76d2..304fac9be 100644 --- a/FL/Fl_Select_Browser.H +++ b/FL/Fl_Select_Browser.H @@ -30,9 +30,23 @@ #include "Fl_Browser.H" +/** + The class is a subclass of Fl_Browser + which lets the user select a single item, or no items by clicking on + the empty space. As long as the mouse button is held down on an + unselected item it is highlighted. Normally the callback is done when the + user presses the mouse, but you can change this with when(). + <P>See Fl_Browser for methods to add and remove lines from the browser. +*/ class Fl_Select_Browser : public Fl_Browser { public: - Fl_Select_Browser(int X,int Y,int W,int H,const char *l=0) + /** + Creates a new Fl_Select_Browser widget using the given + position, size, and label string. The default boxtype is FL_DOWN_BOX. + The constructor specializes Fl_Browser() by setting the type to FL_SELECT_BROWSER. + The destructor destroys the widget and frees all memory that has been allocated. + */ + Fl_Select_Browser(int X,int Y,int W,int H,const char *l=0) : Fl_Browser(X,Y,W,H,l) {type(FL_SELECT_BROWSER);} }; diff --git a/FL/Fl_Widget.H b/FL/Fl_Widget.H index 41deefba5..fab179f7b 100644 --- a/FL/Fl_Widget.H +++ b/FL/Fl_Widget.H @@ -811,7 +811,8 @@ public: void damage(uchar c, int x, int y, int w, int h); void draw_label(int, int, int, int, Fl_Align) const; - void measure_label(int& xx, int& yy) {label_.measure(xx,yy);} + /** Sets width ww, height hh accordingly with the labeltype size, label with images will return w() h() of the image. */ + void measure_label(int& ww, int& hh) {label_.measure(ww, hh);} /** Returns a pointer to the primary Fl_Window widget. * \retval NULL if no window is associated with this widget. |