NAME
Tk::ListBrowser - Tk::IconList inspired chameleon list box.
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 began as an inspiration on Tk::IconList. Nice, column oriented arrangement, but how about row oriented arrangement. And while we are at it, also list bar hlist and tree oriented arrangement. Scrollbars work automatically. Efforts have been made to follow the conventions of the Tk hierarchical list family as close as possible.
Screenshots: https://www.perlgui.org/all/tklistbrowser-screenshots/
This module features:
Arrange modes
Available arrange modes are 'bar', 'column', 'hlist', 'list' and 'tree'. You can switch between arrange modes through the -arrange option while retaining data.
The 'hlist' and 'tree' modes provide a hierarchical list interface. For it to work properly the -separator option must be set to a non empty string of one character.
Sorting
This module allows sorting your list on all kinds of paramenters, like sorting on column, ascending or descending. Furthemore you can choose sort fields like '-data', '-name', or '-text'.
Headers
Headers are shown in the 'hlist', 'list' and 'tree' modes. You can create and configure them in any mode. They are resizable and can be made sortable. You can drag headers left or right with your mouse to change the column ordering.
Side columns
Side columns are shown in the 'hlist', 'list' and tree modes. You can create and configure them in any mode.
Filtering
The keyboard shortcut CTFL+F opens a filter entry at the bottom of the widget. Filtering is case insensitive. The filter will start updating when -filterdelay milliseconds have past after your last keystroke. You can choose which data to filter with the -filterfield option. Filtering can be done on the main list as well as on the side columns.
OPTIONS
Tk::ListBrowser uses the following standard options: -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:
- 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.
- Switch -filtercolumns
-
By default false. If you set it a button will appear next to the filter entry that allows you to select a column.
- 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 -filterforce
-
Default value false. If set the filter entry will allways be visible.
- Switch -filteron
-
Default value main, which is the main entry list. You may also set it to a valid column.
- Name headerBorderWidth
- Class headerBorderWidth
- Switch -headerborderwidth
-
Default value 2.
- Name headerHeight
- Class HeaderHeight
- Switch -headerheight
-
Default value 32.
- Name headerRelief
- Class HeaderRelief
- Switch -headerrelief
-
Default value 'raised'.
- Switch -indicatorminusimg
-
Specifies the image of the minus indicator when -arrange is set to 'tree'. By default an internal image is loaded.
- Switch -indicatorplusimg
-
Specifies the image of the plus indicator when -arrange is set to 'tree'. By default an internal image is loaded.
- Name indent
- Class Indent
- Switch -indent
-
Default value 22. Specifies the indent with when -arrange is set to 'hlist' or 'tree'.
- Name itemPadX
- Class ItemPadX
- Switch -itempadx
-
Internal padding in x direction in entries and column items.
- Name itemPadY
- Class ItemPadY
- Switch -itempady
-
Internal padding in y direction in entries and column items.
- Switch -itemtype
-
Default value imagetext. Can be image, imagetext or text.
- Name marginBottom
- Class MarginBottom
- Switch -marginbottom
-
Default value 0. Expands the scrollable canvas size on the bottom.
- Name marginLeft
- Class MarginLeft
- Switch -marginleft
-
Default value 0. Expands the scrollable canvas size to the left.
- Name marginRight
- Class MarginRight
- Switch -marginright
-
Default value 0. Expands the scrollable canvas size to the right.
- Name marginTop
- Class MarginTop
- Switch -margintop
-
Default value 0. Expands the scrollable canvas size to the top.
- 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 -filterforce option.
- Switch -refreshentriespercycle
-
Default value 10. Specifies how many entries are refreshed during one refresh loop cycle.
- Switch -refreshinterval
-
Default value 1 milisecond. Specifies the interval between refresh loop cycles.
- 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 -selectstyle
-
Default value anchor. Can either be anchor or simple. This option specifies how the arrow keys work. When set to anchor, the arrow keys only move the anchor, space or enter will select. When set to simple the arrow keys also make a single mode selection.
- Switch -separator
-
Default value is an empty string. When set to one character, hierarchy mode is enabled. When -arrange is set to any other than 'hlist' or 'tree', only the root list is shown when hierarchy mode is enabled.
- Switch -sortbottom
-
Default value -(10**32). Used while sorting whenever a column item is found that requires numerical sort, but the item itself is not defined. A ridiculous low value is used instead. Are you handling even lower numbers? You can adjust it here.
- Switch -sortcase
-
Default value false. You can set it if you require case independent sort.
- Switch -sortfield
-
Default value '-name'. Possible values are '-name', '-text' and '-data'. Specifies which attribute of an entry is used for sorting.
- Switch -sortnumerical
-
Default value false. You can set it if you require numerical sorting.
- Switch -sorton
-
Default value is an empty string. That means sorting is done on the main entry list. You can set it to a column name for sorting on column content.
- Switch -sortorder
-
Default value 'ascending'.
- 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.
STANDARD OPTIONS
A number of the options above can also be used when you call the add, columnCreate, add and itemCreate methods. These are -background, -font, -foreground, -itempadx, -itempady, -itemtype, -textanchor, -textjustify, -textside, and -wraplength.
METHODS
- add(?$name?, %options)
-
Adds $name to the list with %options. $name must not yet exist. If you do not specify standard options, the main settings will be used. Besides the standard options you can also use:
- -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.
- -priority
-
Default priority is 0. Entries with the highest priorities are shown first.
- -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
- clear
-
Clears the display. Does not delete data.
- close($entry)
-
Hides all children of $entry. Call refresh or refreshPurge to see changes.
- closeAll
-
Closes all entries. Call refresh or refreshPurge to see changes.
- columnCapable
-
Returns true if -arrange is set to 'hlist', 'list' or 'tree'.
- columnCget($name, $option)
-
Returns the value of $option in column $name
- columnConfigure($name, %options)
-
Configures options in column $name.
- columnCreate($name, %options)
-
Creates a new side column object. Besides the standard options you can use the following:
- columnExists($name)
-
Returns true if column $name exists.
- columnGet($name)
-
Returns a reference to the Tk::ListBrowser::SideColumn object of $name.
- columnIndex($name)
-
Returns the place of column $name inf the viewing order. The first one has index 0.
- columnList
-
Returns the names all available columns.
- columnMove($column, $index)
-
Moves $column to $index.
- columnRemove($name)
-
Removes column $name and all its associated data.
- columnWidth($name, $width)
-
By default the main list and all side columns are sized so no information is lost and no unused space is created. The widths may vary when you add, remove or modify data. Once you make a call to this method the width of the column or main list becomes fixed. This works exactly as in Tk::HList.
Specify $name as an empty string for the main list. Otherwise specify a column name.
- delete(?$name?)
-
Deletes entry $name. Call refresh or refreshPurge to see your changes.
- deleteAll
-
Deletes all entries. Call refresh or refreshPurge 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.
- get(?$name?)
-
Returns a reference to the Tk::ListBrowser::Icon object of $name.
- getAll(?$name?)
-
Returns a list of all Tk::ListBrowser::Item objects.
- getChildren(?$parent?)
-
Returns a list of Tk::ListBrowser::Item objects that are children of $parent.
- getColumn($column)
-
Returns a reference to the Tk::ListBrowser::SideColumn object of column $column. Only practical when -arrange is set to 'column' or 'row'.
- getIndex($index)
-
Returns a reference to the Tk::ListBrowser::Item object at index $index.
- getRoot
-
Returns a list of Tk::ListBrowser::Entry objects that are root.
- getRow($row)
-
Returns a list of references to all Tk::ListBrowser::Icon objects in row $row. Only practical when -arrange is set to 'column' or 'row'.
- headerAvailable
-
Returns true if headers have been defined.
- headerCget($column, $option)
-
Returns the value of $option in header $name.
Specify $column as an empty string for the main list. Otherwise specify a column name.
- headerConfigure($column, $option, $value)
-
Configures options in header $name.
Specify $name as an empty string for the main list. Otherwise specify a column name.
- headerCreate($column, %options)
-
Creates a new header object. You can use the following options:
- -contextcall
-
Callback executed when you right click the header.
- -image
-
Image to display on the header. This option precedes the -text option.
- -sortable
-
Only available at create time. If set to true the list is sorted by clicking on the header. By default sorting is disabled.
- -text
-
Text to display on the header.
Specify $column as an empty string for the main list. Otherwise specify a column name.
- headerExists($column)
-
Returns true if column $name exists.
Specify $column as an empty string for the main list. Otherwise specify a column name.
- headerRemove($column)
-
Removes the header for column $column.
Specify $column as an empty string for the main list. Otherwise specify a column name.
- hide($name)
-
Hides entry $name. Call refresh or refreshPurge 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.
- infoChildren($parent)
-
Returns a list with the names of the children of $parent.
- 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, ?$flag?)>
-
The parameter $flag is only usefull in hierarchy mode. By default it is set to true. You can overwrite that by specifying it as false.
If $flag is set in hierarchy mode the next peer is returned, or undef if $name is the last peer amoung it's peers.
In non hierarchy mode it returns the name of the next entry of $name or 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.
- infoParent($name)
-
Returns the name of parent of $name. Returns undef if no parent is found.
- infoPev($name, ?$flag?)
-
The parameter $flag is only usefull in hierarchy mode. By default it is set to true. You can overwrite that by specifying it as false.
If $flag is set in hierarchy mode the previous peer is returned, or undef if $name is the first peer amoung it's peers.
In non hierarchy mode it returns the name of the previous entry of $name or 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.
- infoRoot
-
Returns a list of root entry names.
- infoSelection
-
Same as selectionGet.
- itemCget($name, $column, $option)
-
Returns the value of $option of item $name in column $column.
- itemConfigure($name, $column, %options)
-
Configures the options item of $name in column $column.
- itemCreate($name, $column, %options)
-
Creates a new item object for $name in column $column. You can use the standard options as well as:
- -data
-
Data to be assigned to this item item.
- -image
-
Image to display in the item.
- -text
-
Text to display in the item.
Once an item has been created there is no need to call refresh when you update it's text or image.
- itemExists($name, $column)
-
Returns true if item for $name in column $column has been created.
- itemGet($name, $column)
-
Returns a reference to the Tk::ListBrowser::Item object for $name in column $column.
- itemRemove($name, $column)
-
Removes the item for $name in column $column and it's data.
- lastColumnInRow($row)
-
Returns the number of the last column in $row.
- lastRowInColumn($column)
-
Returns the number of the last row in $column.
- open($name)
-
Shows all children of $name. Call refresh or refreshPurge to see your changes.
- openAll
-
Opens all entries.
- refresh
-
Clears the canvas and rebuilds it. Call this method after you are done making changes.
- refreshPurge(?$index?, ?$nosave?)
-
Same as refresh, but does not calculate cell sizes. Can be used after an initializing call to refresh has been made. If you specify $index the refresh is done from the entry at the index, going downward. It is operated in a background job cycle, so it is non blocking.
if the $nosave flag is set, the xview and yview of the canvas are not saved before the refresh starts.
- 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.
- sortList
-
Sorts the list and refreshes the display. Make a call to sortMode first to specify how to sort or configure the options -sorton and sortorder.
- sortMode($column, $order)
-
Specify on which column to sort with $column. $order can be 'ascending' or 'descending'. This method changes the options -sorton and -sortorder. It is called after a mouse click on a sortable header.
Specify $column as an empty string for the main list. Otherwise specify a column name.
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 navigation keys. 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.
CTRL+F pops a filter entry. Clicking CTRL+F again hides it. Filtering is done instantly upon entering text. This is influenced by the -filterforce 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
Not having to call refresh all the time would be nice.
BUGS AND CAVEATS
Setting a custom font greatly decreases the speed of refresh.
If you find any bugs, please report them here: https://github.com/haje61/Tk-ListBrowser/issues.