Tk::Balloon - pop up help balloons.
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',
...
],
);
Balloon provides the framework to create and attach help balloons to various widgets so that when the mouse pauses over the widget for more than a specified amount of time, a help balloon is popped up.
If the balloon is attached to a Menu or Listbox widget and the message arguments are array references, then each element in the array will be the message corresponding to a menu entry or listbox element. The balloon message will then be shown for the entry which the mouse pauses over. Otherwise it is assumed that the balloon is to be attached to the Menu or Listbox as a whole. You can have separate status and balloon messages just like normal balloons.
If the balloon is attached to a Canvas widget and the message arguments are hash references, then each hash key should correspond to a canvas item ID or tag and the associated value will correspond to the message for that canvas item. The balloon message will then be shown for the current item (the one at the position of the mouse). Otherwise it is assumed that the balloon is to be attached to the Canvas as a whole. You can have separate status and balloon messages just like normal balloons.
By default, the balloon pops up at the lower right side of the client. If it would extend outside the lower screen border, its positioned at the upper right side. If it would extend outside the right screen border it's shown on the lower left side of the client. If it would extend outside both the lower and the right screen border, it's positioned at the upper left side of the client. Thus, the little arrow always points to the attached client.
Balloon accepts all of the options that the Frame widget accepts. In addition, the following options are also recognized.
/^(\d+),(\d+)$/). If the postcommand returns a value that
matches that re then those coordinates will be used as the position to
post the balloon. Warning: this subroutine should return quickly or
the balloon response will appear slow.
The Balloon widget supports only three non-standard methods:
Attaches the widget indicated by widget to the help system. The allowed options are:
Detaches the specified widget from the help system.
Destroys the specified balloon.
The balloon label is advertised as message.
See the balloon demo included with the widget demo script that came with the distribution for examples on various ways to use balloons.
Because of the overhead associated with each balloon you create (from tracking the mouse movement to know when to activate and deactivate them) you will see 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.
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. If the mouse is over the balloon when a menu is unposted then the balloon will remain until you move off of it.
If using balloons attached to listbox entries or canvas items in a scrolled widget, then the subwidget have to be used:
$balloon->attach($w->Subwidget("scrolled"), -msg => ...);
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.
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.