Tk::MListbox - Multi-column Listbox

# Tk::MListbox | Package Info
Tutorial | FAQ | Changes/Bug fixes |
Version: | 1.11
DSLIP: | bdpOp
Author: | Hans J. Helgesen
Maintainer: | Rob Seegel
Package:
| MListbox
Platforms: | Linux Unix Windows

- Synopsis
- Heirarchy
- Description
- Components
- Options

- MListbox-defined
- Inherited from Frame

- Methods

- Column Indices
- Row Indices

- Keyboard bindings

## Synopsis

    use Tk::MListbox;
    ...
    my $ml = $parent->MListbox(?options, ...?)

Creates and returns a MListbox widget. The appearance and behavior of the widget can be configured by passing one or more options, described in more detail below.

## Heirarchy

Widget // Frame // MListbox

## Description

Tk::MListbox is a composite widget used to display and manipulate tabular data. It can display one or more columns that can each be resized, sorted, or moved. The name MListbox is short for Multi-Listbox, since it is composed of one or more Listbox widgets (one per column) and shares many of the same methods with Listbox.

MListbox handles tasks that can also be accomplished using the HList, TixGrid, or Table widgets from the main Tk Distribution. Columns and TableMatrix (available on CPAN) are other common alternatives.

MListbox distinguishes itself from the others by providing commonly used features associated with tabular display widgets. Among them is the ability to change the order of columns using drag and drop, and the ability to hide or show individual columns. These two features are not currently supported by any of the previously mentioned widgets.

For more detailed information on using this widget, refer to the MListbox tutorial.

## Components

MListbox is a collection of MLColumn widgets, packed into a Pane. These widgets are internal to MListbox and not meant to be used outside of it. Although these subwidgets are not advertised, it is possible to access them using the columnGet() method. The columnInsert() method also returns a reference to a MLColumn widget after creating and inserting it.

Aside from the columns, MListbox has one advertised subwidget.

Subwidgets:
Name: | pane
Class: | Pane
| This is the container that holds all MListbox columns (for horizontal scrolling).

## Options

At creation time, all MListbox-defined options except for -columns, -configurecommand, -moveable, -width, -xscrollcommand, and -yscrollcommand serve as default options for each column that is created. Any options set for individual columns using the -columns option will override the defaults. These options, when reconfigured after widget creation, will override the values for all columns.

MListbox defined:
-background -columns -configurecommand -font -foreground | -height -moveable -resizeable -selectbackground -selectborderwidth | -selectforeground -selectmode -separatorcolor -separatorwidth -sortable | -takefocus -textwidth -width -xscrollcommand -yscrollcommand

Inherited from Frame:
-borderwidth -highlightbackground | -highlightcolor -highlightthickness | -relief |

Name: | background
Class: | Background
Switch: | -background
Alias: | -bg
| Sets the background color for the base widget, the internal Pane, and for all columns. On Unix platforms, the value defaults to #d9d9d9 and on Win32 platforms, SystemButtonFace.
Switch: | -columns
Defines the columns in the widget. This option takes an array reference for it's value (an array reference of array references to be precise). Refer to the adding columns section in the tutorial. This option can be used to define all columns used, or each column can be inserted individually using the insertColumn() method. By default, the value is undefined.
Switch: | -configurecommand
Alias: | -configcmd
The callback which is passed to this option will be called whenever the layout of the widget has changed due to user interaction (ie. a user resizing a column by dragging a separator or moving a column by dragging a column header would trigger this callback.)
Switch: | -font
Sets the default font to be used throughout the MListbox. On Unix, this defaults to "Helvetica -12 bold", and on Win32, "{MS Sans Serif} 8"
Switch: | -foreground
Aliases: | -fg
Sets the foreground (font) color for all MListbox columns. On Unix, this defaults to black and on Win32, SystemButtonText.
Name: | height
Class: | Height
Switch: | -height
Specifies the number of rows, excluding the heading, that will be displayed in the MListbox. A value of 0 will cause the height to dynamically resize depending on the amount of rows in the widget (and can easily get out of control so is not recommended). The value defaults to 10.
Name: | moveable
Class: | Moveable
Switch: | -moveable
Boolean value which enables or disables moveable columns. A value of 1 enables all columns to be reordered by allowing drag-and-drop of column headers. A value of 0 disables this feature.
Name: | resizeable
Class: | Resizeable
Switch: | -resizeable
Boolean value that determines whether or not individual columns can be resized by dragging on their separator. A setting of 1 enables resizing for all columns, and setting of 0 disables it.
Name: | selectBackground
Class: | Background
Switch: | -selectbackground
Alias: | -selectbg
Specifies background color used for selected rows. Defaults: #c3c3c3 (Unix) and SystemHighlight (Win32).
Name: | selectBorderwidth
Class: | Borderwidth
Switch: | -selectborderwidth
Alias: | -selectbd
Specifies border width to be used for selected rows. Can be used to give the row a more pronounced 3D appearance. Default setting: 1.
Name: | selectForeground
Class: | Foreground
Switch: | -selectforeground
Alias: | -selectfg
Sets a foreground (font) color for selected rows. Defaults: black (Unix) and SystemHighlightText (Win32).
Name: | selectMode
Class: | Mode
Switch: | -selectmode
Determines the type of selection allowed within MListbox. Valid choices include: single, browse, multiple, and extended. To get a description of each of these modes, refer to the Tk::Listbox documentation. The default setting is browse.
Name: | separatorColor
Class: | SeparatorColor
Switch: | -separatorcolor
Alias: | -sepcolor
Sets the default color to be used for the separator bar (the bar that is dragged by the user to resize a column). Default setting: black.
Name: | separatorWidth
Class: | SeparatorWidth
Switch: | -separatorwidth
Alias: | -sepwidth
Specifies the width to be used for all column separators (the bar that a user can drag to to resize a column). Default: 1.
Name: | sortable
Class: | Sortable
Switch: | -sortable
Specifies whether or not sorting will be enabled for all columns. (a sort is initiated by pressing the header of a column). Possible values are 1 (enabled) and 0 (disabled). Default setting: 1
Name: | takeFocus
Class: | Focus
Switch: | -takefocus
Specifies whether or not the widget will accept focus during a keyboard traversal (a move from widget to widget using the TAB key). MListbox has keyboard bindings that can be used when it has the focus. Possible values are 1 (enabled) and 0 (disabled). Default setting: 1
Name: | textwidth
Class: | Width
Switch: | -textwidth
Specifies the number of characters to be displayed in each column. The display can be off when using non-fixed width fonts. This option is used when columns are used to control the width of the widget. Default setting: 10.
Name: | width
Class: | Width
Switch: | -width
Specifies the desired width for the MListbox, in screen units. If this value is 0 then MListbox will be sized so that all columns are displayed. The default setting is undefined.
Switch: | -xscrollcommand
Specifies a callback used to communicate with horizontal scrollbars. For full description, refer to Tk::options docs.
Switch: | -yscrollcommand
Specifies a callback used to communicate with vertical scrollbars. This option is used the same as -yscrollcommand, except for vertical scrollbars.

## Methods

### Indices

Many of the methods for MListbox take one more indices as arguments. MListbox has two general kinds of indices: column and row. Column indices are used for all methods which begin with the word column, and row indices are used for all other methods.

Column Indices

number
  Specifies the element as a numerical index, where 0 corresponds to the first element.
end
  Indicates the index of the last column in the MListbox
MLColumn
  Indicates the integer index that this widget occupies.

Row Indices

Refer to Indices section in Tk::Listbox documentation

MListbox defined:
void | activate( index )
(various) | bindColumns( sequence, callback )
(various) | bindRows( sequence, callback )
(various) | bindSeparators( sequence, callback )
arrayref | columnConfigure( index, ?option => value, ... )
@remainingColumns | columnDelete( first, ?last )
@columns | columnGet( first, ?last )
void | columnHide( first, ?last )
integer | columnIndex( index )
MLColumn | columnInsert( index, ?option => value, ... )
void | columnPack( @elements )
@elements | columnPackInfo()
void | columnShow( index, ?option => value, ... )
selection/@selection | curselection()
void | delete( first, ?last )
@rowContents | get( first, ?last )
column/@row | getRow( index )
Integer | index( index )
void | insert( index, @data )
Integer | nearest()
void | see( index )
void | selectionAnchor( index )
void | selectionClear()
Integer | selectionIncludes( index )
void | selectionSet( index )
Integer | size()
void | sort( descending, index, ... )
(various) | xview( descending, index, ... )
(various) | yview( descending, index, ... )

activate( index )

Sets the active element to the one indicated by index. If index is outside the range of elements in the listbox then the closest element is marked. Currently, an active row does not appear any different from an inactive one ( In Listbox, the active element is underlined ).

bindColumns( sequence, callback )

A convenience method, this binds a callback to a specified sequence for the header subwidget in each of the columns.

Unlike the normal bind() method, bindColumns will pass two parameters to whatever callback is defined instead of one. These include a reference to the MListbox widget, and a hash reference containing:

-subwidget => $sw
  A reference to the header subwidget that triggered the callback
-column => index
  The index of the column that contained the header subwidget

See also

binding events to MListbox in the tutorial.

bindRows( sequence, callback )

A convenience method, this binds a callback to a specified sequence for the listbox subwidget in each of the columns.

Unlike the normal bind() method, bindColumns will pass two parameters to whatever callback is defined instead of one. These include a reference to the MListbox widget, and a hash reference containing:

-subwidget => $sw
  A reference to the listbox subwidget that triggered the callback
-column => index
  The index of the column that contained the listbox subwidget
-row => index
  The index of the row directly underneath the mouse pointer. The value will be -1 in cases where there is no row directly underneath the mouse pointer.

Example:

    $ml->bindRows('<ButtonRelease-1>',  sub {
        my ($w, $infoHR) = @_;
        print "You pressed row: " . $infoHR->{-row} .
              " in column: " . $infoHR->{-column} . "\n";
    });

See also

binding events to MListbox in the tutorial.

bindSeparators( sequence, callback )

A convenience method, this binds a callback to a specified sequence for the separator subwidget in each of the columns.

Unlike the normal bind() method, bindColumns will pass two parameters to whatever callback is defined instead of one. These include a reference to the MListbox widget, and a hash reference containing:

-subwidget => $sw
  A reference to the separator subwidget that triggered the callback
-column => index
  The index of the column that contained the separator subwidget

See also

binding events to MListbox in the tutorial.

columnConfigure( index, ?option => value, ... )

Sets option values for a specific column, indicated by index.

Options:

Any valid MLColumn option.

Example:

    $ml->columnConfigure( 0,
        -background => 'blue',
        -foreground => 'white',
        -textwidth => 0,
        -separatorcolor => 'white'
    );

columnDelete( first, ?last )

Deletes all column from first index to last or just first if last is ommitted. Column indices are updated to reflect the deletes.

Returns

An array of the remaining columns.

columnGet( first, ?last )

Returns an array of MLColumn widgets specified by the range set with first and last, or a single widget if last is omitted.

columnHide( first, ?last )

Hides all columns specified by the range of indices first and last, or only one if last is omitted. Hidden columns, and their contents are not deleted, and column indices are unchanged. (This can mean that indices appear not to match what is displayed when columns are hidden.)

See also

columnShow().

columnIndex( index )

Returns an integer index value for the column specified by index.

See also

Column indices.

columnInsert( index, ?option => value, ... )

Creates a new column in the MListbox widget. The column will get the index specified by index. If index is end the new column's index will be one more than the previous highest column index.

If column index exists, the new column will be placed to the left of this column, and the indices of all columns that follow index will be incremented by one.

Options

Any valid MLColumn option.

Returns

The newly created MLColumn widget.

columnPack( @elements )

Reorders the display of columns in the MListbox according to the specifications in the elements array. Each element is a string with the format index:width where index is the index of the column to occupy this position, and width specifies the width in pixels (and can be omitted). Columns are ordered from left to right, and columns not specified are not displayed.

Example

In a MListbox with six columns, the following would reverse the order of the first three, hide the last three, and resize the second element to a ridiculously narrow width.

    $ml->columnPack(qw/2 1:5 0/);

See also

columnPackInfo().

columnPackInfo()

Returns an array of elements describing the currently layout of the MListbox widget. Each element of the array describes a visible column in the widget in the order in which they appear from left to right. An element is a string formatted index:width. Where index is a column index, and width describes the width of the column in pixels.

See also

columnPack().

columnShow( index, ?option => value )

Shows a column specified by index that has been hidden. By default the column will be displayed as the last ( far right ) element in the MListbox. This can be overridden by specifying an optional value.

Options:

-after => index
  Displays the column after (to the right of) the column specified by index
-before => index
  Displays the column before (to the left of) the column specified by index

See also

columnHide().

curselection()

Returns either an array containing the indices of all selected rows, or a scalar containing the index of the first selected row of those selected depending on the context.

Example

In a MListbox with the third row selected...

    $result = $ml->curselection();  ## $result = 2
    @result = $ml->curselection();  ## @result = ( 2 )

delete( first, ?last )

Deletes one or more rows from the MListbox, in a range specified by first and last. If last is not specified than a single row will be deleted.

get( first, ?last )

Returns the contents of rows specified by a range of row indices from first to last, inclusive, or returns only one row if last is omitted. The return value is an array of array references.

getRow( index )

A simplified version of get(), this method returns either an array of the content in each column for the row specified by index, or it will return the content of only the first column in the row depending on the context.

Example

In a MListbox with one row, and four columns containing: a, b, c, and d...

    $result = $ml->getRow(0);  ## $result = "a"
    @result = $ml->getRow(0);  ## @result = ( "a", "b", "c", "d" )

index( index )

Returns the integer index value that corresponds to index. If index is end, the return value is the count of the number of rows in the MListbox (The index after the current last element).

See also

The section on Row Indices.

insert( index, @rows )

Inserts one or more rows into the MListbox before the element at index. A single row element is an array reference to the column values for that row. If an inserted row doesn't contain sufficient values to set each column for the row, than empty strings will be substituted.

Example

For a MListbox with four columns, the following would add three new rows.

    $ml->insert("end",
        [qw/Row0:Col0 Row0:Col1 Row0:Col2 Row0:Col3/],
        [qw/Row1:Col0 Row1:Col1 Row1:Col2 Row1:Col3/],
        [qw/Row2:Col0 Row2:Col1 Row2:Col2 Row2:Col3/]
    );

nearest( y-coordinate )

Given a y-coordinate from the MListbox window, this method return the integer index of the (visible) row nearest to that y-coordinate.

see( index )

Adjusts the view in the MListbox so that the row specified by index is visible. If the element is already visible then the command has no effect.

selectionAnchor( index )

Sets the selection anchor to the element given by index. The selection anchor is the end of the selection that is fixed while dragging out a selection with the mouse. The index anchor may be used to refer to the anchor element.

selectionClear( first, ?last)

Deselects any rows within the range specified by first and last if they are selected. Will deselect only one row, specified by first if last is omitted.

selectionIncludes( index )

Returns 1 if the row specified by index is selected. Otherwise, returns 0.

selectionSet( first, ?last )

Selects all of the rows indiciated in the range specified by first and last without affecting the selection state of elements outside that range.

size()

Returns an integer iindicating the total number of rows in the MListbox.

sort( descending, ?@indices )

Sorts the content of the MListbox, if descending is a true value, the sort order will be descending, and otherwise will be ascending. By default, this value is 0 (ascending). Zero or more column indicies may be specified to use as the key to sort by. The first would be primary, then secondary, etc. By default, all columns are sort keys, sorted in order.

xview( ?option, ... )

This method performs a variety of different tasks related to vertical view for MListbox. The task depends on the specified parameters.

Options

<No Option>
  Returns a list containing two elements. Each element is a real fraction between 0 and 1; together they described the span that is visible in the window.
index
  Adjusts the view in the window so that character position given by index is displayed at the left (xview) or top (yview) side of the window.
moveto => fraction
  Adjusts the view in the window so that the element given by fraction appears at the top of the window. fraction is a value between 0 and 1; 0 indicates the first element in the listbox, 0.33 indicates one-third the way through, etc.
scroll => number, type
  Ajusts the view in the window forward or backward. The amount moved depends on the type of units, and the number of units. number can be positive or negative for forward and backward respectively, type can be units (1 char), or pages (screenfulls).

yview( ?option, ... )

This method performs a variety of different tasks related to vertical view for MListbox. The task depends on the specified parameters.

Options

See xview() options.

## Keyboard Mappings

The following keyboard mappings are bound and work if the widget has focus.

Sequence | Description
--- | ---
<Down> | Moves the location cursor (active row) down by one elment and changes the selection while in browse or extended selectmode.
<Up> | Moves the location cursor up by one element and changes the selection while in browse or extended selectmode.
<Shift-Down> | Moves the location cursor down by one, and extends the selection while in extended selectmode.
<Shift-Up> | Moves the location cursor up by one, and extends the selection while in extended selectmode.
<Shift-Control-Home> | Extends the selection to the first row.
<Shift-Control-End> | Extends the selection to the last row.
<Control-Home> | Moves the location cursor to the first row, selects it, and clears all other selected rows.
<Control-End> | Moves the location cursor to the last row, selects it, and clears all other selected rows.
<Control-Slash> | Selects all rows.
<Control-Backslash> | Deselects all rows.