NAME
Tk::ListBrowser - Tk::IconList like mega widget.
SYNOPSIS
require Tk::ListBrowser;
my $ib= $window->ListBrowser(@options)->pack;
$ib->add('item_1', -image => $image1, -text => $text1);
$ib->add('item_2', -image => $image2, -text => $text2);
$ib->refresh;DESCRIPTION
Tk::ListBrowser is inspired on Tk::IconList but with added features like row as well as column, list and bar oriented display. There are plenty of options to set the presentation of text items.
Scrollbars are automatically shown when needed.
Screenshots: https://github.com/haje61/Tk-ListBrowser/tree/main/screenshots
OPTIONS
Tk::ListBrowser uses the following standardoptions: -background, -font, -foreground, -selectbackground, -selectforeground. In addition the following options are supported.
- Switch -arrange
-
Default value row. This option specifies the layout of your list. If you change this option on the fly you have to call refresh to see the changes. You can set the following values:
- bar
-
Presents a one row, horizontal list.
- column
-
Presents a column centered two dimensional list.
- list
-
Presents a one column vertical list.
- row
-
Presents a row centered two dimensional list.
- Switch -browsecmd
-
Callback, called when an is selected. Gets the selection list as parameters.
- Switch -command
-
Callback, called when an entry is double clicked or return was pressed. Gets the selection list as parameters.
- Name filterDelay
- Class FilterDelay
- Switch -filterdelay
-
Default value 300 miliseconds. When the filter bar is active this is the wait time between a keystroke and a corresponding filter action. If a key is pressed before time out, the timer is reset.
- Switch -filterfield
-
Default value name. Possible values are name, text and data. Specifies on what data the filter should work.
- Switch -filteron
-
Default value false. If set the filter entry will allways be visible.
- Switch -itemtype
-
Default value imagetext. Can be image, imagetext or text.
- Switch -motionselect
-
Default value false. Only works when -selectmode is set to single. Automatically selects an entry when the pointer is hovering over it.
- Switch -nofilter
-
Default value false. If set the filter entry is not available. This option supercedes the -filteron option.
Only available at create time.
- Switch -selectmode
-
Default value single. Can either be single or multiple. In single mode only one entry in the list can be selected at all times. In multiple mode more than one entry can be selected.
- Switch -textanchor
-
Default value empty string. This value centers the text in it's cativy. Besides an empty string the possible values are n, ne, nw, s, se, sw, e and w. The letters stand for the first letter of the wind directions. They tell where to position the text in it's cavity.
- Switch -textjustify
-
Default value center. Can be center, left or right. Specifies how multiline or wrapped text is justified.
- Switch -textside
-
Default value bottom. Possible values are bottom, top, left, right, or none. It sets at which side the text should appear next to the icon. If you change this option on the fly you have to call refresh to see the changes. This option only has meaning when -itemtype is set to 'imagetext'.
- Switch -wraplength
-
Default value 0. You can set it to a positive integer of at least 40 to invoke word or character wrapping. The value determines the maximum width in pixels of a text block. It will attempt a word wrap and will do a character wrap if that fails.
If you change this option on the fly you have to call refresh to see the changes.
If you try to set it to a lower value than 40, you will be overruled. This is to prevent the wrap length to become smaller that the with of one character, which would freeze you application. This also means watching out for using very big fonts.
METHODS
- add(?$name?, %options)
-
Adds $name to the list with %options. $name must not yet exist. Possible options are:
- -after
-
Insert $name after the entry name held by this option.
- -before
-
Insert $name before the entry name held by this option.
- -data
-
Assign an arbitray scalar value to this entry.
-
Tag the entry as hidden. If you do not specify this option the entry is shown after refresh
- -image
-
A valid Tk::Image class assigned to this entry.
- -text
-
Text assigned to this entry.
After a call to add you must call refresh to see your changes. Returns a reference to the created item object.
- anchorClear
-
Clears the keyboard anchor.
- anchorGet
-
Returns a reference to the Tk::ImageBrowser::Icon object that currently holds the anchor.
- anchorSet($name)
-
Sets the keyboard anchor to $name
- anchorSetColumnRow($column, $row)
-
Sets the anchor in $column and $row
- canvasSize
-
Returns the available width and height of the Danvas widget.
- clear
-
Clears the canvas.
- delete(?$name?)
-
Deletes entry $name. You must call refresh to see your changes.
- deleteAll
-
Deletes all entries. You must call refresh to see your changes.
- entryCget($name, $option)
-
Returns the value of $option held by $name. Valid options are -data, -hidden, -image and -text.
- entryConfigure($name, %options)
-
Sets the value of %options held by $name. Valid options are -data, -hidden, -image and -text. You can specify multiple options.
- filterFlip
-
Hides the filter bar if it is shown. Shows it if it is hidden.
- get(?$name?)
-
Returns a reference to the Tk::ListBrowser::Icon object of $name.
- get(?$name?)
-
Returns a list of all Tk::ListBrowser::Icon objects.
- getColumn($column)
-
Returns a list of referencec to all Tk::ListBrowser::Icon objects in column $column.
- getIndex($index)
-
Returns a reference to the Tk::ListBrowser::Icon object at index $index
- getRow($row)
-
Returns a list of referencec to all Tk::ListBrowser::Icon objects in row $row.
- hide($name)
-
Hides entry $name. Call refresh to see changes.
- index
-
Returns the numerical index of entry $name.
- indexColumnRow($column, $row)
-
Returns the numerical index of the entry at $column, $row.
- indexLast
-
Returns the numerical index of the last entry in the list.
- infoAnchor
-
Returns the name of the entry that holds the anchor. Returns undef if the anchor is not held.
- infoData($name)
-
Returns the data associated with entry $name
- infoExists($name)
-
Returns a boolean value indicating if entry $name exists.
- infoFirst
-
Returns the name of the first entry in the list.
- infoFirstVisible
-
Returns the name of the first entry in the list that is not hidden.
- infoHidden($name)
-
Returns the boolean hidden state of entry $name.
- infoLast
-
Returns the name of the last entry in the list.
- infoLastVisible
-
Returns the name of the last entry in the list that is not hidden.
- infoList
-
Returns a list of all entry names in the list.
- infoNext($name)
-
Returns the name of the next entry of $name. Returns undef if $name is the last entry in the list.
- infoNextVisible($name)
-
Returns the name of the first next entry of $name that is not hidden. Returns undef if $name is the last entry in the list.
- infoPev($name)
-
Returns the name of the previous entry of $name. Returns undef if $name is the first entry in the list.
- infoPrevVisible($name)
-
Returns the name of the first previous entry of $name that is not hidden. Returns undef if $name is the first entry in the list.
- infoSelection
-
Same as selectionGet.
- lastColumnInRow($row)
-
Returns the number of the last column in $row.
- lastRowInColumn($column)
-
Returns the number of the last row in $column.
- refresh
-
Clears the canvas and rebuilds it. Call this method after you are done making changes.
- see($name)
-
Scrolls the canvas to make $name visible if it is not, or not completely, visible.
- selectAll
-
Selects all entries.
- selectionClear
-
Clears the entire selection.
- selectionGet
-
Returns a list of entry names contained in the selection.
- selectionSet($begin, ?$end?)
-
Selects entry $begin. If you specify $end the range from $begin to $end will be selected.
- selectionUnSet($begin, $end)
-
Clears the selection of entry $begin. If you specify $end the range from $begin to $end will be cleared from the selection.
- show($name)
-
Shows entry $name. Call refresh to see changes.
- textFormat($text)
-
Formats, basically wraps, $text taking the option -wraplength into account. $text can be a multi line string.
- textHeight($text)
-
Returns the display height of $text in pixels. $text can be a multi line string.
- textWidth($text)
-
Returns the display width of $text in pixels. $text can be a multi line string.
USING THE KEYBOARD
Before you can manipulate the list using the keyboard, the anchor must be initialized first. You do that by pressing any of the keys below. After that you can start navigating and manipulate selections.
The spacebar selects or deselects the entry that is currently held by the anchor. The -browsecmd callback is called if the entry is selected.
The return key selects the entry and invokes the -command callback.
You can navigate the list using the arrow keys and the the Home, Control-Home, End and Control-End keys. Holding shift while pressing these keys manipulates the selection.
The escape key clears the selection and anchor or hides the filter entry if it is visible.
Control-f pops a filter entry. Clicking Control-f again hides it. Filtering is done instantly upon entering text in. This is influenced by the -filteron and -nofilter options.
USING THE MOUSE
Clicking an entry with the left button selects it and assigns the anchor to it. Shift-click manipulates the selection of the range from the entry that holds the anchor to the one you click. Control-click selects or deselects the entry.
You can drag-scroll the list by moving you mouse while holding the middle button pressed.
LICENSE
Same as Perl.
AUTHOR
Hans Jeuken (hanje at cpan dot org)
TODO
Work out Tk::ListBrowser::Hlist and Tk::ListBrowser::Tree addons. Add side columns. Add headers.
BUGS AND CAVEATS
If you find any bugs, please report them here: https://github.com/haje61/Tk-ListBrowser/issues.