Balloon(3pm)

📦
version 804.036 · 15 versions
, in debian trixie, ubuntu questing

💖 Tk::Balloon — pop up help balloons 💖

okay bestie, gather round, because we're talking about Tk::Balloon from the Perl world, and it's literally the little angel that pops up help text when your mouse just chills somewhere for a sec. pop up help balloons. that's the whole vibe. ✨

🎀 SYNOPSIS 🎀

use Tk::Balloon;
...
$b = $top->Balloon(-statusbar => $status_bar_widget);

# Normal Balloon:
$b->attach($widget,
           -balloonmsg => "Balloon help message",
           -statusmsg => "Status bar message");

# Balloon attached to entries in a menu widget:
$b->attach($menu, -state => 'status',
                  -msg => ['first menu entry',
                           'second menu entry',
                           ...
                          ],
          );

# Balloon attached to individual items in a canvas widget:
$b->attach($canvas, -balloonposition => 'mouse',
                    -msg => {'item1' => 'msg1',
                             'tag2'  => 'msg2',
                              ...
                            },
          );

# Balloon attached to items in a listbox widget:
$b->attach($listbox, -balloonposition => 'mouse',
                     -msg => ['first listbox element',
                              '2nd listbox element',
                              ...
                             ],
          );

🌸 DESCRIPTION 🌸

Balloon gives you the whole framework to create help balloons and attach them to all sorts of widgets, so that when the mouse hovers over the widget for longer than some specified amount of time — boom 💥 — a help balloon pops up. main character energy, honestly.

🦋 Balloons and Menus or Listboxes

If the balloon is attached to a Menu or Listbox widget and the message arguments are array references, then each element in the array is the message for the matching menu entry or listbox element. The balloon message shows for whichever entry the mouse pauses over. Otherwise, it's assumed the balloon is attached to the whole Menu or Listbox as one unit. And yes, you can have separate status and balloon messages just like normal balloons. 💅

🎀 Balloons and Canvases

If the balloon is attached to a Canvas widget and the message arguments are hash references, then each hash key should map to a canvas item ID or tag, and the associated value is the message for that canvas item. The balloon message shows for the current item — the one sitting under the mouse. Otherwise, it's assumed the balloon is attached to the whole Canvas. Separate status and balloon messages? absolutely, same as normal balloons. ✨

🌈 Balloons and HLists

If the balloon is attached to a HList widget and the message arguments are hash references, then each hash key should map to a HList path and the associated value is the message for that HList item. The balloon message shows for the current item — again, the one at the mouse position. Otherwise, it's assumed the balloon is attached to the whole HList. And yep, separate status and balloon messages, just like normal balloons. 🫶

🧚 Balloon Position

By default, the balloon pops up at the lower right side of the client. If that would spill outside the lower screen border, it goes to the upper right side. If it would spill outside the right screen border, it shows on the lower left side of the client. And if it would spill outside both the lower and the right screen border, it lands at the upper left side of the client. So the little arrow always points at the attached client. it's giving thoughtful. 🎯

✨ OPTIONS ✨

Balloon accepts all of the options that the Frame widget accepts. On top of that, these ones are also recognized. no skips, we're doing all of them 💖

  • -initwait — how long to wait with no activity before popping up a help balloon. measured in milliseconds. defaults to 350 milliseconds. this applies to both the popped up balloon and the status bar message.
  • -state — can be one of 'balloon', 'status', 'both' or 'none', meaning the help balloon, the status bar help, both, or neither should be activated when the mouse pauses over the client widget. default is 'both'.
  • -statusbar — the widget used to display the status message. this widget should accept the -text option and is typically a Label. if the widget accepts the -textvariable option and that option is defined, then that gets used instead of -text.
  • -balloonposition — can be one of 'widget' or 'mouse', and it controls where the balloon pops up. 'widget' makes the balloon appear at the lower right corner of the widget it's attached to (that's the default), and 'mouse' makes the balloon appear below and to the right of the current mouse position.
  • -postcommand — takes a CODE reference that runs before the balloon and statusbar messages are displayed, and it should return a true or false value telling you whether the balloon should be displayed at all. it also lets you control where the balloon gets positioned: return a true value shaped like X,Y (it matches this regular expression: "/^(\d+),(\d+)$/"), and if the postcommand's return value matches that re, those coordinates get used as the position to post the balloon. > ⚠️ warning: this subroutine should return quickly, or the balloon response will appear slow. 😭
  • -cancelcommand — takes a CODE reference that runs before the balloon and statusbar messages are canceled, and it should return a true or false value telling you whether you want the balloon canceled or not. > ⚠️ warning: this subroutine should return quickly, or the balloon response will appear slow.
  • -motioncommand — takes a CODE reference that runs for any motion event and should return a true or false value indicating whether the currently displayed balloon should be canceled (deactivated). if it returns true, the balloon will definitely be canceled; if it returns false, it may still be canceled depending on the internal rules. note: a new balloon may be posted after the -initwait time interval — use the -postcommand option to control that behavior. > ⚠️ warning: the subroutine should be extremely fast, or the balloon response will appear slow and eat a lot of CPU time (it runs every single time the mouse moves over the widgets the balloon is attached to). 💀
  • -numscreens — accepts an integer of 1 or greater. use this to avoid disjointed balloons across multiple screens in single logical screen (SLS) mode. this only currently works in the horizontal direction. example: if you're running dual screens in SLS mode, you'd set this value to 2. default value is 1.

👑 METHODS 👑

The Balloon widget supports only three non-standard methods. short list, iconic behavior.

💜 attach(widget, options)

Attaches the widget indicated by widget to the help system. The allowed options are:

  • -statusmsg — the argument is the message shown on the status bar when the mouse pauses over this client. if this isn't specified but -msg is, then the status bar message is the same as the argument for -msg. if you give it a scalar reference, it gets dereferenced before being displayed. useful when the postcommand is used to change the message.
  • -balloonmsg — the argument is the message displayed in the balloon that pops up when the mouse pauses over this client. same deal as -statusmsg: if it's not specified, it takes its value from the -msg specification if there is one. if neither -balloonmsg nor -msg are specified, or they are the empty string, then no balloon is popped up instead of an empty balloon. if you give it a scalar reference, it gets dereferenced before being displayed. useful if the postcommand is used to change the message.
  • -msg — the catch-all for -statusmsg and -balloonmsg. convenient way to specify the same message for both the balloon and the status bar for the client. 🎀
  • -initwait
  • -state
  • -statusbar
  • -balloonposition
  • -postcommand
  • -cancelcommand
  • -motioncommand

these options let you override the balloon's default value for that option for some of the widgets it's attached to. they accept the same values as above and default to the Balloon's value.

💜 detach(widget)

Detaches the specified widget from the help system. bye bestie 👋

💜 destroy

Destroys the specified balloon.

🌟 ADVERTISED SUBWIDGETS 🌟

The balloon label is advertised as "message".

🍓 EXAMPLES 🍓

See the balloon demo included with the widget demo script that came with the distribution for examples on various ways to use balloons. go look, it's cute 🫶

💅 NOTES 💅

Because of the overhead that comes with each balloon you create (tracking mouse movement to know when to activate and deactivate them and all that), you'll get the best performance (low CPU consumption) if you create as few balloons as possible and attach them to as many widgets as you can. in other words: don't create a balloon for each widget you want to attach one to. periodt. 🔥

😭 CAVEATS 😭

Pressing any button will deactivate (cancel) the current balloon, if one exists. you can usually make the balloon reappear by moving the mouse a little. creative use of the 3 command options can help you out also. and if the mouse is over the balloon when a menu is unposted, then the balloon will remain until you move off of it. sticky little thing, honestly. 🙈

💀 BUGS 💀

If you're using balloons attached to listbox entries or canvas items in a scrolled widget, then the subwidget has to be used:

$balloon->attach($w->Subwidget("scrolled"), -msg => ...);

🌈 AUTHORS 🌈

  • Rajappa Iyer <rsi@earthling.net> — did the original coding.
  • Jason A. Smith <smithj4@rpi.edu> — added support for menus and made some other enhancements.
  • Slaven Rezic <srezic@cpan.org> — added support for canvas items.
  • Gerhard Petrowitsch <gerhard@petrowitsch.de> — added intelligent positioning.
  • Jack Dunnigan <dunniganj@cpan.org> — made positioning more intelligent and added support for multiple monitors under single logical screen.

⭐ HISTORY ⭐

The code and documentation was derived from Balloon.tcl from the Tix4.0 distribution by Ioi Lam and modified by the above mentioned authors. This code may be redistributed under the same terms as Perl. slay, licensing-wise. ✨

okay that's the whole page bestie, no cap 🫶 this was perl v5.40.1, dated 2025-04-13, and it's the Balloon(3pm) page — go forth and hover responsibly 💖🎀🦋

📦 where this page comes from