FLTK::Browser - Subclass of FLTK::Menu
Displays a scrolling vertical list of text widgets, possibly with a hierarchical arrangement, and lets the user select one of them.
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 use 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.
FLTK::WHEN_NEVERCallback is never done.
changed() can be used to see if the user has modified the browser.
FLTK::WHEN_CHANGEDCallback is called on every change to each item as it happens.
The method item()) will return the one that is being changed.
Notice that selecting large numbers in a mulit browser will produce large numbers of callbacks.
FLTK::WHEN_RELEASECallback is done when the user releases the mouse after some changes, and on any keystroke that changes the item. For a multi browser you will only be able to find out all the changes by scanning all the items in the callback.
FLTK::WHEN_RELEASE_ALWAYSCallback is done when the user releases the mouse even if the current item has not changed, and on any arrow keystroke even when at the top or bottom of the browser.
FLTK::WHEN_ENTER_KEYIf you turn this on then the enter key is a shortcut and executes the current item like double-click.
BOTTOM BOTTOM( );Position current item to bottom
IS_MULTI IS_MULTI( );Means multiple selection can be achieved by user.
MIDDLE MIDDLE( );Position current item to middle
MULTI MULTI( );Means multiple selection can be achieved by user.
NORMAL NORMAL( );Means a single selection can be achieved by user.
NOSCROLL NOSCROLL( );Argument to make_item_visible().
Moves as little as possible so item is visible.
NO_COLUMN_SELECTED NO_COLUMN_SELECTED( );Means that no column has been selected by user.
TOP TOP( );Position current item to top
at_mark bottomline $browser->bottomline( $line );Convenience function for non-hierarchial browsers. Make the indexed item visible and scroll to put it at the bottom of the browser.
box_height my $h = $browser->box_height( );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.
box_width my $w = $browser->box_width( );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.
column_labels my @labels = $browser->column_labels( );Get the list of labels at the top of browser.
$browser->column_labels( $col1,
...,
$col );Set the list 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.
column_widths my @widths = $browser->column_widths( );$browser->column_widths( $col1,
...,
$col );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.
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.
Note that a zero (0) will terminate the list of columns.
@widths = [ 100, 100, 100 ];
Make three columns, total width of columns is 300 pixels. Columns are resizable, but total width is kept always.
@widths = [ 100, 100, -1 ];
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.
@widths = [ 250, 250, 0, 400 ];
Make two columns, total width of columns is 500 pixels. Columns are resizable, but total width is kept always.
compare_to_mark current_index my @indexes = $browser->current_index( );Return an array of current_level()+1 indexes saying which child at each level includes the current item.
current_level my $level = $browser->current_level( );Return the nesting level of the current item (how many parents it has).
current_position my $y = $browser->current_position( );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().
damage_item $browser->damage_item( $mark );Set item referenced by this mark as being damaged.
$browser->damage_item( );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.
default_style my $style = $browser->default_style( );Get the style
$browser->default_style( $style );Set the style.
deselect my $okay = $browser->deselect( $do_callback );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.
display my $visible = $browser->display( $line, $value );Convenience function for non-hierarchial browsers. Make the indexed item be visible() and scroll the browser so it can be seen by the user.
display_lines my $display = $browser->display_lines( );Accessor (get) method which returns a true value if lines should be displayed, or a false value otherwize.
$browser->display_lines( $display );Accessor (set) method which is used to set the value of the displaylines_ member. If you set display to a false value, it will mean that you do not want lines of the tree to be displayed.
displayed my $visible = $browser->displayed( $line );Convenience function for non-hierarchial browsers. Make the indexed item visible and scroll to put it at the bottom of the browser.
focus_index my @indexes = $browser->focus_index( );Return an array of focus_level()+1 indexes saying which child at each level includes the focus.
focus_level my $level = $browser->focus_level( );Return the nesting level of the focus (how many parents it has). The focus is the selected item the user sees.
focus_position my $y = $browser->focus_position( );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().
goto_focus my $focus = $browser->goto_focus( );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.
goto_index my $current = $browser->goto_index( $index, $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 undef 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().
my $current = $browser->goto_index( $index );Go to the index'th item in the top level. If index is out of range, undef is returned.
my $current = $browser->goto_index( $index, $level, $deep, $deeper, $deepest );Go to an item at any level up to 5. Negative numbers indicate that no more levels should be looked at.
goto_mark my $current = $browser->goto_mark( $mark );Set current item to a particular mark.
goto_position my $current = $browser->goto_position( $y );Set the current item() to the last one who's top is at or before Y pixels from the top.
goto_top my $top = $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.
group_symbol my $g_symbol = $browser->group_symbol( );Returns the 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.
$browser->group_symbol( $symbol );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.
header my $element = $browser->header( $column );Returns the Widget in column, starting from index 0. If column'th column is invalid, undef is returned.
height my $h = $browser->height( );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.
hscrollbar indented my $is_it = $browser->indented( );$browser->indented( $value );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.
item_h my $h = $browser->item_h( );The item height.
item_is_open my $is_open = $browser->item_is_open( );If item_is_parent() is true, return true if this item is open. If this is not a parent the result is undefined.
item_is_parent my $is_parent = $browser->item_is_parent( );Return true if the current item is a parent. Notice that it may have zero children.
item_is_visible my $is_visible = $browser->item_is_visible( );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.
layout leaf_symbol my $l_symbol = $browser->leaf_symbol( );Returns the 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->leaf_symbol( $symbol );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.
load make_item_visible my $okay = $browser->make_item_visible( $where );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::TOPFLTK::Browser 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 undef.
middleline $browser->middleline( $line );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().
multi new my $self = $browser->new( $x, $y, $w, $h, $label );Creates a new FLTK::Browser object.
next my $next = $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 undef, 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.
next_visible my $next = $browser->next_visible( );Move forward to the next visible item (what down-arrow does). This does not move and returns undef if we are at the bottom.
previous_visible my $prev = $browser->previous_visible( );Move backward to previous visible item: This does not move and returns undef if we are at the top.
scrollbar select my $okay = $browser->select( $widget, $value, $do_callback );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.
my $okay = $browser->select( $item, $value );Same as goto_index(item),set_item_selected(value), to change the selected state of an item in a non-hierarchial MultiBrowser. If item is out of range nothing happens.
Note: This is an FLTK 1.0 emulation method.
select_only_this my $okay = $browser->select_only_this( $do_callback );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.
selected my $selected = $browser->selected( $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.
Note: This is an FLTK 1.0 emulation method.
selected_column my $col = $browser->selected_column( );Returns the currently selected column.
set_column_start set_focus my $focused = $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().
set_item_opened my $okay = $browser->set_item_opened( $value );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.
set_item_selected my $okay = $browser->set_item_selected( $value, $do_callback );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 \a 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.
set_item_visible my $okay = $browser->set_item_visible( $value );Turn off or on the LFLTK::INVISIBLE|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.
set_mark set_mark_to_focus topline my $line = $browser->topline( );Convenience function for non-hierarchial browsers. Returns the index if the top-level item that is at the top of the scrolling window.
$browser->topline( $line );Convenience function for non-hierarchial browsers. Make the indexed item visible and scroll to put it at the top of the browser.
value $browser->value( $val );Same as goto_index(val);set_focus();, to change the current item in a non-hierarchial browser.
my $val = $browser->value( );Returns focus_index(val)[0], to get the current item in a non-hierarchial browser.
width my $w = $browser->width( );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.
xposition my $x = $browser->xposition( );$browser->xposition( $x );Set the horizontal scrolling position, measured in pixels. Zero is the normal position where the left edge of the child widgets is visible.
yposition my $y = $browser->yposition( );$browser->yposition( $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.
Sanko Robinson <sanko@cpan.org> - http://sankorobinson.com/
Copyright (C) 2008-2010 by Sanko Robinson <sanko@cpan.org>
This program is free software; you can redistribute it and/or modify it under the terms of The Artistic License 2.0. See the LICENSE file included with this distribution or notes on the Artistic License 2.0 for clarification.
When separated from the distribution, all original POD documentation is covered by the Creative Commons Attribution-Share Alike 3.0 License. See the clarification of the CCA-SA3.0.
