NAME

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

OPTIONS

-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

ADVERTISED SUBWIDGETS

EXAMPLES

NOTES

CAVEATS

BUGS

    $balloon->attach($w->Subwidget("scrolled"), -msg => ...);

AUTHORS

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