mirrors/fltk
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

o Major mods to Fl_Browser_.{cxx.H}'s doxygen docs

Browse Source 
o Small mods to Fl_Browser.{cxx,H}'s doxygen docs
	o FL_SORT_ASC/DESC -> FL_SORT_ASCENDING/DESCENDING (includes necessary mod to test/browser.cxx demo)

	TODO: Fl_Browser needs new '\see Related methods: ' that was initiated in Fl_Browser_



git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6720 ea41ed52-d2ee-0310-a9c1-e6b18d33e121
This commit is contained in:
Greg Ercolano 2009-03-25 23:09:04 +00:00
parent 9c191c2317
commit f414a50dd2
5 changed files with 403 additions and 283 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

53
FL/Fl_Browser.H
View File

@ -139,46 +139,61 @@ 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.
Returns 0 if browser is empty.
/**
Returns how many lines are in the browser.
The last line number is equal to this.
Returns 0 if browser is empty.
*/
int size() const {return lines;}
int size() const { return lines; }
void size(int W, int H) { Fl_Widget::size(W, H); }
int topline() const ;
/** For internal use only? */
enum Fl_Line_Position { TOP, BOTTOM, MIDDLE };
void lineposition(int line, Fl_Line_Position pos);
/** Scrolls the browser so the top item in the browser is showing the specified \p line. */
/**
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.
*/
void topline(int line) { lineposition(line, TOP); }
/** Scrolls the browser so the bottom item in the browser is showing the specified \p line. */
/**
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.
*/
void bottomline(int line) { lineposition(line, BOTTOM); }
/** Scrolls the browser so the middle item in the browser is showing the specified \p line. */
/**
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.
*/
void middleline(int line) { lineposition(line, MIDDLE); }
int select(int line, int val=1);
int selected(int line) const ;
void show(int line);
/** Shows the entire Fl_Browser widget -- opposite of hide(). */
void show() {Fl_Widget::show();}
void show() { Fl_Widget::show(); }
void hide(int line);
/** Hides the entire Fl_Browser widget -- opposite of show(). */
void hide() {Fl_Widget::hide();}
void hide() { Fl_Widget::hide(); }
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).
*/
void value(int line) { select(line);}
void value(int line) { select(line); }
const char* text(int line) const ;
void text(int line, const char* newtext);
void* data(int line) const ;
void data(int line, void* d);
Fl_Browser(int X, int Y, int W, int H, const char *L = 0);
/** The destructor deletes all list items and destroys the browser. */
/**
The destructor deletes all list items and destroys the browser.
*/
~Fl_Browser() { clear(); }
/**
@ -210,24 +225,24 @@ public:
<tt>sprintf("\@C%d\@.%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_;}
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
*/
void format_char(char c) {format_char_ = c;}
void format_char(char c) { format_char_ = c; }
/**
Gets the current column separator character.
The default is '\\t' (tab).
*/
char column_char() const {return column_char_;}
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).
*/
void column_char(char c) {column_char_ = c;}
void column_char(char c) { column_char_ = c; }
/**
Gets the current column width array.
This array is zero-terminated and specifies the widths in pixels of
@ -250,17 +265,17 @@ public:
[..]
\endcode
*/
const int* column_widths() const {return 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
*/
void column_widths(const int* arr) {column_widths_ = arr;}
void column_widths(const int* arr) { column_widths_ = arr; }
/**
Returns non-zero if \p line is visible.
*/
int displayed(int line) const {return Fl_Browser_::displayed(find_line(line));}
int displayed(int line) const { return Fl_Browser_::displayed(find_line(line)); }
/**
Make the item at the specified \p line visible().
@ -276,7 +291,7 @@ public:
}
/** For back compatibility only. */
void replace(int a, const char* b) {text(a, b);}
void replace(int a, const char* b) { text(a, b); }
void display(int line, int val=1);
};

283
FL/Fl_Browser_.H
View File

@ -28,11 +28,6 @@
/* \file
Fl_Browser_ widget . */
// This is the base class for browsers. To be useful it must
// be subclassed and several virtual functions defined. The
// Forms-compatable browser and the file chooser's browser are
// subclassed off of this.
// Yes, I know this should be a template...
#ifndef Fl_Browser__H
@ -48,11 +43,11 @@
#define FL_HOLD_BROWSER 2 /**< type() of Fl_Hold_Browser */
#define FL_MULTI_BROWSER 3 /**< type() of Fl_Multi_Browser */
#define FL_SORT_ASC 0 /**< sort browser items in ascending alphabetic order. */
#define FL_SORT_DESC 1 /**< sort in descending order */
#define FL_SORT_ASCENDING 0 /**< sort browser items in ascending alphabetic order. */
#define FL_SORT_DESCENDING 1 /**< sort in descending order */
/**
This is the base for browsers. To be useful it must be
This is the base class 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.
@ -91,211 +86,237 @@ class FL_EXPORT Fl_Browser_ : public Fl_Group {
protected:
// All of the following must be supplied by the subclass:
/** 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 can be provided by the subclass to return the ilast item in the list. */
virtual void *item_last() const { return 0L; }
/**
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()
*/
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()
*/
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()
*/
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()
*/
virtual void *item_last() const { return 0L; }
/**
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.
This method must be provided by the subclass to return
the height of \p item in pixels.
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()
*/
virtual int item_height(void *) const = 0;
virtual int item_height(void *item) 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
\p item in pixels. Allow for two additional pixels for the list
selection box.
\param[in] item The item whose width is returned.
\returns The width of the item in pixels.
*/
virtual int item_width(void *) const = 0;
virtual int item_quick_height(void *) const ;
virtual int item_width(void *item) const = 0;
virtual int item_quick_height(void *item) const ;
/**
This method must be provided by the subclass to draw the item
p in the area indicated by x, y, w,
and h.
This method must be provided by the subclass to draw the \p item
in the area indicated by \p X, \p Y, \p W, \p H.
*/
virtual void item_draw(void *,int,int,int,int) const = 0;
virtual void item_draw(void *item,int X,int Y,int W,int H) const = 0;
/**
This optional function returns a string that may be used for sorting.
This optional method returns a string (label) that may be used for sorting.
\param[in] item The item whose label text is returned.
\returns The item's text label. (Can be NULL if blank)
*/
virtual const char *item_text(void *item) const { return 0L; }
/**
This optional function is required for sorting browser items.
This optional method should be provided by the subclass
to efficiently swap browser items \p a and \p b, such as for sorting.
\param[in] a,b The two items to be swapped.
*/
virtual void item_swap(void*, void*) { }
virtual void item_swap(void *a,void *b) { }
/**
Return the item a specified index.
This method must be provided by the subclass
to return the item for the specified \p index.
\param[in] index The \p index of the item to be returned
\returns The item at the specified \p index.
*/
virtual void *item_at(int) const { return 0L; }
virtual void *item_at(int index) const { return 0L; }
// you don't have to provide these but it may help speed it up:
virtual int full_width() const ; // current width of all items
virtual int full_height() const ; // current height of all items
virtual int incr_height() const ; // average height of an item
// These only need to be done by subclass if you want a multi-browser:
virtual void item_select(void *,int=1);
virtual int item_selected(void *) const ;
virtual void item_select(void *item,int val=1);
virtual int item_selected(void *item) 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 that 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,
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 *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
void deleting(void *item); // get rid of any pointers to item
void replacing(void *a,void *b); // change a pointers to b
void swapping(void *a,void *b); // exchange pointers a and b
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
int displayed(void *item) const ; // true if this item is visible
void redraw_line(void *item); // minimal update, no change in size
/**
Draws the contents of the browser within the specified bounding box.
\todo Find the implementation, if any, and document it there!
*/
void draw(int,int,int,int);
/*
Handles the specified event, plus 4 extra parameters!
\todo Find the implementation, if any, and document it there!
fabien: I guess the answer is there is no implementation (yet?),
so let's comment out this method that does not exist.
int handle(int,int,int,int,int);
*/
This method will cause the entire list to be redrawn.
\see Related methods: 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;
int leftedge() const; // x position after scrollbar & border
void *find_item(int ypos); // item under mouse
void draw();
Fl_Browser_(int,int,int,int,const char * = 0);
Fl_Browser_(int X,int Y,int W,int H,const char *L=0);
public:
/** Vertical scrollbar. */
/**
Vertical scrollbar. Public, so that it can be accessed directly.
*/
Fl_Scrollbar scrollbar;
/** Horizontal scrollbar */
/**
Horizontal scrollbar. Public, so that it can be accessed directly.
*/
Fl_Scrollbar hscrollbar;
int handle(int);
void resize(int,int,int,int);
int handle(int event);
void resize(int X,int Y,int W,int H);
int select(void *,int=1,int docallbacks=0);
int select_only(void *,int docallbacks=0);
int select(void *item,int val=1,int docallbacks=0);
int select_only(void *item,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.
Gets the vertical scroll position of the list as a pixel position \p pos.
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()
*/
int position() const {return position_;}
int position() const { return position_; }
void position(int pos); // scroll to here
/**
Gets or sets the horizontal scrolling position of the list,
which is the pixel offset of the list items within the list
area.
Gets the horizontal scroll position of the list as a pixel position \p pos.
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()
*/
int hposition() const {return hposition_;}
void position(int); // scroll to here
int hposition() const { return hposition_; }
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_;}
void display(void *item); // scroll so this item is shown
/**
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:
\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.
*/
void has_scrollbar(uchar i) {has_scrollbar_ = i;}
Values for has_scrollbar().
*/
enum { // values for has_scrollbar()
HORIZONTAL = 1,
VERTICAL = 2,
BOTH = 3,
ALWAYS_ON = 4,
HORIZONTAL_ALWAYS = 5,
VERTICAL_ALWAYS = 6,
BOTH_ALWAYS = 7
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
};
/**
Returns the current scrollbar mode, see Fl_Browser_::has_scrollbar(uchar)
*/
uchar has_scrollbar() const { return has_scrollbar_; }
/**
Sets whether the widget should have scrollbars or not (default Fl_Browser_::BOTH).
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 \p mode:
- 0 - No scrollbars.
- Fl_Browser_::HORIZONTAL - Only a horizontal scrollbar.
- Fl_Browser_::VERTICAL - Only a vertical scrollbar.
- Fl_Browser_::BOTH - The default is both scrollbars.
- Fl_Browser_::HORIZONTAL_ALWAYS - Horizontal scrollbar always on,
vertical always off.
- Fl_Browser_::VERTICAL_ALWAYS - Vertical scrollbar always on,
horizontal always off.
- Fl_Browser_::BOTH_ALWAYS - Both always on.
*/
void has_scrollbar(uchar mode) { has_scrollbar_ = mode; }
/**
Gets the default text font for the lines in the browser.
\see Related methods: textfont(), textsize(), textcolor()
*/
Fl_Font textfont() const {return textfont_;}
Fl_Font textfont() const { return textfont_; }
/**
Sets the default text font to font \p s
Sets the default text font for the lines in the browser to \p font.
*/
void textfont(Fl_Font s) {textfont_ = s;}
void textfont(Fl_Font font) { textfont_ = font; }
/**
Gets the default text size for the lines in the browser.
Gets the default text size (in pixels) for the lines in the browser.
*/
Fl_Fontsize textsize() const {return textsize_;}
Fl_Fontsize textsize() const { return textsize_; }
/**
Sets the default text size to size \p s.
Sets the default text size (in pixels) for the lines in the browser to \p size.
*/
void textsize(Fl_Fontsize s) {textsize_ = s;}
void textsize(Fl_Fontsize size) { textsize_ = size; }
/**
Gets the default text color for the lines in the browser.
*/
Fl_Color textcolor() const {return (Fl_Color)textcolor_;}
Fl_Color textcolor() const { return (Fl_Color)textcolor_; }
/**
Sets the default text color to color \p n.
Sets the default text color for the lines in the browser to color \p col.
*/
void textcolor(unsigned n) {textcolor_ = n;}
void textcolor(unsigned col) { textcolor_ = col; }
/**
Gets the width of any scrollbars that are used.
Gets the current width of scrollbars in pixels.
*/
static int scrollbar_width() {return scrollbar_width_;}
static int scrollbar_width() { return scrollbar_width_; }
/**
Sets the width of any scrollbars that are used to \p b.
Sets the width of scrollbars to pixel size \p width.
*/
static void scrollbar_width(int b) {scrollbar_width_ = b;}
static void scrollbar_width(int width) { scrollbar_width_ = width; }
/**
Moves the vertical scrollbar to the righthand side of the list.
For back compatibility.
*/
void scrollbar_right() {scrollbar.align(FL_ALIGN_RIGHT);}
void scrollbar_right() { scrollbar.align(FL_ALIGN_RIGHT); }
/**
Moves the vertical scrollbar to the lefthand side of the list.
For back compatibility.
*/
void scrollbar_left() {scrollbar.align(FL_ALIGN_LEFT);}
/**
Sort the items in the browser.
item_swap(void*, void*) and item_text(void*) must be implemented for this call.
\param[in] flags no flags were defined yet. Sorting in descending order and
sorting while ignoring case come to mind.
*/
void scrollbar_left() { scrollbar.align(FL_ALIGN_LEFT); }
void sort(int flags=0);
};
#endif

8
src/Fl_Browser.cxx
View File

@ -460,7 +460,7 @@ int Fl_Browser::full_height() const {
}
/**
The default height of items (including spacing in-between) in pixels.
The default 'average' item height (including inter-item spacing) in pixels.
This currently returns textsize() + 2.
\returns The value in pixels.
*/
@ -629,10 +629,10 @@ void Fl_Browser::clear() {
/**
Adds a new line to the end of the browser.
The text string newtext may contain format characters; see format_char() for details.
The text string \p newtext may contain format characters; see format_char() for details.
\p newtext is copied using the strdup() function, and can be NULL to make a blank line.
The optional void * argument \p d will be the data() for the new item.
The optional void* argument \p d will be the data() for the new item.
\param[in] newtext The label text used for the added item
\param[in] d Optional user data() for the item (0 if unspecified)
@ -753,7 +753,7 @@ int Fl_Browser::value() const {
/**
Swap the two items \p a and \p b.
You must call redraw() to make any changes visible.
Uses swapping() to ensure list updates correctly.
\param[in] a,b The two items to be swapped.
*/
void Fl_Browser::swap(FL_BLINE *a, FL_BLINE *b) {

340
src/Fl_Browser_.cxx
View File

@ -36,7 +36,7 @@
// This is the base class for browsers. To be useful it must be
// subclassed and several virtual functions defined. The
// Forms-compatable browser and the file chooser's browser are
// Forms-compatible browser and the file chooser's browser are
// subclassed off of this.
// Yes, I know this should be a template...
@ -72,22 +72,26 @@ static void hscrollbar_callback(Fl_Widget* s, void*) {
int Fl_Browser_::scrollbar_width_ = 16;
/**
Gets the default scrollbar size that is used by the
Fl_Browser_,
Fl_Help_View,
Fl_Scroll, and
Fl_Text_Display widgets.
Gets the default scrollbar size used by
Fl_Browser_,
Fl_Help_View,
Fl_Scroll, and
Fl_Text_Display widgets.
\returns The default size for widget scrollbars, in pixels.
\todo The source code for this method needs to be moved from Fl_Browser_.cxx to Fl.cxx
*/
int Fl::scrollbar_size() {
return Fl_Browser_::scrollbar_width();
}
/**
Sets the default scrollbar size that is used by the
Fl_Browser_,
Fl_Help_View,
Fl_Scroll, and
Fl_Text_Display widgets.
Sets the default scrollbar size that is used by the
Fl_Browser_,
Fl_Help_View,
Fl_Scroll, and
Fl_Text_Display widgets.
\param[in] W The new default size for widget scrollbars, in pixels.
\todo The source code for this method needs to be moved from Fl_Browser_.cxx to Fl.cxx
*/
void Fl::scrollbar_size(int W) {
Fl_Browser_::scrollbar_width(W);
@ -95,8 +99,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
Returns the bounding box for the interior of the list's display window, inside
the scrollbars.
\param[out] X,Y,W,H The returned bounding box.\n
(The original contents of these parameters are overwritten)
*/
void Fl_Browser_::bbox(int& X, int& Y, int& W, int& H) const {
Fl_Boxtype b = box() ? box() : FL_DOWN_BOX;
@ -119,6 +125,8 @@ void Fl_Browser_::bbox(int& X, int& Y, int& W, int& H) const {
/**
This method returns the X position of the left edge of the list area
after adjusting for the scrollbar and border, if any.
\returns The X position of the left edge of the list, in pixels.
\see Fl_Browser_::bbox()
*/
int Fl_Browser_::leftedge() const {
int X, Y, W, H; bbox(X, Y, W, H);
@ -128,7 +136,10 @@ 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.*/
/**
Repositions and/or resizes the browser.
\param[in] X,Y,W,H The new position and size for the browser, in pixels.
*/
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:
@ -143,12 +154,14 @@ 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.
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()
*/
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);}
void Fl_Browser_::redraw_line(void* item) {
if (!redraw1 || redraw1 == item) {redraw1 = item; damage(FL_DAMAGE_EXPOSE);}
else if (!redraw2 || redraw2 == item) {redraw2 = item; damage(FL_DAMAGE_EXPOSE);}
else damage(FL_DAMAGE_SCROLL);
}
@ -209,39 +222,49 @@ 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.
Sets the vertical scroll position of the list to pixel position \p pos.
The position is how many pixels of the list are scrolled off the top edge
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()
*/
void Fl_Browser_::position(int yy) {
if (yy < 0) yy = 0;
if (yy == position_) return;
position_ = yy;
if (yy != real_position_) redraw_lines();
void Fl_Browser_::position(int pos) {
if (pos < 0) pos = 0;
if (pos == position_) return;
position_ = pos;
if (pos != 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.
Sets the horizontal scroll position of the list to pixel position \p pos.
The position is how many pixels of the list are scrolled off the left edge
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()
*/
void Fl_Browser_::hposition(int xx) {
if (xx < 0) xx = 0;
if (xx == hposition_) return;
hposition_ = xx;
if (xx != real_hposition_) redraw_lines();
void Fl_Browser_::hposition(int pos) {
if (pos < 0) pos = 0;
if (pos == hposition_) return;
hposition_ = pos;
if (pos != real_hposition_) redraw_lines();
}
// Tell whether item is currently displayed:
/**
This method returns non-zero if item p is currently visible in
the list.
Returns non-zero if \p item 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] item The item to check
\returns 1 if visible, 0 if not visible.
*/
int Fl_Browser_::displayed(void* p) const {
int Fl_Browser_::displayed(void* item) const {
int X, Y, W, H; bbox(X, Y, W, H);
int yy = H+offset_;
for (void* l = top_; l && yy > 0; l = item_next(l)) {
if (l == p) return 1;
if (l == item) return 1;
yy -= item_height(l);
}
return 0;
@ -249,12 +272,15 @@ 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) {
/**
Displays the \p item, scrolling the list as necessary.
\param[in] item The item to be displayed.
*/
void Fl_Browser_::display(void* item) {
// First special case - want to display first item in the list?
update_top();
if (p == item_first()) {position(0); return;}
if (item == item_first()) {position(0); return;}
int X, Y, W, H, Yp; bbox(X, Y, W, H);
void* l = top_;
@ -262,11 +288,11 @@ void Fl_Browser_::display(void* p) {
int h1;
// 2nd special case - want to display item already displayed at top of browser?
if (l == p) {position(real_position_+Y); return;} // scroll up a bit
if (l == item) {position(real_position_+Y); return;} // scroll up a bit
// 3rd special case - want to display item just above top of browser?
void* lp = item_prev(l);
if (lp == p) {position(real_position_+Y-item_quick_height(lp)); return;}
if (lp == item) {position(real_position_+Y-item_quick_height(lp)); return;}
#ifdef DISPLAY_SEARCH_BOTH_WAYS_AT_ONCE
// search for item. We search both up and down the list at the same time,
@ -275,7 +301,7 @@ void Fl_Browser_::display(void* p) {
while (l || lp) {
if (l) {
h1 = item_quick_height(l);
if (l == p) {
if (l == item) {
if (Y <= H) { // it is visible or right at bottom
Y = Y+h1-H; // find where bottom edge is
if (Y > 0) position(real_position_+Y); // scroll down a bit
@ -290,7 +316,7 @@ void Fl_Browser_::display(void* p) {
if (lp) {
h1 = item_quick_height(lp);
Yp -= h1;
if (lp == p) {
if (lp == item) {
if ((Yp + h1) >= 0) position(real_position_+Yp);
else position(real_position_+Yp-(H-h1)/2);
return;
@ -304,7 +330,7 @@ void Fl_Browser_::display(void* p) {
l = top_;
for (; l; l = item_next(l)) {
h1 = item_quick_height(l);
if (l == p) {
if (l == item) {
if (Y <= H) { // it is visible or right at bottom
Y = Y+h1-H; // find where bottom edge is
if (Y > 0) position(real_position_+Y); // scroll down a bit
@ -321,7 +347,7 @@ void Fl_Browser_::display(void* p) {
for (; l; l = item_prev(l)) {
h1 = item_quick_height(l);
Y -= h1;
if (l == p) {
if (l == item) {
if ((Y + h1) >= 0) position(real_position_+Y);
else position(real_position_+Y-(H-h1)/2);
return;
@ -331,7 +357,6 @@ void Fl_Browser_::display(void* p) {
}
// redraw, has side effect of updating top and setting scrollbar:
/**
Draws the list within the normal widget bounding box.
*/
@ -490,6 +515,8 @@ J1:
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.
This method does not clear the list, it just handles the follow up
bookkeeping after the list has been cleared.
*/
void Fl_Browser_::new_list() {
top_ = 0;
@ -505,18 +532,20 @@ 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.
This method should be used when \p item is being deleted from the list.
It allows the Fl_Browser_ to discard any cached data it has on the item.
This method does not actually delete the item, but handles the follow up
bookkeeping after the item has just been deleted.
\param[in] item The item being deleted.
*/
void Fl_Browser_::deleting(void* l) {
if (displayed(l)) {
void Fl_Browser_::deleting(void* item) {
if (displayed(item)) {
redraw_lines();
if (l == top_) {
if (item == top_) {
real_position_ -= offset_;
offset_ = 0;
top_ = item_next(l);
if (!top_) top_ = item_prev(l);
top_ = item_next(item);
if (!top_) top_ = item_prev(item);
}
} else {
// we don't know where this item is, recalculate top...
@ -524,13 +553,18 @@ void Fl_Browser_::deleting(void* l) {
offset_ = 0;
top_ = 0;
}
if (l == selection_) selection_ = 0;
if (l == max_width_item) {max_width_item = 0; max_width = 0;}
if (item == selection_) selection_ = 0;
if (item == 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.
This method should be used when item \p a is being replaced by item \p b.
It allows the Fl_Browser_ to update its cache data as needed,
schedules a redraw for the item being changed, and tries to maintain the selection.
This method does not actually replace the item, but handles the follow up
bookkeeping after the item has just been replaced.
\param[in] a Item being replaced
\param[in] b Item to replace 'a'
*/
void Fl_Browser_::replacing(void* a, void* b) {
redraw_line(a);
@ -540,7 +574,12 @@ void Fl_Browser_::replacing(void* a, void* b) {
}
/**
Exchange pointers \p a and \p b.
This method should be used when two items \p a and \p b are being swapped.
It allows the Fl_Browser_ to update its cache data as needed,
schedules a redraw for the two items, and tries to maintain the current selection.
This method does not actually swap items, but handles the follow up
bookkeeping after items have been swapped.
\param[in] a,b Items being swapped.
*/
void Fl_Browser_::swapping(void* a, void* b) {
redraw_line(a);
@ -552,8 +591,14 @@ void Fl_Browser_::swapping(void* a, void* b) {
}
/**
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.
This method should be used when an item is in the process of
being inserted into the list.
It allows the Fl_Browser_ to update its cache data as needed,
scheduling a redraw for the affected lines.
This method does not actually insert items, but handles the
follow up bookkeeping after items have been inserted.
\param[in] a The starting item position
\param[in] b The new item being inserted
*/
void Fl_Browser_::inserting(void* a, void* b) {
if (displayed(a)) redraw_lines();
@ -561,52 +606,59 @@ void Fl_Browser_::inserting(void* a, void* b) {
}
/**
This method returns the item under mouse at my. If no item is
displayed at that position then NULL is returned.
This method returns the item under mouse y position \p ypos.
NULL is returned if no item is displayed at that position.
\param[in] ypos The y position (eg. Fl::event_y()) to find an item under.
\returns The item, or NULL if not found
*/
void* Fl_Browser_::find_item(int my) {
void* Fl_Browser_::find_item(int ypos) {
update_top();
int X, Y, W, H; bbox(X, Y, W, H);
void* l;
int yy = Y-offset_;
for (l = top_; l; l = item_next(l)) {
for (void *l = top_; l; l = item_next(l)) {
int hh = item_height(l); if (hh <= 0) continue;
yy += hh;
if (my <= yy || yy>=(Y+H)) return l;
if (ypos <= yy || yy>=(Y+H)) return l;
}
return 0;
}
/**
Sets the selection state of item p to s and
returns 1 if the state changed or 0 if it did not.
Sets the selection state of \p item to \p val,
and returns 1 if the state changed or 0 if it did not.
<P>If docb is non-zero, select tries to call the callback
function for the widget.
If \p docallbacks is non-zero, select tries to call
the callback function for the widget.
\param[in] item The item whose selection state is to be changed
\param[in] val The new selection state (1=select, 0=de-select)
\param[in] docallbacks If 1, invokes widget callback if item changed.\n
If 0, doesn't do callback (default).
\returns 1 if state was changed, 0 if not.
*/
int Fl_Browser_::select(void* l, int i, int docallbacks) {
int Fl_Browser_::select(void* item, int val, int docallbacks) {
if (type() == FL_MULTI_BROWSER) {
if (selection_ != l) {
if (selection_ != item) {
if (selection_) redraw_line(selection_);
selection_ = l;
redraw_line(l);
selection_ = item;
redraw_line(item);
}
if ((!i)==(!item_selected(l))) return 0;
item_select(l, i);
redraw_line(l);
if ((!val)==(!item_selected(item))) return 0;
item_select(item, val);
redraw_line(item);
} else {
if (i && selection_ == l) return 0;
if (!i && selection_ != l) return 0;
if (val && selection_ == item) return 0;
if (!val && selection_ != item) return 0;
if (selection_) {
item_select(selection_, 0);
redraw_line(selection_);
selection_ = 0;
}
if (i) {
item_select(l, 1);
selection_ = l;
redraw_line(l);
display(l);
if (val) {
item_select(item, 1);
selection_ = item;
redraw_line(item);
display(item);
}
}
if (docallbacks) {
@ -620,8 +672,11 @@ int Fl_Browser_::select(void* l, int i, int docallbacks) {
Deselects all items in the list and returns 1 if the state changed
or 0 if it did not.
<P>If docb is non-zero, deselect tries to call the
callback function for the widget.
If the optional \p docallbacks parameter is non-zero, deselect tries
to call the callback function for the widget.
\param[in] docallbacks If 1, invokes widget callback if item changed.\n
If 0, doesn't do callback (default).
*/
int Fl_Browser_::deselect(int docallbacks) {
if (type() == FL_MULTI_BROWSER) {
@ -639,24 +694,29 @@ 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.
<P>If docb is non-zero, select_only tries to call the
callback function for the widget.
Selects \p item and returns 1 if the state changed or 0 if it did not.
Any other items in the list are deselected.
\param[in] item The \p item to select.
\param[in] docallbacks If 1, invokes widget callback if item changed.\n
If 0, doesn't do callback (default).
*/
int Fl_Browser_::select_only(void* l, int docallbacks) {
if (!l) return deselect(docallbacks);
int Fl_Browser_::select_only(void* item, int docallbacks) {
if (!item) return deselect(docallbacks);
int change = 0;
if (type() == FL_MULTI_BROWSER) {
for (void* p = item_first(); p; p = item_next(p))
if (p != l) change |= select(p, 0, docallbacks);
if (p != item) change |= select(p, 0, docallbacks);
}
change |= select(l, 1, docallbacks);
display(l);
change |= select(item, 1, docallbacks);
display(item);
return change;
}
/** Handles an event within the normal widget bounding box. */
/**
Handles the \p event within the normal widget bounding box.
\param[in] event The event to process.
\returns 1 if event was processed, 0 if not.
*/
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;
@ -873,9 +933,13 @@ 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),
/**
The constructor makes an empty browser.
\param[in] X,Y,W,H position and size.
\param[in] L The label string, may be NULL.
*/
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()
hscrollbar(0, 0, 0, 0, 0)
{
@ -902,11 +966,20 @@ Fl_Browser_::Fl_Browser_(int X, int Y, int W, int H, const char* l)
end();
}
/*
* Simple bubble sort - pure lazyness on my side.
*/
/**
Sort the items in the browser based on \p flags.
item_swap(void*, void*) and item_text(void*) must be implemented for this call.
\param[in] flags FL_SORT_ASCENDING -- sort in ascending order\n
FL_SORT_DESCENDING -- sort in descending order\n
Values other than the above will cause undefined behavior\n
Other flags may appear in the future.
\todo Add a flag to ignore case
*/
void Fl_Browser_::sort(int flags) {
int i, j, n = -1, desc = ((flags&FL_SORT_DESC)==FL_SORT_DESC);
//
// Simple bubble sort - pure lazyness on my side.
//
int i, j, n = -1, desc = ((flags&FL_SORT_DESCENDING)==FL_SORT_DESCENDING);
void *a =item_first(), *b, *c;
if (!a) return;
while (a) {
@ -943,20 +1016,23 @@ void Fl_Browser_::sort(int flags) {
/**
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.
\p item, 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.
\param[in] item The item whose height to return.
\returns The height, in pixels.
*/
int Fl_Browser_::item_quick_height(void* l) const {
return item_height(l);
int Fl_Browser_::item_quick_height(void* item) const {
return item_height(item);
}
/**
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.
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.
\returns The average height of items, in pixels.
*/
int Fl_Browser_::incr_height() const {
return item_quick_height(item_first());
@ -964,8 +1040,10 @@ int Fl_Browser_::incr_height() const {
/**
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.
of the item list, in pixels.
The default implementation computes the full height from the item heights.
Includes the items that are scrolled off screen.
\returns The height of the entire list, in pixels.
*/
int Fl_Browser_::full_height() const {
int t = 0;
@ -976,26 +1054,32 @@ int Fl_Browser_::full_height() const {
/**
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.
of the item list, in pixels.
The default implementation computes the full width from the item widths.
\returns The maximum width of all the items, in pixels.
*/
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.
This method must be implemented by the subclass if it supports
multiple selections; sets the selection state to \p val for the \p item.
Sets the selection state for \p item, where optional \p val is 1 (select, the default)
or 0 (de-select).
\param[in] item The item to be selected
\param[in] val The optional selection state; 1=select, 0=de-select.\n
The default is to select the item (1).
*/
void Fl_Browser_::item_select(void*, int) {}
void Fl_Browser_::item_select(void *item, int val) {}
/**
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.
multiple selections; returns the selection state for \p item.
The method should return 1 if \p item is selected, or 0 otherwise.
\param[in] item The item to test.
*/
int Fl_Browser_::item_selected(void* l) const {return l==selection_;}
int Fl_Browser_::item_selected(void* item) const { return item==selection_ ? 1 : 0; }
//
// End of "$Id$".

2
test/browser.cxx
View File

@ -119,7 +119,7 @@ void swap_cb(Fl_Widget *, void *) {
}
void sort_cb(Fl_Widget *, void *) {
browser->sort(FL_SORT_ASC);
browser->sort(FL_SORT_ASCENDING);
}
int main(int argc, char **argv) {