
=head1 NAME

Tk::Balloon - pop up help balloons.

=for pm Tixish/Balloon.pm

=for category Tix Extensions

=head1 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 a menu widget:
    $b->attach($file_menu->menu, -msg => ['first menu entry',
					  'second menu entry',
					  ...
					 ],
	      );

    # Balloon attached to canvas widget items and tags:
    $b->attach($canvas, -msg => {'item1' => 'msg1',
				 'tag2'  => 'msg2',
				  ...
				},
	      );

=head1 DESCRIPTION

B<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 widget then it
will expect the message arguments to be array references with
each element in the array corresponding to a menu entry. The balloon
message will then be shown for the active menu entry.

Balloon messages may also be attached to individual canvas items and
tags. The message arguments have to be references to hashes with the
items and tags as keys and the corresponding messages as values.

B<Balloon> accepts all of the options that the B<Frame> widget
accepts. In addition, the following options are also recognized.

=over 4

=item B<-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.

=item B<-state>

Can be one of B<balloon>, B<status>, B<both> or B<none> indicating
that the help balloon, status bar help, both or none respectively
should be activated when the mouse pauses over the client widget.

=item B<-statusbar>

Specifies the widget used to display the status message. This
widget should accept the B<-text> option and is typically a
B<Label>. If the widget accepts the B<-textvariable> option and
that option is defined then it is used instead of the B<-text>
option.

=item B<-postcommand>

This option takes a CODE reference which is to be executed before
the balloon and statusbar messages are displayed. Useful in combination
with the B<-followmouse> option when used with a B<Text> or B<Canvas>
widget and you want the message to be different depending on what
object in the widget the mouse is over.

=item B<-followmouse>

This option can be set to 0 or 1 and has 2 effects. It will cause
the balloon to be displayed only if the mouse is completely
motionless for the B<-initwait> time interval, and it will make
the balloon appear under and to the right of the mouse.

=item B<-show>

This option can be set to 0 or 1 and will disable or enable the
balloon or statusbar message. Useful in the postcommand if you
want to cancel the current balloon before it is displayed.

=back

=head1 METHODS

The B<Balloon> widget supports only two non-standard methods:

=over 4

=item B<attach(>I<widget>, I<options>B<)>

Attaches the widget indicated by I<widget> to the help system. The
options can be:

=over 4

=item B<-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
B<-msg> is specified then the message displayed on the status bar
is the same as the argument for B<-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.

=item B<-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
B<-statusmsg> if this is not specified, then it takes its value
from the B<-msg> specification if any. If neither B<-balloonmsg>
nor B<-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.

=item B<-msg>

The catch-all for B<-statusmsg> and B<-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.

=back

=item B<detach(>I<widget>B<)>

Detaches the specified widget I<widget> from the help system.

=back

=head1 AUTHORS

B<Rajappa Iyer> rsi@earthling.net did the original coding.
Jason A Smith <smithj4@rpi.edu> added support for menus.
Slaven Rezic <eserte@cs.tu-berlin.de> added support for canvas items.

This code and documentation is derived from Balloon.tcl from the
Tix4.0 distribution by Ioi Lam. This code may be redistributed
under the same terms as Perl.

=cut

