form(3pm)

📦

version 804.036 · 15 versions

804.036 · debian trixie, ubuntu questing (latest)
804.036 · opensuse-leap 16.0
804.035 · centos-stream 9
804.036 · centos-stream 10
804.036 · alpine 3.22
804.036 · alpine 3.23
804.036 · alpine 3.24
804.036 · arch rolling
804.036 · ubuntu stonking
804.035 · ubuntu jammy
804.036 · fedora 43
804.036 · fedora 44
804.036 · ubuntu noble
804.036 · debian bookworm
804.036 · ubuntu resolute

💖 form(3pm) — Tk::form 💖

okay bestie, buckle up, because we're diving into Tk::form, aka the geometry manager that runs on attachment rules. it's giving architect energy. no cap.

✨ NAME ✨

Tk::form — a Geometry manager based on attachment rules 🦋

✨ SYNOPSIS ✨

$widget->form?(args)?

$widget->formOption?(args)?

✨ DESCRIPTION ✨

so the form method is how you talk to the form Geometry Manager. and what does that icon do? it arranges the geometry of the children inside a parent window according to attachment rules. lowkey it's very flexible and very powerful — it can literally emulate all the existing features of the Tk packer and placer geometry managers (go peek at pack, place if you wanna compare notes 👀).

the form method can take any of several forms, depending on Option:

$slave->form?(options)? — sets or adjusts the attachment values of the slave window, according to the -option=>value argument pairs. here's the whole menu, bestie:
- -b => attachment — shorthand for the -bottom option. lazy girl's fave 💅
- -bottom => attachment — sets an attachment for the bottom edge of the slave window. the attachment has to be specified the way "SPECIFYING ATTACHMENTS" below says, no freestyling.
- -bottomspring => weight — sets the weight of the spring on the bottom edge of the slave window. see "USING SPRINGS" below.
- -bp => value — shorthand for the -padbottom option.
- -bs => weight — shorthand for the -bottomspring option.
- -fill => style — sets the fillings when springs are used for this widget. the value has to be x, y, both or none. pick one, queen.
- -in => $master — plops the slave window into the specified $master window. if the slave was originally chilling in another master window, all attachment values with respect to the original master window are discarded. and even if the attachment values are the same as in the original master window, they still need to be specified again — no shortcuts. the -in flag, when you need it, has to show up as the first flag of options. otherwise an error is generated. main character goes first, periodt.
- -l => attachment — shorthand for the -left option.
- -left => attachment — sets an attachment for the left edge of the slave window. attachment must be specified per "SPECIFYING ATTACHMENTS" below.
- -leftspring => weight — sets the weight of the spring on the left edge of the slave window. see "USING SPRINGS" below.
- -lp => value — shorthand for the -padleft option.
- -ls => weight — shorthand for the -leftspring option.
- -padbottom => value — sets how much external padding to leave on the bottom side of the slave. the value can be any of the forms acceptable to Tk_GetPixels.
- -padleft => value — sets how much external padding to leave on the left side of the slave.
- -padright => value — sets how much external padding to leave on the right side of the slave.
- -padtop => value — sets how much external padding to leave on the top side of the slave.
- -padx => value — sets how much external padding to leave on both the left and the right sides of the slave. two for one, slay.
- -pady => value — sets how much external padding to leave on both the top and the bottom sides of the slave. also two for one 💖
- -r => attachment — shorthand for the -right option.
- -right => attachment — sets an attachment for the right edge of the slave window. attachment must be specified per "SPECIFYING ATTACHMENTS" below.
- -rightspring => weight — sets the weight of the spring on the right edge of the slave window. see "USING SPRINGS" below.
- -rp => value — shorthand for the -padright option.
- -rs => weight — shorthand for the -rightspring option.
- -t => attachment — shorthand for the -top option.
- -top => attachment — sets an attachment for the top edge of the slave window. attachment must be specified per "SPECIFYING ATTACHMENTS" below.
- -topspring => weight — sets the weight of the spring on the top edge of the slave window. see "USING SPRINGS" below.
- -tp => value — shorthand for the -padtop option.
- -ts => weight — shorthand for the -topspring option.
$master->formCheck — this method checks whether there's a circular dependency in the attachments of the master's slaves (peep "CIRCULAR DEPENDENCY" below 👀). it returns the Boolean value TRUE if it discovers a circular dependency, and FALSE otherwise. vibe check: passed or failed.
$slave->formForget — removes the slave from its master and unmaps its window. the slave is no longer managed by form, bestie, it's free. all attachment values with respect to its master window are discarded. and if another slave is attached to this slave, then that other slave's attachment gets changed to grid attachment based on its geometry.
$master->formGrid?(x_size, y_size)? — when x_size and y_size are given, this method returns the number of grids of the $master window as a pair of integers of the form (x_size, y_size). when both x_size and y_size are given, this method changes the number of horizontal and vertical grids on the master window. it's giving grid math ✨
$slave->formInfo?(-option)? — queries the attachment options of a slave window. -option can be any of the options accepted by the form method. if -option is given, only the value of that option is returned. otherwise, this method returns a list whose elements are the current configuration state of the slave, given in the same option-value form you might specify to form. the first two elements in that list are "-in=>$master", where $master is the slave's master window.
$master->formSlaves — returns a list of all the slaves for the master window. the order of the slaves in the list is the same as their order in the packing order. if master has no slaves, then an empty string is returned. sad, but that's the rules 🥲

✨ SPECIFYING ATTACHMENTS ✨

you can specify an attachment for each side of a slave window managed by form. an attachment is specified in the form "-side => [anchor_point, offset]". -side can be one of -top, -bottom, -left or -right.

Offset is given in screen units (aka any of the forms acceptable to Tk_GetPixels). a positive offset means shifting to a position to the right or bottom of an anchor point. a negative offset means shifting to a position to the left or top of an anchor point. directions, bestie.

Anchor_point can be given in one of the following forms:

✨ Grid Attachment ✨

the master window gets divided into a bunch of horizontal and vertical grids. by default the master window is divided into 100x100 grids; you can adjust the number of grids with the formGrid method. a grid attachment anchor point is given by a % sign followed by an integer value. for example, '%0' specifies the first grid line (the top or left edge of the master window). '%100' specifies the last grid line (the bottom or right edge of the master window). it's giving percentages but make it grids 🎀

✨ Opposite Side Attachment ✨

an opposite attachment specifies an anchor point located on the opposite side of another slave widget, and that other widget must be managed by form in the same master window. an opposite attachment anchor point is given by the name of another widget. for example, "$b->form(-top=>[$a,0])" attaches the top side of the widget $b to the bottom of the widget $a. matching each other's energy, fr fr 🫶

✨ Parallel Side Attachment ✨

a parallel attachment specifies an anchor point located on the same side of another slave widget, which must be managed by form in the same master window. a parallel attachment anchor point is given by the sign & followed by the name of another widget. for example, "$b->form(-top=>['&',$a,0])" attaches the top side of the widget $b to the top of the widget $a, which makes the top sides of these two widgets sit at the same vertical position in their parent window. twinsies ✨

✨ No Attachment ✨

specifies a side of the slave to be attached to nothing, indicated by the keyword none. when the none anchor point is given, the offset must be zero (or not present at all). when a side of a slave is attached to ['none', 0], the position of this side is calculated by the position of the other side and the natural size of the slave. for example, if the left side of a widget is attached to ['%0', 100], its right side is attached to ['none', 0], and the natural size of the widget is 50 pixels, then the right side of the widget will be positioned at pixel ['%0', 149]. math is math.

when both -top and -bottom are attached to none, then by default -top will be attached to ['%0', 0]. when both -left and -right are attached to none, then by default -left will be attached to ['%0', 0]. defaults coming in clutch 🙈

shifting effects can be achieved by specifying a non-zero offset with an anchor point. in the following example, the top side of widget $b is attached to the bottom of $a; hence $b always appears below $a. also, the left edge of $b is attached to the left side of $a with a 10 pixel offset. therefore, the left edge of $b is always shifted 10 pixels to the right of $a's left edge:

$b->form(-left=>[$a,10], -top=>[$a,0]);

✨ ABBREVIATIONS: ✨

certain abbreviations can be made on the attachment specifications. first off, an offset of zero can be omitted. so these following two lines are equivalent:

$b->form(-top=>[$a,0], -right=>['%100',0]);

$b->form(-top=>[$a], -right=>'%100');

in the second case, when the anchor point is omitted, the offset must be given. a default anchor point gets chosen according to the value of the offset. if the anchor point is 0 or positive, the default anchor point %0 is used; so "$b->form(-top=>15)" attaches the top edge of $b to a position 15 pixels below the top edge of the master window. if the anchor point is "-0" or negative, the default anchor point %100 is used; so "$a->form(-right=>-2)" attaches the right edge of $a to a position 2 pixels to the left of the master window's right edge. and one more example below shows a method with its equivalent abbreviation:

$b->form(-top=>['%0',10], -bottom=>['%100',0]);

$b->form(-top=>10, -bottom=>-0);

✨ USING SPRINGS ✨

to be written.

...yeah that's literally all it says, bestie 😭 the lore isn't lore-ing yet. stay tuned for part 2 💖

✨ ALGORITHM OF FORM ✨

Okay so form starts with any slave in the list of slaves of the master window. Then it tries to determine the position of each side of the slave. 💅

If the attachment of a side of the slave is grid attachment, the position of the side is readily determined. ✨

If the attachment of this side is none, then form tries to determine the position of the opposite side first, and then uses the position of the opposite side and the natural size of the slave to determine the position of this side. 🫶

If the attachment is opposite or parallel widget attachments, then form tries to determine the positions of the other widget first, and then uses the positions of the other widget and the natural size of the slave to determine the position of this side. This recursive algorithm is carried on until the positions of all slaves are determined. 💖

💀 CIRCULAR DEPENDENCY 💀

The algorithm of form will fail if a circular dependency exists in the attachments of the slaves. For example:

    $c->form(-left=>$b);

    $b->form(-right=>$c);

In this example, the position of the left side of $b depends on the right side of $c, which in turn depends on the left side of $b. 😭

When a circular dependency is discovered during the execution of the form algorithm, form will generate a background error and the geometry of the slaves are undefined (and will be arbitrary). Notice that form only executes the algorithm when the specification of the slaves' attachments is complete. Therefore, it allows intermediate states of circular dependency during the specification of the slaves' attachments. Also, unlike the Motif Form manager widget, form defines circular dependency as ``dependency in the same dimension''. Therefore, the following code fragment does not have circular dependency because the two widgets do not depend on each other in the same dimension ($b depends on $c in the horizontal dimension and $c depends on $b in the vertical dimension): 💅

    $b->form(-left=>$c);

    $c->form(-top=>$b);

🐛 BUGS 🐛

Springs have not been fully implemented yet. 😭

👀 SEE ALSO 👀

Tk::grid
Tk::pack
Tk::place

🔑 KEYWORDS 🔑

geometry manager, form, attachment, spring, propagation, size, pack, tix, master, slave

That's the whole vibe, bestie. This page came from perl v5.40.1, dated 2025-04-13, and it's the form(3pm) manual page. xoxo 💖🦋

📦 where this page comes from

debian trixie: perl-tk 1:804.036+dfsg1-5
ubuntu questing: perl-tk 1:804.036+dfsg1-5
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms