Adjuster(3pm)

💖 Tk::Adjuster — the manual, but make it cute 💖

okay bestie, sit down, hydrate, and let me tell you about Tk::Adjuster (that's the Tk::Adjuster module in the 3pm manual section, user-contributed Perl docs, iykyk). It's the little drag-handle thing that lets a user resize your packed widgets with their own two hands. no cap. 🫶

---

✨ NAME ✨

Tk::Adjuster — Allow size of packed widgets to be adjusted by user 💅

---

🌸 SYNOPSIS 🌸

use Tk::Adjuster;

$adjuster = $widget->Adjuster(?options?);

literally that's it. two lines and you're already the main character. ✨

---

🎀 WIDGET-SPECIFIC OPTIONS 🎀

• -restore (Name: restore, Class: Restore) — a boolean, bestie. It decides whether the Adjuster should forcibly try to make room for itself (by shrinking its managed widget) when it gets unmapped — like, say, when a top-level window changes size. Default is 1. 🦋
• -side (Name: side, Class: Side) — which side the managed widget sits on relative to the Adjuster. With the pack geometry manager, this maps to the side of the master that the managed widget and the Adjuster are packed against. Must be left, right, top, or bottom. Defaults to top. 📐
• -widget (Name: widget, Class: Widget) — the widget that the Adjuster is gonna manage. that's the one getting resized, bestie. 👑

---

💜 DESCRIPTION 💜

Tk::Adjuster is a Frame containing a "line" and a "blob". iconic structure, honestly.

Drag with Mouse Button-1 and a line gets dragged around to show the new size. Let go of Button-1 and it submits GeometryRequests on behalf of the managed widget, which makes the packer actually change that widget's size. slay. 🔥

If the drag is done with Shift held down, then the GeometryRequests happen in "real time" so you can see the text-flow effects as you go — but way more work is being done, so behaviour may be sluggish. beautiful but expensive, like me. 💀

If the widget is packed with -side => left or -side => right, then width is what gets adjusted. If it's packed -side => top or -side => bottom, then height gets adjusted. no cap. 📏

packPropagate is turned off for the master window so that adjusting doesn't change the overall window size. Same deal — packPropagate is turned off for the managed widget if it has things packed inside it. That's so the GeometryRequests made by Tk::Adjuster don't get overridden by pack. 🫶

Also, the managed widget is made non-expandable, so the geometry manager can't reallocate freed space in the master back to the managed widget. But note: expansion is only turned off after the Adjuster is mapped — which lets the managed widget expand naturally when the window is created. it's giving ✨thoughtful✨.

The Tk::Widget method, packAdjust, calls pack on the widget, then creates an instance of Tk::Adjuster, and packs that "after" the widget. But its use has two disadvantages: the Adjuster widget isn't made available to the caller, and options can't be set on the Adjuster. For those reasons, the Tk::Adjuster method packAfter is preferred — but packAdjust is retained for backwards compatibility. periodt. 💅

---

🌈 WIDGET METHODS 🌈

• $adjuster->packAfter(managed_widget, ?pack_options?) — this command configures the Adjuster's -widget and -side options to managed_widget and the -side value specified in pack_options (or top if you didn't specify one). Then it 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. bye bestie 👋
• $adjuster->slave — this command returns the value $adjuster->cget('-widget'), i.e. the reference to the managed widget. it's just handing you the widget back, wholesome. 🥹

---

🦋 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. 😭 (the blob deserves customization, fr fr)

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

bestie. do not come for me. these are the documented bugs, I'm just the messenger. 🫠

---

That's the whole page! Written by the lovely humans of User Contributed Perl Documentation, running on perl v5.40.1, dated 2025-04-13 — so this page is a Adjuster(3pm) classic, mwah. 💋