Tk::MListbox

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.

Widget // Frame // MListbox

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.

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.

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.

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

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.

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

$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

$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

$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

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