Tk::Adjuster - Allow size of packed widgets to be adjusted by user
use Tk::Adjuster; $adjuster = $widget->Adjuster(?options?);
User Contributed Perl Documentation Adjuster(3)
NAME
Tk::Adjuster - Allow size of packed widgets to be adjusted by user
SYNOPSIS
use Tk::Adjuster;
$adjuster = $widget->Adjuster(?options?);
WIDGET-SPECIFIC OPTIONS
Name: restore
Class: Restore
Switch: -restore
Specifies a boolean value that determines whether the Adjuster
should forcibly attempt to make room for itself (by reducing the
size of its managed widget) when it is unmapped (for example, due
to a size change in a top level window). The default value is 1.
Name: side
Class: Side
Switch: -side
Specifies the side on which the managed widget lies relative to the
Adjuster. In conjunction with the pack geometry manager, this
relates to the side of the master against which the managed widget
and the Adjuster are packed. Must be left, right, top, or bottom.
Defaults to top.
Name: widget
Class: Widget
Switch: -widget
Specifies the widget which is to be managed by the Adjuster.
DESCRIPTION
Tk::Adjuster is a Frame containing a "line" and a "blob".
Dragging with Mouse Button-1 results in a line being dragged to
indicate new size. Releasing Button-1 submits GeometryRequests on
behalf of the managed widget which will cause the packer to change the
widget's size.
If Drag is done with Shift button down, then GeometryRequests are made
in "real time" so that text-flow effects can be seen, but as a lot more
work is done behaviour may be sluggish.
If widget is packed with -side => left or -side => right then width is
adjusted. If packed -side => top or -side => bottom then height is
adjusted.
packPropagate is turned off for the master window to prevent adjustment
changing overall window size. Similarly packPropagate is turned off for
the managed widget if it has things packed inside it. This is so that
the GeometryRequests made by Tk::Adjuster are not overridden by pack.
In addition, the managed widget is made non-expandable to prevent the
geometry manager reallocating freed space in the master back to the
managed widget. Note however that expansion is turned off only after
the Adjuster is mapped, which allows the managed widget to expand
naturally on window creation.
The Tk::Widget method, packAdjust, calls pack on the widget, then
creates an instance of Tk::Adjuster, and packs that "after" the widget.
Its use has two disadvantages however: the Adjuster widget is not made
available to the caller, and options cannot be set on the Adjuster. For
these reasons, the Tk::Adjuster method, packAfter is preferred, but
packAdjust is retained for backwards compatibility.
WIDGET METHODS
$adjuster->packAfter(managed_widget, ?pack_options?)
This command configures the Adjuster's -widget and -side options
respectively to managed_widget and the -side value specified in
pack_options (top if not specified). It then packs the Adjuster
after managed_widget, with -fill set to x or y as appropriate.
$adjuster->packForget?(boolean)?
This command calls Tk::Widget::packForget on the Adjuster. If a
parameter is provided and it has a true boolean value, then
packForget is also called on the managed widget.
$adjuster->slave
This command returns the value $adjuster->cget('-widget'), ie. the
reference to the managed widget.
EXAMPLES
Using an Adjuster to separate two widgets, whereby the left widget is
managed, and right widget expands to fill space on a window resize
a) Using packAfter (preferred interface)
use Tk;
use Tk::Adjuster;
my $f = MainWindow->new;
my $lst1 = $f->Listbox();
my $adj1 = $f->Adjuster();
my $lst2 = $f->Listbox();
my $side = 'left';
$lst1->pack(-side => $side, -fill => 'both', -expand => 1);
$adj1->packAfter($lst1, -side => $side);
$lst2->pack(-side => $side, -fill => 'both', -expand => 1);
MainLoop;
b) Using packAdjust
use Tk;
use Tk::Adjuster;
my $f = MainWindow->new;
my $lst1 = $f->Listbox();
my $lst2 = $f->Listbox();
my $side = 'left';
$lst1->packAdjust(-side => $side, -fill => 'both');
$lst2->pack (-side => $side, -fill => 'both', -expand => 1);
MainLoop;
c) Using the standard Tk::Widget::pack
use Tk;
use Tk::Adjuster;
my $f = MainWindow->new;
my $side = 'left';
my $lst1 = $f->Listbox();
my $adj = $f->Adjuster(-widget => $lst1, -side => $side);
my $lst2 = $f->Listbox();
$lst1->pack(-side => $side, -fill => 'both', -expand => 1);
$adj->pack (-side => $side, -fill => 'y');
$lst2->pack(-side => $side, -fill => 'both', -expand => 1);
MainLoop;
Changing the above examples so that $side has the value 'right' means
the left widget expands to fill space on a window resize.
Changing the above examples so that $side has the value 'top' produces
a testcase with a horizontal Adjuster. Here the bottom widget expands
to fill space on a window resize. Packing to the 'bottom' makes the
top widget expand to fill space on window resize.
Using -restore => 0 for multiple columns
In the case of multiple columns (or rows) the "restore" functionality
of the Adjuster can be inconvenient. When the user adjusts the width of
one column and thereby pushes the Adjuster of another column off the
window, this adjuster tries to restore itself by reducing the size of
its managed widget. This has the effect that column widths shrink; and
the original size is not restored when the user reverses the
originating change. The -restore option can be used to turn off this
functionality. (It makes some sense, however, to leave -restore turned
on for the first-packed Adjuster, so that at least one Adjuster always
remains visible.)
use Tk;
use Tk::Adjuster;
my $f = MainWindow->new;
my $lst1 = $f->Listbox();
my $adj1 = $f->Adjuster();
my $lst2 = $f->Listbox();
my $adj2 = $f->Adjuster(-restore => 0);
my $lst3 = $f->Listbox();
my $side = 'left';
$lst1->pack(-side => $side, -fill => 'both', -expand => 1);
$adj1->packAfter($lst1, -side => $side);
$lst2->pack(-side => $side, -fill => 'both', -expand => 1);
$adj2->packAfter($lst2, -side => $side);
$lst3->pack(-side => $side, -fill => 'both', -expand => 1);
MainLoop;
BUGS
It is currently not possible to configure the appearance of the
Adjuster. It would be nice to be able to set the width and relief of
the Adjuster "line" and the presence/absence of the "blob" on the
Adjuster.
Tk::Adjuster works theoretically with the grid geometry manager but
there are currently some problems which seem to be due to bugs in grid:
a) There's never an Unmap event for the adjuster, so the "restore"
functionality has no effect.
b) After adjusting, widgets protrude into the border of the master.
c) grid('Propagate', 0) on MainWindow has no effect - window shrinks/grows
when widgets are adjusted.
d) Widgets shuffle to correct position on startup
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
+---------------+----------------------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+----------------------------+
|Availability | library/perl-5/perl-tk-532 |
+---------------+----------------------------+
|Stability | Volatile |
+---------------+----------------------------+
NOTES
Source code for open source software components in Oracle Solaris can
be found at https://www.oracle.com/downloads/opensource/solaris-source-
code-downloads.html.
This software was built from source available at
https://github.com/oracle/solaris-userland. The original community
source was downloaded from
http://search.cpan.org/CPAN/authors/id/S/SR/SREZIC/Tk-804.036.tar.gz.
Further information about this software can be found on the open source
community website at http://search.cpan.org/~srezic/Tk.
perl v5.32.0 2013-11-15 Adjuster(3)