MAN page from RedHat Other PerlTk-8.11-1.i386.rpm

BALLOON

Section: User Contributed Perl Documentation (1)
Updated: perl 5.004, patch 04
Index

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 helpballoons to various widgets so that when the mouse pauses over thewidget for more than a specified amount of time, a help balloon ispopped up.

Balloons and Menus

If the balloon is attached to a Menu widget and the message argumentsare array references, then each element in the array will be themessage corresponding to a menu entry. The balloon message will thenbe shown for the entry which the mouse pauses over. Otherwise it isassumed that the balloon is to be attached to the Menu as a whole.You can have separate status and balloon messages just like normalballoons.

Balloons and Canvases

If the balloon is attached to a Canvas widget and the messagearguments are hash references, then each hash key should correspond toa canvas item ID or tag and the associated value will correspond to themessage for that canvas item. The balloon message will then be shown forthe current item (the one at the position of the mouse). Otherwise it isassumed that the balloon is to be attached to the Canvas as a whole.You can have separate status and balloon messages just like normalballoons.

OPTIONS

Balloon accepts all of the options that the Frame widgetaccepts. In addition, the following options are also recognized.

-initwait: Specifies the amount of time to wait without activity beforepopping up a help balloon. Specified in milliseconds. Defaults to350 milliseconds. This applies to both the popped up balloon andthe status bar message.
-state: Can be one of 'balloon', 'status', 'both' or 'none'indicating that the help balloon, status bar help, both or nonerespectively should be activated when the mouse pauses over theclient widget. Default is 'both'.
-statusbar: Specifies the widget used to display the status message. Thiswidget should accept the -text option and is typically aLabel. If the widget accepts the -textvariable option andthat option is defined then it is used instead of the -textoption.
-balloonposition: Can be one of 'widget' or 'mouse'. It controls where the balloonwill popup. 'widget' makes the balloon appear at the lower rightcorner of the widget it is attached to (default), and 'mouse' makesthe balloon appear below and to the right of the current mouse position.
-postcommand: This option takes a CODE reference which will be executed before theballoon and statusbar messages are displayed and should return a trueor false value to indicate whether you want the balloon to be displayedor not. This also lets you control where the balloon is positioned byreturning a true value that looks like X,Y (matches this regularexpression: /^(\d+),(\d+)$/). If the postcommand returns a value thatmatches that re then those coordinates will be used as the position topost the balloon. Warning: this subroutine should return quickly orthe balloon response will appear slow.
-cancelcommand: This option takes a CODE reference which will be executed before theballoon and statusbar messages are canceled and should return a trueor false value to indicate whether you want the balloon to be canceledor not. Warning: this subroutine should return quickly or the balloonresponse will appear slow.
-motioncommand: This option takes a CODE reference which will be executed for anymotion event and should return a true or false value to indicatewhether the currently displayed balloon should be canceled (deactivated).If it returns true then the balloon will definitely be canceled, if itreturns false then it may still be canceled depending the internal rules.Note: a new balloon may be posted after the -initwait timeinterval, use the -postcommand option to control that behavior.Warning: the subroutine should be extremely fast or the balloonresponse will appear slow and consume a lot of CPU time (it is executedevery time the mouse moves over the widgets the balloon is attached to).

METHODS

The Balloon widget supports only three non-standard methods:

attach(widget, options)

Attaches the widget indicated by widget to the help system. Theallowed options are:

-statusmsg: The argument is the message to be shown on the status bar when themouse pauses over this client. If this is not specified, but-msg is specified then the message displayed on the status baris the same as the argument for -msg. If you give it a scalarreference then it is dereferenced before being displayed. Usefulif the postcommand is used to change the message.
-balloonmsg: The argument is the message to be displayed in the balloon thatwill be popped up when the mouse pauses over this client. As with-statusmsg if this is not specified, then it takes its valuefrom the -msg specification if any. If neither -balloonmsgnor -msg are specified, or they are the empty string thenno balloon is popped up instead of an empty balloon. If yougive it a scalar reference then it is dereferenced before beingdisplayed. Useful if the postcommand is used to change the message.
-msg: The catch-all for -statusmsg and -balloonmsg. This is aconvenient way of specifying the same message to be displayed inboth 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 forthose option for some of the widgets it is attached to. It accepts thesame 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 withthe distribution for examples on various ways to use balloons.

NOTES

Because of the overhead associated with each balloon you create (fromtracking the mouse movement to know when to activate and deactivatethem) you will see the best performance (low CPU consumption) if youcreate as few balloons as possible and attach them to as many widgetsas you can. In other words, don't create a balloon for each widgetyou 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 movingthe mouse a little. Creative use of the 3 command options can helpyou out also. If the mouse is over the balloon when a menu is unpostedthen the balloon will remain until you move off of it.

BUGS

Hopefully none, probably some.

AUTHORS

Rajappa Iyer rsiAATTearthling.net did the original coding.

Jason A. Smith <smithj4AATTrpi.edu> added support for menus and made someother enhancements.

Slaven Rezic <eserteAATTcs.tu-berlin.de> added support for canvas items.

HISTORY

The code and documentation was derived from Balloon.tcl from theTix4.0 distribution by Ioi Lam and modified by the above mentionedauthors. This code may be redistributed under the same terms as Perl.

Index

NAME
SYNOPSIS
DESCRIPTION
Balloons and Menus
Balloons and Canvases
OPTIONS
METHODS
attach(widget, options)
detach(widget)
destroy
EXAMPLES
NOTES
CAVEATS
BUGS
AUTHORS
HISTORY

This document was created byman2html,using the manual pages.