Browser Class Reference

Inherits Menu.

Inherited by ComboBrowser, FileBrowser, and MultiBrowser.

List of all members.

Public Types

enum  { IS_MULTI, NORMAL, MULTI }
enum  { NO_COLUMN_SELECTED }
enum  linepos { NOSCROLL, TOP, MIDDLE, BOTTOM }

Public Member Functions

int handle (int)
void layout ()
void draw ()
 Browser (int X, int Y, int W, int H, const char *l=0)
 ~Browser ()
int width () const
int height () const
int box_width () const
int box_height () const
int xposition () const
void xposition (int)
int yposition () const
void yposition (int)
bool indented () const
void indented (bool v)
Widget * goto_top ()
Widget * goto_focus ()
Widget * goto_position (int y)
Widget * goto_index (const int *indexes, unsigned level)
Widget * goto_index (int)
Widget * goto_index (int, int, int=-1, int=-1, int=-1)
Widget * goto_mark (const Mark &)
Widget * next ()
Widget * next_visible ()
Widget * previous_visible ()
bool at_mark (const Mark &mark) const
int compare_to_mark (const Mark &mark) const
bool item_is_visible () const
bool item_is_parent () const
bool item_is_open () const
int item_h () const
bool set_focus ()
void set_mark (Mark &dest) const
void set_mark_to_focus (Mark &dest) const
bool set_item_selected (bool value=true, int do_callback=0)
bool select_only_this (int do_callback=0)
bool deselect (int do_callback=0)
bool make_item_visible (linepos=NOSCROLL)
void damage_item ()
void damage_item (const Mark &)
bool set_item_opened (bool)
bool set_item_visible (bool)
int current_level () const
const int * current_index () const
int current_position () const
int focus_level () const
const int * focus_index () const
int focus_position () const
const int * column_widths () const
void column_widths (const int *pWidths)
const char ** column_labels () const
void column_labels (const char **pLabels)
int selected_column ()
int set_column_start (int column, int x)
Widget * header (int col)
int nheader () const
void value (int v)
int value () const
bool select (int line, bool value=true)
bool selected (int line)
int topline () const
void topline (int line)
void bottomline (int line)
void middleline (int line)
bool displayed (int line)
bool display (int line, bool value=true)
int load (const char *filename)
int multi () const
const Symbol * leaf_symbol () const
void leaf_symbol (const Symbol *s)
const Symbol * group_symbol () const
void group_symbol (const Symbol *s)

Public Attributes

Scrollbar scrollbar
Scrollbar hscrollbar

Static Public Attributes

NamedStyle * default_style

Protected Member Functions

void handle_callback (int doit)

Detailed Description

Displays a scrolling vertical list of text widgets, possibly with a hierarchical arrangement, and lets the user select one of them.

browser.gif

The items may be created as child widgets (usually the same widgets as are used to create menus: Item widgets, or ItemGroup widgets to make a hierarchy).

All the functions used to add, remove, or modify items in the list are defined by the base class Menu. See that for much more information. For a simple constant list you can populate the list by calling browser->add("text of item") once for each item.

See also:
You can also us an List which allows you to control the storage by dynamically creating a temporary "fake" widget for the browser to use each time it wants to look at or draw an item. This is useful for creating browsers with hundreds of thousands of items, or when the set of items changes rapidly.

If you give the browser a callback you can find out what item was selected with value(), the first item is zero (this is different from older versions of fltk that started at 1!), and will be negative if no item is selected. You can change the selected item with value(new_value).

The subclass MultiBrowser lets the user select more than one item at the same time.

The callback() is done when the user changes the selected items or when they open/close parents. In addition, if the user double-clicks a non-parent item, then it is "executed" which usually means that the callback() on the item itself is run. However, if no callback has been set on the item, the callback() of this widget is called with the user_data() of the item.

You can control when callbacks are done with the when() method. The following values are useful, the default value is WHEN_CHANGED.

Member Enumeration Documentation

anonymous enum
 

Enumeration values:
NORMAL  means single selection can be achieved by user
MULTI  means multiple selection can be achieved by user

anonymous enum
 

Enumeration values:
NO_COLUMN_SELECTED  means that no column has been selected by user

enum Browser::linepos
 

Enumeration values:
NOSCROLL  move as little as possible so item is visible
TOP  position current item to top
MIDDLE  position current item to middle
BOTTOM  position current item to bottom

Constructor & Destructor Documentation

Browser::Browser (  int  X,
int  Y,
int  W,
int  H,
const char *  L = 0
) 
 

The constructor makes an empty browser.

Browser::~Browser (   ) 
 

The destructor deletes all the list items (because they are child Widgets of an Group) and destroys the browser.

Member Function Documentation

void Browser::bottomline (  int  line  )  [inline]
 

Convenience function for non-hierarchial browsers. Make the indexed item visible and scroll to put it at the bottom of the browser.

int Browser::box_height (   )  const [inline]
 

The height of the display area of the browser in pixels, this is h() minus the edges of the box() minus the height of the horizontal scrollbar, if visible. If this is changed (by resizing the widget, adding or deleting items or opening or closing a parent item such that the scrollbar visibility changes) then layout() must be called before this is correct.

int Browser::box_width (   )  const [inline]
 

The width of the display area of the browser in pixels, this is w() minus the edges of the box() minus the width of the vertical scrollbar, if visible. If this is changed (by resizing the widget, adding or deleting items or opening or closing a parent item such that the scrollbar visibility changes) then layout() must be called before this is correct.

void Browser::column_labels (  const char **  t  ) 
 

Set an array of labels to put at the top of the browser. The initial sizes of them are set with column_widths(). Items in the browser can print into the correct columns by putting '\t' characters into their text. Or they can look at column_widths() to find the settings from their draw() methods.

void Browser::column_widths (  const int *  t  ) 
 

Sets the horizontal locations that each '\t' character in an item should start printing text at. These are measured from the left edge of the browser, including any area for the open/close + glyphs.

  • Array must end with 0 (zero) always
  • You can define flexible column by setting column width to -1. If you have flexible column in browser, all columns are resized to match width of the browser, by resizing flexible column.
  // Example 1: make three columns, total width of columns is 300 pixels.
  // Columns are resizable, but total width is kept always.
  const int widths[]   = { 100, 100, 100, 0 };

  // Example 2: make three columns, total width of columns is always width of the browser.
  // Columns are resizable, third column is flexible and will take remaining space left.
  const int widths[]   = { 100, 100, -1, 0 };

const int * Browser::current_index (   )  const [inline]
 

Return an array of current_level()+1 indexes saying which child at each level includes the current item.

int Browser::current_level (   )  const [inline]
 

Return the nesting level of the current item (how many parents it has).

int Browser::current_position (   )  const [inline]
 

Return the y position, in pixels, of the top edge of the current item. You may also want the height, which is in item_h().

void Browser::damage_item (  const Mark &  mark  ) 
 

Set item referenced by this mark as being damaged.

void Browser::damage_item (   )  [inline]
 

Tell the browser to redraw the current item. Do this if you know it has changed appearance. This is better than redrawing the entire browser because it will blink a lot less.

bool Browser::deselect (  int  do_callback = 0  ) 
 

Turn off selection of all items in the browser. For the normal (not Multi) Browser, this puts it in a special state where nothing is highlighted and index(0) returns -1. The user cannot get it into this state with the GUI.

For a MultiBrowser the user can get this state by ctrl+clicking the selected items off.

If do_callback has some bits that are also in when() then the callback is done for each item that changes selected state.

bool Browser::display (  int  line,
bool  value = true
) 
 

Convenience function for non-hierarchial browsers. Make the indexed item be visible() and scroll the browser so it can be seen by the user.

bool Browser::displayed (  int  line  ) 
 

Convenience function for non-hierarchial browsers. Returns true if the indexed item is visible (ie not hidden).

const int * Browser::focus_index (   )  const [inline]
 

Return an array of focus_level()+1 indexes saying which child at each level includes the focus.

Reimplemented from Group.

int Browser::focus_level (   )  const [inline]
 

Return the nesting level of the focus (how many parents it has). The focus is the selected item the user sees.

int Browser::focus_position (   )  const [inline]
 

Return the y position, in pixels, of the top edge of the focus item. You may also want the height, which is in goto_focus(); item_h().

Widget * Browser::goto_focus (   )  [inline]
 

Sets the item() to the "focus" (the item with the dotted square in an MultiBrowser, and the selected item in a normal Browser.

Widget * Browser::goto_index (  int  a,
int  b,
int  c = -1,
int  d = -1,
int  e = -1
) 
 

Go to an item at any level up to 5. Negative numbers indicate that no more levels should be looked at.

Widget * Browser::goto_index (  int  i  ) 
 

Go to the i'th item in the top level. If i is out of range null is returned.

Widget * Browser::goto_index (  const int *  indexes,
unsigned  level
) 
 

Go to a nested item. indexes must contain level+1 index numbers. The first number indicates the top-level item number, the second indicates the child number of that parent, and so on. This sets the current item() to the given item and also returns it. If the values are out of range then null is returned.

A negative number in indexes[0] will make it go into a special no-item state where select_only_this() will do deselect().

Widget * Browser::goto_mark (  const Mark &  mark  ) 
 

set current item to a particular mark

Widget * Browser::goto_position (  int  Y  ) 
 

Set the current item() to the last one who's top is at or before Y pixels from the top.

Widget * Browser::goto_top (   ) 
 

Because of the hierarchial structure it is difficult to identify an item in the browser. Instead of passing an identifier to all the calls that can modify an item, the browser provides several calls to set item() based on various rules, and then calls to modify the current item().

This call sets item() to the very first visible widget in the browser. It returns the widget for that item, or null if the browser is empty.

If you have invisible items in the browser you should use goto_index(0) if you want to go to the first item even if it is invisible.

Browser::group_symbol (  const Symbol *  s  )  [inline]
 

Sets a default value for image() on each item that is a hierarchy parent. If the parent item has no image() then this one is used for it.

Widget * Browser::header (  int  col  )  [inline]
 

Return pointer to Widget in column col, starting from index 0. If column col is invalid, NULL is returned.

int Browser::height (   )  const [inline]
 

The height of all the visible items in the browser, measured in pixels. If this is changed (by adding or deleting items or opening or closing a parent item) then layout() must be called before this is correct.

void Browser::indented (  bool  v  )  [inline]
 

Turn this on to for space to be reserved for open/close boxes drawn to the left of top-level items. You usually want this for a hierarchial browser. This should be off for a flat browser, or to emulate Windows Explorer where "my computer" does not have an open/close to the left of it. The default value is false.

bool Browser::item_is_open (   )  const
 

If item_is_parent() is true, return true if this item is open. If this is not a parent the result is undefined.

bool Browser::item_is_parent (   )  const
 

Return true if the current item is a parent. Notice that it may have zero children.

bool Browser::item_is_visible (   )  const
 

Return true if the item would be visible to the user if the browser was scrolled to the correct location. This means that the INVISIBLE flag is not set on it, and all parents of it are open and visible as well.

Browser::leaf_symbol (  const Symbol *  s  )  [inline]
 

Sets a default value for image() on each item that is not a parent of other items. If the item has no image() then this one is used for it.

bool Browser::make_item_visible (  linepos  where = NOSCROLL  ) 
 

This makes the current item visible to the user.

First it turns off the INVISIBLE flag on the current item, and turns off the INVISIBLE flag and opens (turning on the STATE flag) all parent items. These flag changes cause flags_changed() to be called on any List that you have assigned to the browser.

The browser is then scrolled by calling yposition() so the item is visible. The optional argument tells how to scroll. If not specified (or the default value of Browser::NOSCROLL is given) then the browser is scrolled as little as possible to show the item. If it is Browser::TOP then the item is put at the top of the browser. If it is Browser::MIDDLE then the item is centered vertically in the browser. If it is Browser::BOTTOM then the item is put at the bottom of the browser.

This does nothing if the current item is null.

void Browser::middleline (  int  line  )  [inline]
 

Convenience function for non-hierarchial browsers. Make the indexed item visible and scroll to put it in the middle of the browser if it is not already visible (passes NO_SCROLL to make_item_visible().

Widget * Browser::next (   ) 
 

Move the current item to the next item. If if is a parent it moves to the first child. If not a parent, it moves to the next child of it's parent. If it is the last child it moves to the parent's brother. Repeatedly calling this will visit every child of the browser. This returns the widget. If the current widget is the last one this returns null, but the current widget remains on the last one.

The current_position() is NOT set by this! It cannot be calculated efficiently and would slow down the use of this function for visiting all items.

Widget * Browser::next_visible (   ) 
 

Move forward to the next visible item (what down-arrow does). This does not move and returns null if we are at the bottom.

int Browser::nheader (   )  const [inline]
 

Return number of columns in browser.

Widget * Browser::previous_visible (   ) 
 

Move backward to previous visible item: This does not move and returns null if we are at the top.

bool Browser::select (  int  line,
bool  value = true
) 
 

Same as goto_index(line),set_item_selected(value), to change the selected state of an item in a non-hierarchial MultiBrowser. If line is out of range nothing happens.

bool Browser::select_only_this (  int  do_callback = 0  ) 
 

Make the given item be the current one. For the MultiBrowser subclass this will turn off selection of all other items and turn it on for this one and also set the focus here. If the selection changes and when()&do_callback is non-zero, the callback is done.

For the multibrowser, the callback is done for each item that changes, whether it turns on or off.

bool Browser::selected (  int  line  ) 
 

Does goto_index(line),item_selected() to return the selection state of an item in a non-hierarchial MultiBrowser. If line is out of range it returns false.

int Browser::selected_column (   )  [inline]
 

It will call the callback() if the user clicks on a column title. Check this to see which one they clicked. This will return a negative number if the callback is being done for some other reason, such as the user clicking on an item.

bool Browser::set_focus (   ) 
 

Change the focus (the selected item, or in an MultiBrowser the item that has a dotted box around it, to the current item. This calls make_item_visible().

bool Browser::set_item_opened (  bool  open  ) 
 

If the current item is a parent, set the open state (the STATE flags) to the given value and redraw the browser correctly. Returns true if the state was actually changed, returns false if it was already in that state.

bool Browser::set_item_selected (  bool  value = true,
int  do_callback = 0
) 
 

This is for use by the MultiBrowser subclass. Turn the SELECTED flag on or off in the current item (use goto_index() to set the current item before calling this).

If this is not a MultiBrowser, this does select_only_this() if value is true, and deselect() if value is false.

If do_callback has some bits that are also in when() then the callback is done for each item that changes selected state.

bool Browser::set_item_visible (  bool  value  ) 
 

Turn off or on the INVISIBLE flag on the given item and redraw the browser if necessary. Returns true if the state was actually changed, returns false if it was already in that state.

void Browser::topline (  int  line  )  [inline]
 

Convenience function for non-hierarchial browsers. Make the indexed item visible and scroll to put it at the top of the browser.

int Browser::topline (   )  const [inline]
 

Convenience function for non-hierarchial browsers. Returns the index if the top-level item that is at the top of the scrolling window.

int Browser::value (   )  const [inline]
 

Returns focus_index(v)[0], to get the current item in a non-hierarchial browser.

Reimplemented from Menu.

void Browser::value (  int  v  )  [inline]
 

Same as goto_index(v);set_focus();, to change the current item in a non-hierarchial browser.

Reimplemented from Menu.

int Browser::width (   )  const [inline]
 

The width of the longest item in the browser, measured in pixels. If this is changed (by adding or deleting items or opening or closing a parent item) then layout() must be called before this is correct.

void Browser::xposition (  int  X  ) 
 

Set the horizontal scrolling position, measured in pixels. Zero is the normal position where the left edge of the child widgets is visible.

void Browser::yposition (  int  Y  ) 
 

Set the vertical scrolling position, measured in pixels. Zero means the top of the first item is visible. Positive numbers scroll the display up.

Member Data Documentation

NamedStyle * Browser::default_style [static]
 

This style mostly serves to set the parenting back to Widget::default_style to avoid the gray color and larger leading set by Menu::default_style. However it also sets it's own glyph() function to one that draws the [+] and [-] indicators.

Reimplemented from Menu.

The documentation for this class was generated from the following files:
Sun Jan 7 00:55:17 2007. FLTK ©2006 Bill Spitzak and others.
Permission is granted to reproduce this manual or any portion for any purpose, provided this copyright and permission notice are preserved.