/ 
Tk-Contrib-0.06
River stage zero No dependents
/ Tk::TiedListbox

NAME

Tk::TiedListbox - gang together Listboxes

SYNOPSIS

use Tk::TiedListbox

$l1 = $widget->Listbox(-exportselection => 0,...);
$l2 = $widget->Listbox(-exportselection => 0,...);
$l3 = $widget->Listbox(-exportselection => 0,...);
$l1->tie([$l2,$l3]);

DESCRIPTION

TiedListbox causes two or more Listboxes to be operated in tandem. One application is emulating multi-column listboxes. The scrolling, selection, or both mechanisms may be tied together. The methods tie and untie are provided, along with overridden versions of some of the Listbox methods to provide tandem operation.

Scrollbars are fully supported. You can use either explicitly created Scrollbars, the ScrlListbox widget, or the Scrolled super-widget. Tricks to "attach" multiple tied listboxes to a single scrollbar are unnecessary and will lead to multiple calls of the listbox methods (a bad thing).

The configuration options, geometry, and items of the Listboxes are not altered by tying them. The programmer will have to make sure that the setup of the Listboxes make sense together. Here are some (unenforced) guidelines:

For listboxes with tied selection:

  • set -exportselection to 0 for all but possibly one Listbox

  • use identical -selectmode for all Listboxes

  • if items are added/deleted, they should be done all at once and at the same index, or the selection should be cleared

  • Listboxes should have the same number of items

For listboxes with tied scrolling:

  • use the same window height and font for all Listboxes

  • Listboxes should have the same number of items

METHODS

$listbox->tie?(?option?, [listbox,...])?

Ties together $listbox and the list of Listboxes with the given option. Returns $listbox.

If no arguments are given, returns a list containing two items: the tie option ("scroll", "selection", or "all") and the list of Listboxes to which $listbox is tied.

option can be one of "scroll", "selection", or "all". If omitted, "all" is assumed. "scroll" makes the tied Listboxes scroll together, "selection" makes selections occur simultaneously in all tied Listboxes, and "all" effects both actions.

All the Listboxes are untied (if previously tied) before being tied to each other; hence a Listbox can only be in one "tie group" at a time. "Tiedness" is commutative.

The tie method can be called with either Listbox or TiedListbox objects. All Listbox objects specified are reblessed to TiedListbox objects.

Code such as below can be used to tie ScrlListboxes:

$slb1=ScrlListbox(...); # or Scrolled('Listbox',...
$slb2=ScrlListbox(...); # or Scrolled('Listbox',...
$slb1->tie([$slb2->Subwidget('scrolled')]);
$listbox->untie()

This function unties the Listbox from its "tie group". The other items in the "tie group" (if more than one) remain tied to each other.

Returns a list containing two items: the old tie option ("scroll", "selection", or "all") and the list of Listboxes to which $listbox was tied.

OVERRIDDEN METHODS

You probably don't care about these. They are just details to tie together the behaviors of the listboxes.

All overriden methods take identical arguments as the corresponding Listbox methods (see the Listbox documentation for a full description). All overridden methods that take an index interpret that index in the context of the listbox object provided.

$listbox->activate(...)
$listbox->selection(...)

To allow tied selection, these functions are overridden for listboxes tied together with the "selection" or "all" option. When an item is selected or activated in one listbox, the items with the same index (if present) are selected or activated in all tied listboxes.

The selection('includes',...) submethod returns only information about the given $listbox.

$listbox->scan(...)
$listbox->see(...)
$listbox->yview(...)

To allow tied scrolling, these functions are overridden for listboxes tied together with the "scroll" or "all" option. When one listbox is scrolled, all the other tied listboxes are scrolled by the same number of items (if possible). An attempt is made to keep items of the same index at the top of each tied listbox, while not interfering with the normal scrolling operations.

The yview method with no arguments returns only information about the given $listbox.

Horizontal scrolling (via xview) is not tied.

BUGS

Reblessing the widgets to TiedListbox might be too weird. It will disable any additional features for widgets in a class derived from Listbox (none yet that I know of).

The bindtags for reblessed widgets aren't updated. This is probably wouldn't be a good thing to do automatically anyway.

AUTHOR

Andrew Allen <ada@fc.hp.com>

This code may be distributed under the same conditions as Perl.