Tk::MListbox |
Package Info | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Tutorial | FAQ | Changes/Bug fixes |
|
||||||||||||
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.
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.
Subwidgets: | |||||
|
This is the container that holds all MListbox columns (for horizontal scrolling). |
At creation time, all MListbox-defined options except for
MListbox defined: | |
Inherited from Frame: | |||||
|
|
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. | |||||||||
|
| |||||||||
|
| |||||||||
|
| |||||||||
|
| |||||||||
|
| |||||||||
|
| |||||||||
|
| |||||||||
|
| |||||||||
|
| |||||||||
|
| |||||||||
| ||||||||||
|
| |||||||||
|
| |||||||||
|
| |||||||||
|
| |||||||||
|
| |||||||||
|
| |||||||||
|
| |||||||||
|
|
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
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:
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:
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:
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
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
$ml->columnPack(qw/2 1:5 0/);
See also
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:
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.
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.
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. |