fltk::Browser Class Reference

Inherits fltk::Menu.

Inherited by fltk::ComboBrowser, fltk::FileBrowser, and fltk::MultiBrowser.

List of all members.

Public Types

enum  { IS_MULTI, NORMAL, MULTI }
enum  { NO_COLUMN_SELECTED }

Public Member Functions

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

Public Attributes

Scrollbar hscrollbar
Scrollbar scrollbar

Static Public Attributes

static NamedStyledefault_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: fltk::Item widgets, or fltk::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 fltk::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 fltk::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 fltk::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 fltk::WHEN_CHANGED.


Member Enumeration Documentation

anonymous enum

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

anonymous enum

Enumerator:
NO_COLUMN_SELECTED  means that no column has been selected by user

Enumerator:
NOSCROLL  Argument to make_item_visible().

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 
)

Browser::~Browser (  ) 

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


Member Function Documentation

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.

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.

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.

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.

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.

References fltk::DAMAGE_VALUE, fltk::Widget::redraw(), and fltk::Widget::relayout().

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.

References fltk::DAMAGE_VALUE, goto_position(), fltk::Widget::redraw(), and value().

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.

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.

References fltk::Menu::child(), fltk::Menu::children(), fltk::Menu::item(), and next_visible().

Referenced by goto_position(), select(), and select_only_this().

Widget * Browser::goto_focus (  )  [inline]

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

References fltk::FOCUS.

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.

References goto_mark(), goto_top(), fltk::Menu::item(), fltk::Widget::layout_damage(), next_visible(), and previous_visible().

Referenced by yposition().

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().

References fltk::Menu::child(), fltk::Menu::children(), goto_mark(), fltk::Menu::item(), fltk::Widget::layout_damage(), next_visible(), and previous_visible().

Referenced by display(), displayed(), goto_index(), select(), and selected().

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.

References goto_index().

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.

References goto_index().

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

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.

References fltk::Menu::child(), fltk::Menu::children(), and fltk::Menu::item().

Referenced by select_only_this().

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.

References fltk::Menu::child(), fltk::Menu::children(), fltk::Menu::item(), item_is_open(), item_is_parent(), and item_is_visible().

Referenced by goto_index(), goto_position(), goto_top(), select(), and select_only_this().

Widget * Browser::previous_visible (  ) 

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

References fltk::Menu::child(), fltk::Menu::children(), fltk::Menu::item(), item_is_open(), and item_is_parent().

Referenced by goto_index(), and goto_position().

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 fltk::INVISIBLE flag is not set on it, and all parents of it are open and visible as well.

References fltk::Menu::item(), and fltk::Widget::visible().

Referenced by next_visible().

bool Browser::item_is_parent (  )  const

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

References fltk::Menu::children().

Referenced by next_visible(), previous_visible(), and set_item_opened().

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.

References fltk::Widget::flag(), fltk::Menu::item(), and fltk::OPENED.

Referenced by next_visible(), previous_visible(), and set_item_opened().

bool Browser::set_focus (  ) 

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

References fltk::Widget::contains(), damage_item(), fltk::focus(), fltk::Menu::item(), make_item_visible(), and fltk::Widget::take_focus().

Referenced by select_only_this().

bool Browser::select ( Widget e,
int  v,
int  do_callback = 0 
)

This is for use by the MultiBrowser subclass. select or deselect an item in parameter, optionally execute a callback (calls set_item_selected()). This method changes item position in the tree.

References goto_top(), fltk::Menu::item(), next_visible(), and set_item_selected().

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

This is for use by the MultiBrowser subclass. Turn the fltk::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.

References fltk::Widget::clear_selected(), damage_item(), deselect(), fltk::Widget::do_callback(), fltk::List::flags_changed(), goto_mark(), fltk::Menu::item(), select_only_this(), selected(), and fltk::Widget::set_selected().

Referenced by select(), and select_only_this().

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.

References fltk::Widget::do_callback(), goto_mark(), goto_top(), next(), next_visible(), set_focus(), and set_item_selected().

Referenced by deselect(), and set_item_selected().

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.

References fltk::Menu::item(), and select_only_this().

Referenced by set_item_selected().

bool Browser::make_item_visible ( linepos  where = NOSCROLL  ) 

This makes the current item visible to the user.

First it turns off the fltk::INVISIBLE flag on the current item, and turns off the fltk::INVISIBLE flag and opens (turning on the fltk::STATE flag) all parent items. These flag changes cause flags_changed() to be called on any fltk::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 fltk::Browser::NOSCROLL is given) then the browser is scrolled as little as possible to show the item. If it is fltk::Browser::TOP then the item is put at the top of the browser. If it is fltk::Browser::MIDDLE then the item is centered vertically in the browser. If it is fltk::Browser::BOTTOM then the item is put at the bottom of the browser.

This does nothing if the current item is null.

References BOTTOM, fltk::Menu::child(), fltk::Menu::children(), fltk::List::flags_changed(), goto_mark(), fltk::Rectangle::h(), fltk::Menu::item(), fltk::LAYOUT_CHILD, fltk::Widget::layout_damage(), MIDDLE, fltk::OPENED, fltk::Widget::relayout(), fltk::Widget::set_flag(), set_item_visible(), fltk::Widget::set_visible(), and TOP.

Referenced by set_focus().

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.

References damage_item().

Referenced by damage_item(), set_focus(), and set_item_selected().

void Browser::damage_item ( const Mark &  mark  ) 

Set item referenced by this mark as being damaged.

References fltk::DAMAGE_CONTENTS, fltk::DAMAGE_VALUE, and fltk::Widget::redraw().

bool Browser::set_item_opened ( bool  open  ) 

If the current item is a parent, set the open state (the fltk::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.

References fltk::Widget::clear_flag(), fltk::List::flags_changed(), fltk::Menu::item(), item_is_open(), item_is_parent(), fltk::LAYOUT_CHILD, fltk::OPENED, fltk::Widget::relayout(), and fltk::Widget::set_flag().

bool Browser::set_item_visible ( bool  value  ) 

Turn off or on the fltk::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.

References fltk::Widget::clear_flag(), fltk::List::flags_changed(), fltk::INVISIBLE, fltk::Menu::item(), fltk::LAYOUT_CHILD, fltk::Widget::relayout(), and fltk::Widget::set_flag().

Referenced by display(), and make_item_visible().

int Browser::current_level (  )  const [inline]

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

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_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().

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.

References fltk::FOCUS.

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 fltk::Group.

References fltk::FOCUS.

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().

References fltk::FOCUS.

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 };

References fltk::Widget::redraw(), and fltk::Widget::relayout().

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 fltk::column_widths() to find the settings from their draw() methods.

References fltk::Widget::callback(), fltk::Group::current(), and fltk::Widget::parent().

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.

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::nheader (  )  const [inline]

Return number of columns in browser.

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 fltk::Menu.

int Browser::value (  )  const [inline]

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

Reimplemented from fltk::Menu.

References fltk::FOCUS.

Referenced by yposition().

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.

References goto_index(), and set_item_selected().

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.

References goto_index(), fltk::Menu::item(), and fltk::Widget::selected().

Referenced by set_item_selected().

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.

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.

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.

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().

bool Browser::displayed ( int  line  ) 

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

References goto_index(), fltk::Menu::item(), and fltk::Widget::visible().

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.

References goto_index(), and set_item_visible().

bool Browser::display_lines (  )  const

Accessor (get) method which returns TRUE if lines should be displayed, or FALSE otwherwize.

void Browser::display_lines ( bool  display  ) 

Accessor (set) method which is used to set the value of the "displaylines_" member. If you set display to FALSE it will mean that you do not want lines of the tree to be displayed.

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.

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.


Member Data Documentation

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 fltk::Menu.

Referenced by Browser().


Wed Jun 17 08:58:18 2009. FLTK ©2007 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.