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