DialogBox(3pm)

👑 DialogBox — the manual page, but make it cute

ok so this is DialogBox, and it lives in the Tk::DialogBox module — it's part of the User Contributed Perl Documentation situation. Basically it's the glowy popup-window maker bestie you've been looking for. 💖

---

✨ NAME ✨

Tk::DialogBox — create and manipulate a dialog screen. yes. that's the whole job. slay.

---

🌸 SYNOPSIS 🌸

use Tk::DialogBox
...
$d = $top->DialogBox(-title => "Title", -buttons => ["OK", "Cancel"]);
$w = $d->add(Widget, args)->pack;
...
$button = $d->Show;

see how easy that is?? iconic. ✨

---

🦋 DESCRIPTION 🦋

So DialogBox is very similar to Dialog, except — and this is the part that matters — it lets you put any widget in the top Frame. any. no restrictions. main character energy.

It builds you two Frames: top and bottom.

• The bottom Frame shows all the Buttons you specified, lined up left to right. a little button lineup, if you will. 🎀
• The top Frame is the container for every other widget you add in with the add() method.

---

💅 OPTIONS 💅

here are all the options DialogBox understands, no gatekeeping:

• -title — the title of your DialogBox, obvi. if you don't set it, the name of the program gets used instead. default behaviour, lowkey humble of it.
• -buttons — the button names to show in the bottom Frame. this is a reference to an array of strings, and each string is the text that goes on its Button. there is no default value for this one, bestie. and if you don't specify any button names at all? then no Buttons are displayed. empty. nothing. the void. 💀
• -default_button — the Button that counts as invoked when the user hits <Return> on the DialogBox. this one gets highlighted, so it's the star of the show 👑. if you don't name a default Button, then the first element of the array whose reference you passed to -buttons becomes the default. first come, first served, periodt.
• -cancel_button — the Button that counts as invoked when the user closes the DialogBox using the window manager's close button. here's the tea though:
  • if -cancel_button isn't given, and there's only one button configured, then that button is also used as the cancel button.
  • otherwise, no button is considered the cancel button — and in that case, Show just returns undef when the user closes the DialogBox. yeah. undef. that's it. 😭
• -command — a callback that runs after invoking an action to close the DialogBox, but before restoring focus and grab information. the selected button gets passed in as the first argument. 🫶
• -focus — specify which widget gets the initial focus once the DialogBox pops up. by default, the -default_button widget receives the initial focus.
• -showcommand — a callback that runs before displaying the DialogBox and waiting for user input. the DialogBox itself is passed as the first argument.

---

🧚 METHODS 🧚

ok so the page literally says DialogBox supports only two methods as of now... and then lists three. we don't question it. we just vibe. 🌈

add(widget, options)

Adds the widget you name in widget. widget can be the name of any Tk widget — standard or contributed, doesn't matter, we're not snobs. options are the options that widget accepts.

The widget gets advertized as a subwidget of DialogBox, and its name is lower-cased and used as the advertised name. and heads up: if you create multiple instances of the same widget in the DialogBox, only the last one gets the advertised name. last one wins, sorry to the others 🙈

also add() does not automatically pack() or grid() the widget into the DialogBox. you gotta do that yourself. it's giving independent.

Show(?-global?)

Displays the Dialog until the user invokes one of the Buttons in the bottom Frame. if the grab type -global is specified, then Show uses that grab; otherwise it defaults to a local grab. returns the name of the Button invoked.

The actual Dialog is shown using the Popup method, and any other options you hand to Show get passed along to Popup — you can use those to position the Dialog on the screen. go read Tk::Popup for the details, iykyk. ✨

Exit()

Close the dialogbox by emulating a click on the default button. sneaky. effective. slay.

---

🎀 ADVERTISED WIDGETS 🎀

• top — the subwidget reference to the top half of the DialogBox widget: the Frame holding the widgets you added with the add method.
• bottom — the subwidget reference to the bottom half of the DialogBox widget: the Frame holding the Button widgets.
• B_"button-text" — individual subwidget references to the Buttons in the DialogBox widget. the subwidget name is the string B_ concatenated with the Button's -text value.

---

💀 BUGS 💀

not me reporting the bugs but okay:

• There is no way of removing a widget once it's been added to the top Frame — unless you access the top subwidget and go through the child widgets. so, manual labour. 😭
• There is no control over the appearance of the Buttons in the bottom Frame, and no way to control the placement of the two Frames with respect to each other. they're just gonna do their thing.

---

🌟 AUTHOR 🌟

Rajappa Iyer — rsi@earthling.net

This code is distributed under the same terms as Perl. 💜

---

ok that's the whole page, you understood all of it, i'm so proud of you fr fr. this was the DialogBox(3pm) manual page from the User Contributed Perl Documentation, and it's from perl v5.40.1, dated 2025-04-13. go forth and make the cutest little dialogs. mwah. 💖✨🎀🦋