Fl_Browser_

## class Fl_Browser_

### Class Hierarchy

    Fl_Group
       |
       +----Fl_Browser_
               |
               +----Fl_Browser, Fl_Check_Browser

### Include Files

    #include <FL/Fl_Browser_.H>

### Description

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.

This has been designed so that the subclass has 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.

### Methods

Fl_Browser_ ~Fl_Browser_ bbox deleting deselect display displayed draw find_item | full_height full_width handle has_scrollbar hposition incr_height inserting item_draw | item_first item_height item_next item_prev item_quick_height item_select item_selected item_width | leftedge new_list position redraw_line redraw_lines replacing resize scrollbar_left | scrollbar_right scrollbar_width select select_only selection textcolor textfont textsize top

#### 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.

#### Fl_Browser_::bbox(int &x, int &y, int &w, int &h) const

`[protected]` This method returns the bounding box for the interior of the list, inside the scrollbars.

#### Fl_Browser_::deleting(void *a)

`[protected]` 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.

#### int Fl_Browser_::deselect(int docb=0)

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.

#### Fl_Browser_::display(void *p)

Displays item `p`, scrolling the list as necessary.

#### int Fl_Browser_::displayed(void *p) const

`[protected]` This method returns non-zero if item `p` is currently visible in the list.

#### Fl_Browser_::draw()
Fl_Browser_::draw(int x, int y, int w, int h)

`[protected]` The first form draws the list within the normal widget bounding box.

`[protected]` The second form draws the contents of the browser within the specified bounding box.

#### void *Fl_Browser_::find_item(int my)

This method returns the item under mouse at `my`. If no item is displayed at that position then `NULL` is returned.

#### virtual int Fl_Browser_::full_height() const

`[protected]` 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.

#### Fl_Browser_::full_width() const

`[protected]` 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.

#### Fl_Browser_::handle(int event)
Fl_Browser_::handle(int event, int x, int y, int w, int h)

The first form handles an event within the normal widget bounding box.

`[protected]` The second form handles an event within the specified bounding box.

#### void Fl_Browser_::has_scrollbar(int h)

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`:

- `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.

#### int Fl_Browser_::hposition() const
Fl_Browser_::hposition(int h)

Gets or sets the horizontal scrolling position of the list, which is the pixel offset of the list items within the list area.

#### virtual int Fl_Browser_::incr_height() const

`[protected]` 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.

#### Fl_Browser_::inserting(void *a, void *b)

`[protected]` 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.

#### virtual void Fl_Browser_::item_draw(void *p, int x, int y, int w, int h)

`[protected]` 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 *Fl_Browser_::item_first() const

`[protected]` This method must be provided by the subclass to return the first item in the list.

#### virtual int Fl_Browser_::item_height(void *p) const

`[protected]` 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 void *Fl_Browser_::item_next(void *p) const

`[protected]` This method must be provided by the subclass to return the item in the list after `p`.

#### virtual void *Fl_Browser_::item_prev(void *p) const

`[protected]` This method must be provided by the subclass to return the item in the list before `p`.

#### virtual int Fl_Browser_::item_quick_height(void *p) const

`[protected]` 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`.

#### virtual void Fl_Browser_::item_select(void *p, int s=1)

`[protected]` 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.

#### virtual int Fl_Browser_::item_selected(void *p) const

`[protected]` 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.

#### virtual int Fl_Browser_::item_width(void *p) const

`[protected]` 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.

#### int Fl_Browser_::leftedge() const

`[protected]` This method returns the X position of the left edge of the list area after adjusting for the scrollbar and border, if any.

#### Fl_Browser_::new_list()

`[protected]` 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.

#### int Fl_Browser_::position() const
Fl_Browser_::position(int v) const

Gets or sets the vertical scrolling position of the list, which is the pixel offset of the list items within the list area.

#### Fl_Browser_::redraw_line(void *p)

`[protected]` This method should be called when the contents of an item have changed but not changed the height of the item.

#### Fl_Browser_::redraw_lines()

`[protected]` This method will cause the entire list to be redrawn.

#### Fl_Browser_::replacing(void *a, void *b)

`[protected]` 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.

#### Fl_Browser_::resize(int x, int y, int w, int h)

Repositions and/or resizes the browser.

#### Fl_Browser_::scrollbar_left()

This method moves the vertical scrollbar to the lefthand side of the list.

#### Fl_Browser_::scrollbar_right()

This method moves the vertical scrollbar to the righthand side of the list.

#### static void Fl_Browser_::scrollbar_width(int sw);
static int Fl_Browser_::scrollbar_width() const;

Sets or gets the width of any scrollbars that are used.

#### int Fl_Browser_::select(void *p, int s=1, int docb=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.

#### Fl_Browser_::select_only(void *p, int docb=0)

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.

#### void *Fl_Browser_::selection() const

`[protected]` 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.

#### Fl_Color Fl_Browser_::textcolor() const
void Fl_Browser_::textcolor(Fl_Color color)

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_Font Fl_Browser_::textfont() const
void Fl_Browser_::textfont(Fl_Font font)

The first form gets the default text font for the lines in the browser.

The second form sets the default text font to `font`

#### uchar Fl_Browser_::textsize() const
void Fl_Browser_::textsize(uchar size)

The first form gets the default text size for the lines in the browser.

The second form sets the default text size to `size`

#### void *Fl_Browser_::top() const

`[protected]` Returns the item the appears at the top of the list.