NAME¶
Tk::Balloon - pop up help balloons.
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 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.
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 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.
Balloons and Canvases¶
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.
Balloons and HLists¶
If the balloon is attached to a
HList widget and the message arguments
are hash references, then each hash key should correspond to a HList path and
the associated value will correspond to the message for that HList 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
HList as a whole. You can have 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 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.
OPTIONS¶
Balloon accepts all of the options that the
Frame widget accepts.
In addition, the following options are also recognized.
- -initwait
- Specifies the amount of time to wait without activity
before popping up a help balloon. Specified 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' indicating that the help balloon, status
bar help, both or none respectively should be activated when the mouse
pauses over the client widget. Default is 'both'.
- -statusbar
- Specifies 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 it is used instead of the -text
option.
- -balloonposition
- Can be one of 'widget' or 'mouse'. It
controls where the balloon will popup. 'widget' makes the balloon
appear at the lower right corner of the widget it is attached to
(default), and 'mouse' makes the balloon appear below and to the
right of the current mouse position.
- -postcommand
- This option takes a CODE reference which will be
executed before the balloon and statusbar messages are displayed and
should return a true or false value to indicate whether you want the
balloon to be displayed or not. This also lets you control where the
balloon is positioned by returning a true value that looks like X,Y
(matches this regular expression: "/^(\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.
- -cancelcommand
- This option takes a CODE reference which will be
executed before the balloon and statusbar messages are canceled and should
return a true or false value to indicate whether you want the balloon to
be canceled or not. Warning: this subroutine should return quickly
or the balloon response will appear slow.
- -motioncommand
- This option takes a CODE reference which will be
executed for any motion event and should return a true or false value to
indicate whether the currently displayed balloon should be canceled
(deactivated). If it returns true then the balloon will definitely be
canceled, if it returns false then it may still be canceled depending 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 consume a lot of CPU
time (it is executed every time the mouse moves over the widgets the
balloon is attached to).
- -numscreens
- This option accepts an integer 1 or greater. This option
should be used to avoid disjointed balloons across multiple screens in
single logical sceen (SLS) mode. This only currently works in the
horizontal direction. Example: If you are running dual screens in SLS mode
then you would set this value to 2. Default value is 1.
METHODS¶
The
Balloon widget supports only three non-standard methods:
Attaches the widget indicated by
widget to the help system. The allowed
options are:
- -statusmsg
- The argument is the message to be shown on the status bar
when the mouse pauses over this client. If this is not specified, but
-msg is specified then the message displayed on the status bar is
the same as the argument for -msg. If you give it a scalar
reference then it is dereferenced before being displayed. Useful if the
postcommand is used to change the message.
- -balloonmsg
- The argument is the message to be displayed in the balloon
that will be popped up when the mouse pauses over this client. As with
-statusmsg if this is not specified, then it takes its value from
the -msg specification if any. 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
then it is dereferenced before being displayed. Useful if the postcommand
is used to change the message.
- -msg
- The catch-all for -statusmsg and -balloonmsg.
This is a convenient way of specifying the same message to be displayed in
both the balloon and the status bar for the client.
- -initwait
- -state
- -statusbar
- -balloonposition
- -postcommand
- -cancelcommand
- -motioncommand
- These options allow you to override the balloon's default
value for those option for some of the widgets it is attached to. It
accepts the same values as above and will default to the Balloon's
value.
Detaches the specified
widget from the help system.
destroy¶
Destroys the specified balloon.
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.
NOTES¶
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.
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. If the mouse is
over the balloon when a menu is unposted then the balloon will remain until
you move off of it.
BUGS¶
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 => ...);
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.