/ 
FLTK-0.532008
River stage zero No dependents
/ FLTK::Browser

NAME

FLTK::Browser - Subclass of FLTK::Menu

Description

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:

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

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_NEVER

Callback is never done. changed() can be used to see if the user has modified the browser.

FLTK::WHEN_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.

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.

Functions

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

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.

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.

Example 1
@widths   = [ 100, 100, 100 ];

Make three columns, total width of columns is 300 pixels. Columns are resizable, but total width is kept always.

Example 2
@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.

Example 3
@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

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.

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

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

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

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

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

my $total = $browser->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

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.

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

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.

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

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

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.

Author

Sanko Robinson <sanko@cpan.org> - http://sankorobinson.com/

License and Legal

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.