Documentation

  
  FLTK Apps      FLTK Library      Forums      Links     Login 
 Home  |  Articles & FAQs  |  Bugs & Features  |  Documentation  |  Download  ]
 

class Fl_Browser


Class Hierarchy

Include Files

    #include <FL/Fl_Browser.H>
    

Description

The Fl_Browser widget displays a scrolling list of text lines, and manages all the storage for the text. This is not a text editor or spreadsheet! But it is useful for showing a vertical list of named objects to the user.

Each line in the browser is identified by number. The numbers start at one (this is so that zero can be reserved for "no line" in the selective browsers). Unless otherwise noted, the methods do not check to see if the passed line number is in range and legal. It must always be greater than zero and <= size().

Each line contains a null-terminated string of text and a void * data pointer. The text string is displayed, the void * pointer can be used by the callbacks to reference the object the text describes.

The base class 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 class 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 subclass of Fl_Browser_.

Methods

Fl_Browser::Fl_Browser(int, int, int, int, const char * = 0)

The constructor makes an empty browser.

Fl_Browser::~Fl_Browser(void)

The destructor deletes all list items and destroys the browser.

void Fl_Browser::add(const char *, void * = 0)

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::bottomline(int n)

Scrolls the browser so the bottom line in the browser is n.

void Fl_Browser::clear()

Remove all the lines in the browser.

uchar Fl_Browser::column_char() const
void Fl_Browser::column_char(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().

const int *Fl_Browser::column_widths() const
void Fl_Browser::column_widths(const int *w)

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.

void *Fl_Browser::data(int n) const
void Fl_Browser::data(int n, void *)

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.

uchar Fl_Browser::format_char() const
void Fl_Browser::format_char(char c)

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:
  • @. Print rest of line, don't look for more '@' signs
  • @@ Print rest of line starting with '@'
  • @l Use a large (24 point) font
  • @m Use a medium large (18 point) font
  • @s Use a small (11 point) font
  • @b Use a bold font (adds FL_BOLD to font)
  • @i Use an italic font (adds FL_ITALIC to font)
  • @f or @t Use a fixed-pitch font (sets font to FL_COURIER)
  • @c Center the line horizontally
  • @r Right-justify the text
  • @B0, @B1, ... @B255 Fill the backgound with fl_color(n)
  • @C0, @C1, ... @C255 Use fl_color(n) to draw the text
  • @F0, @F1, ... Use fl_font(n) to draw the text
  • @S1, @S2, ... Use point size n to draw the text
  • @u or @_ Underline the text.
  • @- draw an engraved line through the middle.
Notice that the @. command can be used to reliably terminate the parsing. To print a random string in a random color, use sprintf("@C%d@.%s", color, string) and it will work even if the string starts with a digit or has the format character in it.

The second form sets the current prefix to c. Set the prefix to 0 to disable formatting.

void Fl_Browser::hide(int n)

Makes line n invisible, preventing selection by the user. The line can still be selected under program control.

void Fl_Browser::insert(int n, const char *, void * = 0)

Insert a new line before line n. If n > size() then the line is added to the end.

int Fl_Browser::load(const char *filename)

Clears the browser and reads the file, adding each line from the file to the browser. If the filename is NULL or a zero-length string then this just clears the browser. This returns zero if there was any error in opening or reading the file, in which case errno is set to the system error. The data() of each line is set to NULL.

void Fl_Browser::middleline(int n)

Scrolls the browser so the middle line in the browser is n.

void Fl_Browser::move(int to, int from)

Line from is removed and reinserted at to; to is calculated after the line is removed.

int Fl_Browser::position() const
void Fl_Browser::position(int p)

The first form returns the current vertical scrollbar position, where 0 corresponds to the top. If there is not vertical scrollbar then this will always return 0.

The second form sets the vertical scrollbar position to p.

void Fl_Browser::remove(int n)

Remove line n and make the browser one line shorter.

int Fl_Browser::selected(int n) const

Return 1 if line n is selected, 0 if it not selected.

void Fl_Browser::show(int n)

Makes line n visible for selection.

int Fl_Browser::size() const

Returns how many lines are in the browser. The last line number is equal to this.

void Fl_Browser::swap(int a, int b)

Swaps two lines in the browser.

const char *Fl_Browser::text(int n) const
void Fl_Browser::text(int n, const char *)

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.

int Fl_Browser::topline() const
void Fl_Browser::topline(int n)

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::visible(int n) const


User Comments [ Add Comment ]

From greg.ercolano, 04:47 Sep 22, 2006 (score=3)

One cool feature of Fl_Browser is the mysterious optional "data" argument to add() and insert().

This is apparently an optional pointer to *user defined data* (similar to 'user_data' for callbacks) so that you can assign user data to each line in the browser, which is /very/ cool.

This data follows the text around, even when lines are inserted or swapped.

I keep learning new stuff about Fl_Browser.. it's incredibly well designed and very well optimized and durable.


Reply ]

From greg.ercolano, 10:41 Aug 16, 2006 (score=3)

It should probably be added that the app can just make an instance of  Fl_Browser, and can set type() to one of these values to determine the browser's behavior:

    
    FL_NORMAL_BROWSER  -- browse only (no select)
                          [Same as Fl_Browser with default type()]
    
    FL_SELECT_BROWSER  -- single select, does not remain selected after mouse released
                          [Same as Fl_Select_Browser]
    
    FL_HOLD_BROWSER    -- single select, remains selected after mouse released
                          [Same as Fl_Hold_Browser]
    
    FL_MULTI_BROWSER   -- multi-select (with SHIFT and/or CTRL), remains selected after mouse release
                          [Same as Fl_Multi_Browser]
    

I think Fl_Browser_::type() should be documented with the above constants and descriptions.


Reply ]

From Anonymous, 14:41 Apr 17, 2006 (score=3)

The array of integers passed to column_widths is *not* locally copied, so make sure it doesn't go out of scope before the browser does (otherwise you'll get some very strange column widths...)
Reply ]

From Eivind Tagseth, 08:08 Mar 02, 2004 (score=1)

Fl_Browser overrides Fl_Browser_'s select with a version taking the line number (starting at 1) as parameter.
Reply ]

 
 

Comments are owned by the poster. All other content is copyright 1998-2015 by Bill Spitzak and others. This project is hosted by Seriss Corporation. Please report site problems to 'erco@seriss.com'.