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: +
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));} 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. +
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.
+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. + +
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. + +
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: + +
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. + +
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. + +
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. + +
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. + +
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(). +
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(). +
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(). +
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. diff --git a/documentation/todo_filelist_doc.txt b/documentation/todo_filelist_doc.txt index 8264639b7..fca8239e8 100644 --- a/documentation/todo_filelist_doc.txt +++ b/documentation/todo_filelist_doc.txt @@ -10,7 +10,7 @@ header. Most other stuff goes into the source. In Progress Work List (add your WP and name here): - WP1 (Fabien) DONE - - WP2 (Fabien) + - WP2 (Fabien) DONE - WP3 - WP4 - WP5 diff --git a/src/Fl_Browser.cxx b/src/Fl_Browser.cxx index 5e24bbce9..c7325b583 100644 --- a/src/Fl_Browser.cxx +++ b/src/Fl_Browser.cxx @@ -128,11 +128,16 @@ FL_BLINE* Fl_Browser::_remove(int line) { return(ttt); } +/** Remove line n and make the browser one line shorter.*/ void Fl_Browser::remove(int line) { if (line < 1 || line > lines) return; free(_remove(line)); } +/** + Insert a new line before line n. If n > + size() then the line is added to the end. +*/ void Fl_Browser::insert(int line, FL_BLINE* t) { if (!first) { t->prev = t->next = 0; @@ -173,11 +178,25 @@ void Fl_Browser::insert(int line, const char* newtext, void* d) { insert(line, t); } +/** + Line from is removed and reinserted at to; to + is calculated after the line is removed. +*/ void Fl_Browser::move(int to, int from) { if (from < 1 || from > lines) return; insert(to, _remove(from)); } +/** + The first form returns the text for line n. If n is + out of range it returns NULL. +
The second form sets the text for line n. +*/ +/** + The first form returns the text for line n. If n is + out of range it returns NULL. +
The second form sets the text for line n. +*/ void Fl_Browser::text(int line, const char* newtext) { if (line < 1 || line > lines) return; FL_BLINE* t = find_line(line); @@ -200,6 +219,16 @@ void Fl_Browser::text(int line, const char* newtext) { redraw_line(t); } +/** + The first form returns the data for line n. If n is + out of range this returns NULL. +
The second form sets the data for line n. +*/ +/** + The first form returns the data for line n. If n is + out of range this returns NULL. +
The second form sets the data for line n. +*/ void Fl_Browser::data(int line, void* d) { if (line < 1 || line > lines) return; find_line(line)->data = d; @@ -392,8 +421,9 @@ void Fl_Browser::item_draw(void* v, int X, int Y, int W, int H) const { static const int no_columns[1] = {0}; +/** The constructor makes an empty browser.*/ Fl_Browser::Fl_Browser(int X, int Y, int W, int H, const char*l) - : Fl_Browser_(X, Y, W, H, l) { +: Fl_Browser_(X, Y, W, H, l) { column_widths_ = no_columns; lines = 0; full_height_ = 0; @@ -427,10 +457,16 @@ void Fl_Browser::lineposition(int line, Fl_Line_Position pos) { position(final); } +/** + 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. +*/ int Fl_Browser::topline() const { return lineno(top()); } +/** Remove all the lines in the browser.*/ void Fl_Browser::clear() { for (FL_BLINE* l = first; l;) { FL_BLINE* n = l->next; @@ -443,6 +479,12 @@ void Fl_Browser::clear() { new_list(); } +/** + Add a new line to the end of the browser. The text is copied using + the strdup() function. It may also be NULL to make a + blank line. The void * argument is returned as the data() + of the new item. +*/ void Fl_Browser::add(const char* newtext, void* d) { insert(lines+1, newtext, d); //Fl_Browser_::display(last); @@ -463,11 +505,13 @@ int Fl_Browser::select(int line, int v) { return Fl_Browser_::select(find_line(line), v); } +/** Return 1 if line n is selected, 0 if it not selected.*/ int Fl_Browser::selected(int line) const { if (line < 1 || line > lines) return 0; return find_line(line)->flags & SELECTED; } +/** Makes line n visible for selection.*/ void Fl_Browser::show(int line) { FL_BLINE* t = find_line(line); if (t->flags & NOTDISPLAYED) { @@ -477,6 +521,10 @@ void Fl_Browser::show(int line) { } } +/** + Makes line n invisible, preventing selection by the user. + The line can still be selected under program control. +*/ void Fl_Browser::hide(int line) { FL_BLINE* t = find_line(line); if (!(t->flags & NOTDISPLAYED)) { @@ -491,6 +539,7 @@ void Fl_Browser::display(int line, int v) { if (v) show(line); else hide(line); } +/** Returns a non-zero value if line n is visible.*/ int Fl_Browser::visible(int line) const { if (line < 1 || line > lines) return 0; return !(find_line(line)->flags&NOTDISPLAYED); @@ -540,6 +589,7 @@ void Fl_Browser::swap(FL_BLINE *a, FL_BLINE *b) { cache = 0; } +/** Swaps two lines in the browser.*/ void Fl_Browser::swap(int ai, int bi) { if (ai < 1 || ai > lines || bi < 1 || bi > lines) return; FL_BLINE* a = find_line(ai); diff --git a/src/Fl_Browser_.cxx b/src/Fl_Browser_.cxx index 9a6b8f801..2bc6ce99f 100644 --- a/src/Fl_Browser_.cxx +++ b/src/Fl_Browser_.cxx @@ -94,6 +94,10 @@ void Fl::scrollbar_size(int W) { } // return where to draw the actual box: +/** + This method returns the bounding box for the interior of the list, inside + the scrollbars. +*/ void Fl_Browser_::bbox(int& X, int& Y, int& W, int& H) const { Fl_Boxtype b = box() ? box() : FL_DOWN_BOX; X = x()+Fl::box_dx(b); @@ -112,6 +116,10 @@ void Fl_Browser_::bbox(int& X, int& Y, int& W, int& H) const { if (H < 0) H = 0; } +/** + This method returns the X position of the left edge of the list area + after adjusting for the scrollbar and border, if any. +*/ int Fl_Browser_::leftedge() const { int X, Y, W, H; bbox(X, Y, W, H); return X; @@ -120,6 +128,7 @@ int Fl_Browser_::leftedge() const { // The scrollbars may be moved again by draw(), since each one's size // depends on whether the other is visible or not. This skips over // Fl_Group::resize since it moves the scrollbars uselessly. +/** Repositions and/or resizes the browser.*/ void Fl_Browser_::resize(int X, int Y, int W, int H) { Fl_Widget::resize(X, Y, W, H); // move the scrollbars so they can respond to events: @@ -133,6 +142,10 @@ void Fl_Browser_::resize(int X, int Y, int W, int H) { } // Cause minimal update to redraw the given item: +/** + This method should be called when the contents of an item have changed + but not changed the height of the item. +*/ void Fl_Browser_::redraw_line(void* l) { if (!redraw1 || redraw1 == l) {redraw1 = l; damage(FL_DAMAGE_EXPOSE);} else if (!redraw2 || redraw2 == l) {redraw2 = l; damage(FL_DAMAGE_EXPOSE);} @@ -195,6 +208,11 @@ void Fl_Browser_::update_top() { // Change position(), top() will update when update_top() is called // (probably by draw() or handle()): +/** + Gets or sets the vertical scrolling position of the list, + which is the pixel offset of the list items within the list + area. +*/ void Fl_Browser_::position(int yy) { if (yy < 0) yy = 0; if (yy == position_) return; @@ -202,6 +220,11 @@ void Fl_Browser_::position(int yy) { if (yy != real_position_) redraw_lines(); } +/** + Gets or sets the horizontal scrolling position of the list, + which is the pixel offset of the list items within the list + area. +*/ void Fl_Browser_::hposition(int xx) { if (xx < 0) xx = 0; if (xx == hposition_) return; @@ -210,6 +233,10 @@ void Fl_Browser_::hposition(int xx) { } // Tell whether item is currently displayed: +/** + This method returns non-zero if item p is currently visible in + the list. +*/ int Fl_Browser_::displayed(void* p) const { int X, Y, W, H; bbox(X, Y, W, H); int yy = H+offset_; @@ -222,6 +249,7 @@ int Fl_Browser_::displayed(void* p) const { // Ensure this item is displayed: // Messy because we have no idea if it is before top or after bottom: +/** Displays item p, scrolling the list as necessary.*/ void Fl_Browser_::display(void* p) { // First special case - want to display first item in the list? @@ -304,6 +332,12 @@ void Fl_Browser_::display(void* p) { // redraw, has side effect of updating top and setting scrollbar: +/** + The first form draws the list within the normal widget bounding box. + +
The second form draws the contents of the browser within the + specified bounding box. +*/ void Fl_Browser_::draw() { int drawsquare = 0; update_top(); @@ -455,6 +489,11 @@ J1: } // Quick way to delete and reset everything: +/** + This method should be called when the list data is completely replaced + or cleared. It informs the Fl_Browser_ widget that any cached + information it has concerning the items is invalid. +*/ void Fl_Browser_::new_list() { top_ = 0; position_ = real_position_ = 0; @@ -468,6 +507,11 @@ void Fl_Browser_::new_list() { // Tell it that this item is going away, and that this must remove // all pointers to it: +/** + This method should be used when an item is deleted from the list. + It allows the Fl_Browser_ to discard any cached data it has + on the item. +*/ void Fl_Browser_::deleting(void* l) { if (displayed(l)) { redraw_lines(); @@ -487,6 +531,10 @@ void Fl_Browser_::deleting(void* l) { if (l == max_width_item) {max_width_item = 0; max_width = 0;} } +/** + This method should be used when an item is replaced in the list. + It allows the Fl_Browser_ to update its cache data as needed. +*/ void Fl_Browser_::replacing(void* a, void* b) { redraw_line(a); if (a == selection_) selection_ = b; @@ -503,11 +551,19 @@ void Fl_Browser_::swapping(void* a, void* b) { else if (b == top_) top_ = a; } +/** + This method should be used when an item is added to the list. + It allows the Fl_Browser_ to update its cache data as needed. +*/ void Fl_Browser_::inserting(void* a, void* b) { if (displayed(a)) redraw_lines(); if (a == top_) top_ = b; } +/** + This method returns the item under mouse at my. If no item is + displayed at that position then NULL is returned. +*/ void* Fl_Browser_::find_item(int my) { update_top(); int X, Y, W, H; bbox(X, Y, W, H); @@ -521,6 +577,13 @@ void* Fl_Browser_::find_item(int my) { return 0; } +/** + Sets the selection state of item p to s and + returns 1 if the state changed or 0 if it did not. + +
If docb is non-zero, select tries to call the callback + function for the widget. +*/ int Fl_Browser_::select(void* l, int i, int docallbacks) { if (type() == FL_MULTI_BROWSER) { if (selection_ != l) { @@ -553,6 +616,13 @@ int Fl_Browser_::select(void* l, int i, int docallbacks) { return 1; } +/** + Deselects all items in the list and returns 1 if the state changed + or 0 if it did not. + +
If docb is non-zero, deselect tries to call the + callback function for the widget. +*/ int Fl_Browser_::deselect(int docallbacks) { if (type() == FL_MULTI_BROWSER) { int change = 0; @@ -568,6 +638,13 @@ int Fl_Browser_::deselect(int docallbacks) { } } +/** + Selects item p and returns 1 if the state changed or 0 if it did + not. Any other items in the list are deselected. + +
If docb is non-zero, select_only tries to call the
+ callback function for the widget.
+*/
int Fl_Browser_::select_only(void* l, int docallbacks) {
if (!l) return deselect(docallbacks);
int change = 0;
@@ -579,7 +656,7 @@ int Fl_Browser_::select_only(void* l, int docallbacks) {
display(l);
return change;
}
-
+/** Handles an event within the normal widget bounding box. */
int Fl_Browser_::handle(int event) {
// must do shortcuts first or the scrollbar will get them...
if (event == FL_ENTER || event == FL_LEAVE) return 1;
@@ -796,6 +873,7 @@ J1:
return 0;
}
+/** The constructor makes an empty browser.*/
Fl_Browser_::Fl_Browser_(int X, int Y, int W, int H, const char* l)
: Fl_Group(X, Y, W, H, l),
scrollbar(0, 0, 0, 0, 0), // they will be resized by draw()
@@ -826,14 +904,32 @@ Fl_Browser_::Fl_Browser_(int X, int Y, int W, int H, const char* l)
// Default versions of some of the virtual functions:
+/**
+ This method may 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. This method differs from
+ item_height in that it is only
+ called for selection and scrolling operations. The default implementation
+ calls item_height.
+*/
int Fl_Browser_::item_quick_height(void* l) const {
return item_height(l);
}
+/**
+ This method may be provided to return the average height of all items, to
+ be used for scrolling. The default implementation uses the height of the first
+ item.
+*/
int Fl_Browser_::incr_height() const {
return item_quick_height(item_first());
}
+/**
+ This method may be provided by the subclass to indicate the full height
+ of the item list in pixels. The default implementation computes the full
+ height from the item heights.
+*/
int Fl_Browser_::full_height() const {
int t = 0;
for (void* p = item_first(); p; p = item_next(p))
@@ -841,12 +937,27 @@ int Fl_Browser_::full_height() const {
return t;
}
+/**
+ This method may be provided by the subclass to indicate the full width
+ of the item list in pixels. The default implementation computes the full
+ width from the item widths.
+*/
int Fl_Browser_::full_width() const {
return max_width;
}
+/**
+ This method must be implemented by the subclass if it supports
+ multiple selections in the browser. The s argument specifies the
+ selection state for item p: 0 = off, 1 = on.
+*/
void Fl_Browser_::item_select(void*, int) {}
+/**
+ This method must be implemented by the subclass if it supports
+ multiple selections in the browser. The method should return 1 if p
+ is selected and 0 otherwise.
+*/
int Fl_Browser_::item_selected(void* l) const {return l==selection_;}
//
diff --git a/src/Fl_Browser_load.cxx b/src/Fl_Browser_load.cxx
index 7e99a56b7..9112074a9 100644
--- a/src/Fl_Browser_load.cxx
+++ b/src/Fl_Browser_load.cxx
@@ -30,6 +30,14 @@
#include The Fl_File_Chooser class also exports several static values
+ that may be used to localize or customize the appearance of all file chooser
+ dialogs:
+
+ The sort member specifies the sort function that is
+ used when loading the contents of a directory.
+*/
+
+/** \fn Fl_File_Chooser::Fl_File_Chooser(const char *pathname, const char *pattern, int type, const char *title)
+ The constructor creates the Fl_File_Chooser dialog pictured
+ above. The pathname argument can be a directory name or a
+ complete file name (in which case the corresponding file is highlighted
+ in the list and in the filename input field.)
+
+ The pattern argument can be a NULL
+ string or "*" to list all files, or it can be a
+ series of descriptions and filter strings separated by tab
+ characters (\t). The format of filters is either
+ "Description text (patterns)" or just "patterns". A file chooser
+ that provides filters for HTML and image files might look like:
+
+ The file chooser will automatically add the "All Files (*)"
+ pattern to the end of the string you pass if you do not provide
+ one. The first filter in the string is the default filter.
+
+ See the FLTK documentation on fl_filename_match()
+ for the kinds of pattern strings that are supported.
+
+ The type argument can be one of the following:
+
+ The title argument is used to set the title bar text for the
+ Fl_File_Chooser window.
+*/
+
+/** \fn Fl_File_Chooser::~Fl_File_Chooser()
+ Destroys the widget and frees all memory used by it.*/
+
+/** \fn void Fl_File_Chooser::color(Fl_Color c)
+ Sets or gets the background color of the Fl_File_Browser list.*/
+
+/** \fn Fl_Color Fl_File_Chooser::color()
+ Sets or gets the background color of the Fl_File_Browser list.*/
+
+/** \fn int Fl_File_Chooser::count()
+ Returns the number of selected files.*/
+
+/** \fn void Fl_File_Chooser::directory(const char *pathname)
+ Sets or gets the current directory.*/
+
+/** \fn const char *Fl_File_Chooser::directory()
+ Sets or gets the current directory.*/
+
+/** \fn void Fl_File_Chooser::filter(const char *pattern)
+ Sets or gets the current filename filter patterns. The filter
+ patterns use fl_filename_match().
+ Multiple patterns can be used by separating them with tabs, like
+ "*.jpg\t*.png\t*.gif\t*". In addition, you can provide
+ human-readable labels with the patterns inside parenthesis, like
+ "JPEG Files (*.jpg)\tPNG Files (*.png)\tGIF Files (*.gif)\tAll Files (*)".
+ Use filter(NULL) to show all files.
+*/
+
+/** \fn const char *Fl_File_Chooser::filter()
+ See void filter(const char *pattern)*/
+
+/** \fn void Fl_File_Chooser::filter_value(int f)
+ Sets or gets the current filename filter selection.*/
+
+/** \fn int Fl_File_Chooser::filter_value()
+ Sets or gets the current filename filter selection.*/
+
+/** \fn void Fl_File_Chooser::hide()
+ Hides the Fl_File_Chooser window.*/
+
+/** \fn void Fl_File_Chooser::iconsize(uchar s)
+ Sets or gets the size of the icons in the Fl_File_Browser. By
+ default the icon size is set to 1.5 times the textsize().
+*/
+
+/** \fn uchar Fl_File_Chooser::iconsize()
+ Sets or gets the size of the icons in the Fl_File_Browser. By
+ default the icon size is set to 1.5 times the textsize().
+*/
+
+/** \fn void Fl_File_Chooser::label(const char *l)
+ Sets or gets the title bar text for the Fl_File_Chooser.*/
+
+/** \fn const char *Fl_File_Chooser::label()
+ Sets or gets the title bar text for the Fl_File_Chooser.*/
+
+/** \fn void Fl_File_Chooser::ok_label(const char *l)
+ Sets or gets the label for the "ok" button in the
+ Fl_File_Chooser.
+*/
+
+/** \fn const char *Fl_File_Chooser::ok_label()
+ Sets or gets the label for the "ok" button in the
+ Fl_File_Chooser.
+*/
+
+/** \fn int Fl_File_Chooser::preview() const
+ Returns the current state of the preview box. */
+
+/** \fn void Fl_File_Chooser::rescan()
+ Reloads the current directory in the Fl_File_Browser.*/
+
+/** \fn void Fl_File_Chooser::show()
+ Shows the Fl_File_Chooser window.*/
+
+/** \fn void Fl_File_Chooser::textcolor(Fl_Color c)
+ Sets or gets the current Fl_File_Browser text color.*/
+
+/** \fn Fl_Color Fl_File_Chooser::textcolor()
+ Sets or gets the current Fl_File_Browser text color.*/
+
+/** \fn void Fl_File_Chooser::textfont(Fl_Font f)
+ Sets or gets the current Fl_File_Browser text font.*/
+
+/** \fn Fl_Font Fl_File_Chooser::textfont()
+ Sets or gets the current Fl_File_Browser text font.*/
+
+/** \fn void Fl_File_Chooser::textsize(Fl_Fontsize s)
+ Sets or gets the current Fl_File_Browser text size.*/
+
+/** \fn Fl_Fontsize Fl_File_Chooser::textsize()
+ Sets or gets the current Fl_File_Browser text size.*/
+
+/** \fn void Fl_File_Chooser::type(int t)
+ Sets or gets the current type of Fl_File_Chooser.*/
+
+/** \fn int Fl_File_Chooser::type()
+ Sets or gets the current type of Fl_File_Chooser.*/
+
+/** \fn const char *Fl_File_Chooser::value(const char *pathname)
+ Sets or gets the current value of the selected file.
+
+ In the second form, file is a 1-based index into a list of
+ file names. The number of selected files is returned by
+ Fl_File_Chooser::count().
+
+ This sample code loops through all selected files:
+
+
+
+ Member
+ Default value
+
+
+ add_favorites_label
+ "Add to Favorites"
+
+
+ all_files_label
+ "All Files (*)"
+
+
+ custom_filter_label
+ "Custom Filter"
+
+
+ existing_file_label
+ "Please choose an existing file!"
+
+
+ favorites_label
+ "Favorites"
+
+
+ filename_label
+ "Filename:"
+
+
+ filesystems_label
+ "My Computer" (WIN32)
+
+ "File Systems" (all others)
+
+ manage_favorites_label
+ "Manage Favorites"
+
+
+ new_directory_label
+ "New Directory?"
+
+
+ new_directory_tooltip
+ "Create a new directory."
+
+
+ preview_label
+ "Preview"
+
+
+ save_label
+ "Save"
+
+
+ show_label
+ "Show:"
+
+
+ sort
+ fl_numericsort
+
+ "HTML Files (*.html)\tImage Files (*.{bmp,gif,jpg,png})"
+
+
+
+
+
+
+ // Get list of filenames user selected from a MULTI chooser
+ for ( int t=1; t<=chooser->count(); t++ ) {
+ const char *filename = chooser->value(t);
+ ..
+ }
+
+*/
+
+/** \fn const char *Fl_File_Chooser::value(int file)
+ See const char *value(const char *pathname)*/
+
+/** \fn const char *Fl_File_Chooser::value()
+ See const char *value(const char *pathname)*/
+
+/** \fn int Fl_File_Chooser::visible()
+ Returns 1 if the Fl_File_Chooser window is visible.*/
+
+/** \fn Fl_Widget* Fl_File_Chooser::add_extra(Fl_Widget*)
+ Adds extra widget at the bottom of Fl_File_Chooser window.
+ Returns pointer for previous extra widget or NULL if not set previously.
+ If argument is NULL only remove previous extra widget.
+ NOTE! Fl_File_Chooser doesn't delete extra widget in destructor! To prevent memory leakage don't forget
+ delete unused extra widgets by yourself.
+*/
+ /** \fn int Fl_File_Chooser::shown()
+ Returns non-zero if the file chooser main window show() has been called (but not hide()
+ see Fl_Window::shown()
+ */
+
+ /** \fn void Fl_File_Chooser::callback(void (*cb)(Fl_File_Chooser *, void *), void *d = 0)
+ Sets the file chooser callback cb and associated data d */
+
+ /** \fn void Fl_File_Chooser::user_data(void *d)
+ Sets the file chooser user data d */
+
+ /** \fn void * Fl_File_Chooser::user_data() const
+ Gets the file chooser user data d */
+
+// *** END OF OUT OF SOURCE DOC ***
+
// Contents:
//
// Fl_File_Chooser::count() - Return the number of selected files.
@@ -794,12 +1064,9 @@ Fl_File_Chooser::newdir()
}
-//
-// 'Fl_File_Chooser::preview()' - Enable or disable the preview tile.
-//
-void
-Fl_File_Chooser::preview(int e)// I - 1 = enable preview, 0 = disable preview
+/** Enable or disable the preview tile. 1 = enable preview, 0 = disable preview. */
+void Fl_File_Chooser::preview(int e)
{
previewButton->value(e);
prefs_.set("preview", e);
@@ -868,12 +1135,11 @@ Fl_File_Chooser::rescan()
}
//
-// 'Fl_File_Chooser::rescan_keep_filename()' - Rescan the current directory
-// without clearing the filename, then select the file if it is in the list
-//
-
-void
-Fl_File_Chooser::rescan_keep_filename()
+/**
+ Rescan the current directory without clearing the filename,
+ then select the file if it is in the list
+*/
+void Fl_File_Chooser::rescan_keep_filename()
{
// if no filename was set, this is likely a diretory browser
const char *fn = fileName->value();
diff --git a/src/glut_font.cxx b/src/glut_font.cxx
index 6053d733a..788e9dee4 100644
--- a/src/glut_font.cxx
+++ b/src/glut_font.cxx
@@ -114,8 +114,10 @@ void glutStrokeString(void* fontID, const unsigned char *string) {
* A newline will simply translate the next character's insertion
* point back to the start of the line and down one line.
*/
-
+#if !defined(WIN32) || defined(CYGWIN)
#warning FIXME This needs to be UTF aware now
+#endif
+
while ((c = *string++) != 0) {
if (c < font->Quantity) {
if (c == '\n') {