1Balloon(3)            User Contributed Perl Documentation           Balloon(3)
2
3
4

NAME

6       Tk::Balloon - pop up help balloons.
7

SYNOPSIS

9           use Tk::Balloon;
10           ...
11           $b = $top->Balloon(-statusbar => $status_bar_widget);
12
13           # Normal Balloon:
14           $b->attach($widget,
15                      -balloonmsg => "Balloon help message",
16                      -statusmsg => "Status bar message");
17
18           # Balloon attached to entries in a menu widget:
19           $b->attach($menu, -state => 'status',
20                             -msg => ['first menu entry',
21                                      'second menu entry',
22                                      ...
23                                     ],
24                     );
25
26           # Balloon attached to individual items in a canvas widget:
27           $b->attach($canvas, -balloonposition => 'mouse',
28                               -msg => {'item1' => 'msg1',
29                                        'tag2'  => 'msg2',
30                                         ...
31                                       },
32                     );
33
34           # Balloon attached to items in a listbox widget:
35           $b->attach($listbox, -balloonposition => 'mouse',
36                                -msg => ['first listbox element',
37                                         '2nd listbox element',
38                                         ...
39                                        ],
40                     );
41

DESCRIPTION

43       Balloon provides the framework to create and attach help balloons to
44       various widgets so that when the mouse pauses over the widget for more
45       than a specified amount of time, a help balloon is popped up.
46
47   Balloons and Menus or Listboxes
48       If the balloon is attached to a Menu or Listbox widget and the message
49       arguments are array references, then each element in the array will be
50       the message corresponding to a menu entry or listbox element.  The
51       balloon message will then be shown for the entry which the mouse pauses
52       over. Otherwise it is assumed that the balloon is to be attached to the
53       Menu or Listbox as a whole. You can have separate status and balloon
54       messages just like normal balloons.
55
56   Balloons and Canvases
57       If the balloon is attached to a Canvas widget and the message arguments
58       are hash references, then each hash key should correspond to a canvas
59       item ID or tag and the associated value will correspond to the message
60       for that canvas item. The balloon message will then be shown for the
61       current item (the one at the position of the mouse). Otherwise it is
62       assumed that the balloon is to be attached to the Canvas as a whole.
63       You can have separate status and balloon messages just like normal
64       balloons.
65
66   Balloons and HLists
67       If the balloon is attached to a HList widget and the message arguments
68       are hash references, then each hash key should correspond to a HList
69       path and the associated value will correspond to the message for that
70       HList item. The balloon message will then be shown for the current item
71       (the one at the position of the mouse). Otherwise it is assumed that
72       the balloon is to be attached to the HList as a whole.  You can have
73       separate status and balloon messages just like normal balloons.
74
75   Balloon Position
76       By default, the balloon pops up at the lower right side of the client.
77       If it would extend outside the lower screen border, it's positioned at
78       the upper right side. If it would extend outside the right screen
79       border it's shown on the lower left side of the client. If it would
80       extend outside both the lower and the right screen border, it's
81       positioned at the upper left side of the client. Thus, the little arrow
82       always points to the attached client.
83

OPTIONS

85       Balloon accepts all of the options that the Frame widget accepts. In
86       addition, the following options are also recognized.
87
88       -initwait
89           Specifies the amount of time to wait without activity before
90           popping up a help balloon. Specified in milliseconds. Defaults to
91           350 milliseconds. This applies to both the popped up balloon and
92           the status bar message.
93
94       -state
95           Can be one of 'balloon', 'status', 'both' or 'none' indicating that
96           the help balloon, status bar help, both or none respectively should
97           be activated when the mouse pauses over the client widget. Default
98           is 'both'.
99
100       -statusbar
101           Specifies the widget used to display the status message. This
102           widget should accept the -text option and is typically a Label. If
103           the widget accepts the -textvariable option and that option is
104           defined then it is used instead of the -text option.
105
106       -balloonposition
107           Can be one of 'widget' or 'mouse'. It controls where the balloon
108           will popup. 'widget' makes the balloon appear at the lower right
109           corner of the widget it is attached to (default), and 'mouse' makes
110           the balloon appear below and to the right of the current mouse
111           position.
112
113       -postcommand
114           This option takes a CODE reference which will be executed before
115           the balloon and statusbar messages are displayed and should return
116           a true or false value to indicate whether you want the balloon to
117           be displayed or not. This also lets you control where the balloon
118           is positioned by returning a true value that looks like X,Y
119           (matches this regular expression: "/^(\d+),(\d+)$/"). If the
120           postcommand returns a value that matches that re then those
121           coordinates will be used as the position to post the balloon.
122           Warning: this subroutine should return quickly or the balloon
123           response will appear slow.
124
125       -cancelcommand
126           This option takes a CODE reference which will be executed before
127           the balloon and statusbar messages are canceled and should return a
128           true or false value to indicate whether you want the balloon to be
129           canceled or not. Warning: this subroutine should return quickly or
130           the balloon response will appear slow.
131
132       -motioncommand
133           This option takes a CODE reference which will be executed for any
134           motion event and should return a true or false value to indicate
135           whether the currently displayed balloon should be canceled
136           (deactivated).  If it returns true then the balloon will definitely
137           be canceled, if it returns false then it may still be canceled
138           depending the internal rules.  Note: a new balloon may be posted
139           after the -initwait time interval, use the -postcommand option to
140           control that behavior.  Warning: the subroutine should be extremely
141           fast or the balloon response will appear slow and consume a lot of
142           CPU time (it is executed every time the mouse moves over the
143           widgets the balloon is attached to).
144
145       -numscreens
146           This option accepts an integer 1 or greater. This option should be
147           used to avoid disjointed balloons across multiple screens in single
148           logical sceen (SLS) mode. This only currently works in the
149           horizontal direction.  Example: If you are running dual screens in
150           SLS mode then you would set this value to 2. Default value is 1.
151

METHODS

153       The Balloon widget supports only three non-standard methods:
154
155   attach(widget, options)
156       Attaches the widget indicated by widget to the help system. The allowed
157       options are:
158
159       -statusmsg
160           The argument is the message to be shown on the status bar when the
161           mouse pauses over this client. If this is not specified, but -msg
162           is specified then the message displayed on the status bar is the
163           same as the argument for -msg. If you give it a scalar reference
164           then it is dereferenced before being displayed. Useful if the
165           postcommand is used to change the message.
166
167       -balloonmsg
168           The argument is the message to be displayed in the balloon that
169           will be popped up when the mouse pauses over this client. As with
170           -statusmsg if this is not specified, then it takes its value from
171           the -msg specification if any. If neither -balloonmsg nor -msg are
172           specified, or they are the empty string then no balloon is popped
173           up instead of an empty balloon. If you give it a scalar reference
174           then it is dereferenced before being displayed. Useful if the
175           postcommand is used to change the message.
176
177       -msg
178           The catch-all for -statusmsg and -balloonmsg. This is a convenient
179           way of specifying the same message to be displayed in both the
180           balloon and the status bar for the client.
181
182       -initwait
183       -state
184       -statusbar
185       -balloonposition
186       -postcommand
187       -cancelcommand
188       -motioncommand
189           These options allow you to override the balloon's default value for
190           those option for some of the widgets it is attached to. It accepts
191           the same values as above and will default to the Balloon's value.
192
193   detach(widget)
194       Detaches the specified widget from the help system.
195
196   destroy
197       Destroys the specified balloon.
198

ADVERTISED SUBWIDGETS

200       The balloon label is advertised as "message".
201

EXAMPLES

203       See the balloon demo included with the widget demo script that came
204       with the distribution for examples on various ways to use balloons.
205

NOTES

207       Because of the overhead associated with each balloon you create (from
208       tracking the mouse movement to know when to activate and deactivate
209       them) you will see the best performance (low CPU consumption) if you
210       create as few balloons as possible and attach them to as many widgets
211       as you can.  In other words, don't create a balloon for each widget you
212       want to attach one to.
213

CAVEATS

215       Pressing any button will deactivate (cancel) the current balloon, if
216       one exists. You can usually make the balloon reappear by moving the
217       mouse a little. Creative use of the 3 command options can help you out
218       also. If the mouse is over the balloon when a menu is unposted then the
219       balloon will remain until you move off of it.
220

BUGS

222       If using balloons attached to listbox entries or canvas items in a
223       scrolled widget, then the subwidget have to be used:
224
225           $balloon->attach($w->Subwidget("scrolled"), -msg => ...);
226

AUTHORS

228       Rajappa Iyer <rsi@earthling.net> did the original coding.
229
230       Jason A. Smith <smithj4@rpi.edu> added support for menus and made some
231       other enhancements.
232
233       Slaven Rezic <srezic@cpan.org> added support for canvas items.
234
235       Gerhard Petrowitsch <gerhard@petrowitsch.de> added intelligent
236       positioning
237
238       Jack Dunnigan <dunniganj@cpan.org> Made positioning more intelligent
239       and added support for multiple monitors under single logical screen.
240

HISTORY

242       The code and documentation was derived from Balloon.tcl from the Tix4.0
243       distribution by Ioi Lam and modified by the above mentioned authors.
244       This code may be redistributed under the same terms as Perl.
245
246
247
248perl v5.36.0                      2023-01-20                        Balloon(3)
Impressum