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

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. 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 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.

-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.

-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 -followmouse option when used with a Text or Canvas widget and you want the message to be different depending on what object in the widget the mouse is over.

-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 -initwait time interval, and it will make the balloon appear under and to the right of the mouse.

-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.

METHODS

The Balloon widget supports only two non-standard methods:

attach(widget, options)

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

-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.

detach(widget)

Detaches the specified widget widget from the help system.

AUTHORS

Rajappa Iyer rsi@earthling.net did the original coding. Jason A Smith <smithj4@rpi.edu> added support for menus.

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.