balloon(3)
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',
...
},
);
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
If the balloon is attached to a Menu widget and the mes
sage arguments are array references, then each element in
the array will be the message corresponding to a menu
entry. 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 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 mes
sage arguments are hash references, then each hash key
should correspond to a canvas item ID or tag and the asso
ciated value will correspond to the message for that can
vas item. The balloon message will then be shown for the
current item (the one at the position of the mouse). Oth
erwise 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.
OPTIONS
Balloon accepts all of the options that the Frame widget
accepts. In addition, the following options are also rec
ognized.
- -initwait
- Specifies the amount of time to wait without activity
before popping up a help balloon. Specified in mil
liseconds. Defaults to 350 milliseconds. This applies
to both the popped up balloon and the status bar mes
sage. - -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 mes
sage. 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 exe
cuted 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:
"/^(+),(+)$/"). 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 exe
cuted 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 exe
cuted for any motion event and should return a true or
false value to indicate whether the currently dis
played 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 inter val, use the -postcommand option to control that behavior. Warning: the subroutine should be extremely fast or the balloon response will appear slow and con
sume a lot of CPU time (it is executed every time the
mouse moves over the widgets the balloon is attached
to).
METHODS
The Balloon widget supports only three non-standard meth
ods:
attach(widget, options)
Attaches the widget indicated by widget to the help sys
tem. 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 argu
ment 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 spec
ification if any. If neither -balloonmsg nor -msg are specified, or they are the empty string then no bal
loon 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. - detach(widget)
- Detaches the specified widget from the help system.
- destroy
- Destroys the specified balloon.
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 per
formance (low CPU consumption) if you create as few bal
loons 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
Hopefully none, probably some.
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 <eserte@cs.tu-berlin.de> added support for
canvas items.
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 redis
tributed under the same terms as Perl.