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.
browser-
See also:
add()
add_group()
add_leaf()
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).
value()
1
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.
callback()
user_data()
You can control when callbacks are done with the when() method. The following values are useful, the default value is FLTK::WHEN_CHANGED.
when()
FLTK::WHEN_CHANGED
FLTK::WHEN_NEVER
Callback is never done. changed() can be used to see if the user has modified the browser.
changed()
Callback 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.
item()
FLTK::WHEN_RELEASE
Callback 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_ALWAYS
Callback 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_KEY
If 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( );
NORMAL
NORMAL( );
Means a single selection can be achieved by user.
NOSCROLL
NOSCROLL( );
Argument to make_item_visible().
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
my $position = $browser->at_mark( $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.
h()
box()
layout()
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.
w()
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()
\t
FLTK::column_widths()
draw()
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.
'\t'
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.
0
@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
my $difference = $browser->compare_to_mark( $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()+1
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().
y
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.
index(0)
-1
For a MultiBrowser the user can get this state by ctrl+clicking the selected items off.
ctrl+click
If do_callback has some bits that are also in when() then the callback is done for each item that changes selected state.
do_callback
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.
visible()
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.
displaylines_
displayed
my $visible = $browser->displayed( $line );
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()
+1
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()
;
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.
level+1
undef
A negative number in indexes[0] will make it go into a special no-item state where select_only_this() will do deselect().
indexes[0]
select_only_this()
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.
index
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.
Y
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.
goto_index(0)
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.
image()
$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.
column
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
my $h_sb = $browser->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()
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.
FLTK::INVISIBLE
layout
$browser->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
my $total = $browser->load( $filename );
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.
FLTK::STATE
flags_changed()
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.
yposition()
FLTK::Browser::TOP
FLTK::Browser::MIDDLE
FLTK::Browser::BOTTOM
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().
NO_SCROLL
multi
my $total = $browser->multi( );
new
my $self = $browser->new( $x, $y, $w, $h, $label );
Creates a new FLTK::Browser object.
FLTK::Browser
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.
current_position()
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
my $v_sb = $browser->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.
set_item_selected()
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.
item
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.
when()&do_callback
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.
goto_index(line),item_selected()
line
selected_column
my $col = $browser->selected_column( );
Returns the currently selected column.
set_column_start
my $column = $browser->set_column_start( $column, $x );
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.
true
false
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).
FLTK::SELECTED
goto_index()
If this is not a MultiBrowser, this does select_only_this() if value is true, and deselect() if \a value is false.
value
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
$browser->set_mark( $destination );
set_mark_to_focus
$browser->set_mark_to_focus( $destination );
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.
$browser->value( $val );
Same as goto_index(val);set_focus();, to change the current item in a non-hierarchial browser.
goto_index(val);set_focus();
my $val = $browser->value( );
Returns focus_index(val)[0], to get the current item in a non-hierarchial browser.
focus_index(val)[0]
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.
To install FLTK, copy and paste the appropriate command in to your terminal.
cpanm
cpanm FLTK
CPAN shell
perl -MCPAN -e shell install FLTK
For more information on module installation, please visit the detailed CPAN module installation guide.