|<B>-initwaitB>||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.|
|<B>-stateB>||Can be one of <B>balloonB>, <B>statusB>, <B>bothB> or <B>noneB> 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 <B>bothB>.|
|<B>-statusbarB>||Specifies the widget used to display the status message. This widget should accept the <B>-textB> option and is typically a <B>LabelB>. If the widget accepts the <B>-textvariableB> option and that option is defined then it is used instead of the <B>-textB> option.|
|<B>-balloonpositionB>||Can be one of <B>widgetB> or <B>mouseB>. It controls where the balloon will popup. <B>widgetB> makes the balloon appear at the lower right corner of the widget it is attached to (default), and <B>mouseB> makes the balloon appear below and to the right of the current mouse position.|
|<B>-postcommandB>||This option takes a <B>CODEB> 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.|
|<B>-cancelcommandB>||This option takes a <B>CODEB> 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.|
|<B>-motioncommandB>||This option takes a <B>CODEB> 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 <B>-initwaitB> time interval, use the <B>-postcommandB> 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).|
|<B>-numscreensB>||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.|
The <B>BalloonB> widget supports only three non-standard methods:
attach(widget, options)Attaches the widget indicated by widget to the help system. The allowed options are:
<B>-statusmsgB> 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>-msgB> is specified then the message displayed on the status bar is the same as the argument for <B>-msgB>. If you give it a scalar reference then it is dereferenced before being displayed. Useful if the postcommand is used to change the message. <B>-balloonmsgB> 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>-statusmsgB> if this is not specified, then it takes its value from the <B>-msgB> specification if any. If neither <B>-balloonmsgB> nor <B>-msgB> 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. <B>-msgB> The catch-all for <B>-statusmsgB> and <B>-balloonmsgB>. This is a convenient way of specifying the same message to be displayed in both the balloon and the status bar for the client. <B>-initwaitB> <B>-stateB> <B>-statusbarB> <B>-balloonpositionB> <B>-postcommandB> <B>-cancelcommandB> <B>-motioncommandB> These options allow you to override the balloons 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 <B>BalloonB>s value.
detach(widget)Detaches the specified widget from the help system.
destroyDestroys the specified balloon.
The balloon label is advertised as message.
See the balloon demo included with the widget demo script that came with the distribution for examples on various ways to use balloons.
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 performance (low CPU consumption) if you create as few balloons as possible and attach them to as many widgets as you can. In other words, dont create a balloon for each widget you want to attach one to.
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.
If using balloons attached to listbox entries or canvas items in a scrolled widget, then the subwidget have to be used:
$balloon->attach($w->Subwidget("scrolled"), -msg => ...);
Rajappa Iyer <email@example.com> did the original coding.
Jason A. Smith <firstname.lastname@example.org> added support for menus and made some other enhancements.
Slaven Rezic <email@example.com> added support for canvas items.
Gerhard Petrowitsch <firstname.lastname@example.org> added intelligent positioning
Jack Dunnigan <email@example.com> Made positioning more intelligent and added support for multiple monitors under single logical screen.
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 redistributed under the same terms as Perl.
|perl v5.20.3||BALLOON (3)||2013-11-15|