1Balloon(3) User Contributed Perl Documentation Balloon(3)
2
6 Tk::Balloon - pop up help balloons.
7
9 use Tk::Balloon;
10 ...
11 $b = $top->Balloon(-statusbar => $status_bar_widget);
12 # Normal Balloon:
14 $b->attach($widget,
15 -balloonmsg => "Balloon help message",
16 -statusmsg => "Status bar message");
17 # 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 # 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 # 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
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 Balloons and Menus or Listboxes
48 If the balloon is attached to a Menu or Listbox widget and the message
50 arguments are array references, then each element in the array will be
51 the message corresponding to a menu entry or listbox element. The bal‐
52 loon message will then be shown for the entry which the mouse pauses
53 over. Otherwise it is assumed that the balloon is to be attached to the
54 Menu or Listbox as a whole. You can have separate status and balloon
55 messages just like normal balloons.
56 Balloons and Canvases
58 If the balloon is attached to a Canvas widget and the message arguments
60 are hash references, then each hash key should correspond to a canvas
61 item ID or tag and the associated value will correspond to the message
62 for that canvas item. The balloon message will then be shown for the
63 current item (the one at the position of the mouse). Otherwise it is
64 assumed that the balloon is to be attached to the Canvas as a whole.
65 You can have separate status and balloon messages just like normal bal‐
66 loons.
67 Balloon Position
69 By default, the balloon pops up at the lower right side of the client.
71 If it would extend outside the lower screen border, its positioned at
72 the upper right side. If it would extend outside the right screen bor‐
73 der it's shown on the lower left side of the client. If it would extend
74 outside both the lower and the right screen border, it's positioned at
75 the upper left side of the client. Thus, the little arrow always points
76 to the attached client.
77
79 Balloon accepts all of the options that the Frame widget accepts. In
80 addition, the following options are also recognized.
81 -initwait
83 Specifies the amount of time to wait without activity before pop‐
84 ping up a help balloon. Specified in milliseconds. Defaults to 350
85 milliseconds. This applies to both the popped up balloon and the
86 status bar message.
87 -state
89 Can be one of 'balloon', 'status', 'both' or 'none' indicating that
90 the help balloon, status bar help, both or none respectively should
91 be activated when the mouse pauses over the client widget. Default
92 is 'both'.
93 -statusbar
95 Specifies the widget used to display the status message. This wid‐
96 get should accept the -text option and is typically a Label. If the
97 widget accepts the -textvariable option and that option is defined
98 then it is used instead of the -text option.
99 -balloonposition
101 Can be one of 'widget' or 'mouse'. It controls where the balloon
102 will popup. 'widget' makes the balloon appear at the lower right
103 corner of the widget it is attached to (default), and 'mouse' makes
104 the balloon appear below and to the right of the current mouse
105 position.
106 -postcommand
108 This option takes a CODE reference which will be executed before
109 the balloon and statusbar messages are displayed and should return
110 a true or false value to indicate whether you want the balloon to
111 be displayed or not. This also lets you control where the balloon
112 is positioned by returning a true value that looks like X,Y
113 (matches this regular expression: "/^(\d+),(\d+)$/"). If the post‐
114 command returns a value that matches that re then those coordinates
115 will be used as the position to post the balloon. Warning: this
116 subroutine should return quickly or the balloon response will
117 appear slow.
118 -cancelcommand
120 This option takes a CODE reference which will be executed before
121 the balloon and statusbar messages are canceled and should return a
122 true or false value to indicate whether you want the balloon to be
123 canceled or not. Warning: this subroutine should return quickly or
124 the balloon response will appear slow.
125 -motioncommand
127 This option takes a CODE reference which will be executed for any
128 motion event and should return a true or false value to indicate
129 whether the currently displayed balloon should be canceled (deacti‐
130 vated). If it returns true then the balloon will definitely be
131 canceled, if it returns false then it may still be canceled depend‐
132 ing the internal rules. Note: a new balloon may be posted after
133 the -initwait time interval, use the -postcommand option to control
134 that behavior. Warning: the subroutine should be extremely fast or
135 the balloon response will appear slow and consume a lot of CPU time
136 (it is executed every time the mouse moves over the widgets the
137 balloon is attached to).
138 -numscreens
140 This option accepts an integer 1 or greater. This option should be
141 used to avoid disjointed balloons across multiple screens in single
142 logical sceen (SLS) mode. This only currently works in the horizon‐
143 tal direction. Example: If you are running dual screens in SLS
144 mode then you would set this value to 2. Default value is 1.
145
147 The Balloon widget supports only three non-standard methods:
148 attach(widget, options)
150 Attaches the widget indicated by widget to the help system. The allowed
152 options are:
153 -statusmsg
155 The argument is the message to be shown on the status bar when the
156 mouse pauses over this client. If this is not specified, but -msg
157 is specified then the message displayed on the status bar is the
158 same as the argument for -msg. If you give it a scalar reference
159 then it is dereferenced before being displayed. Useful if the post‐
160 command is used to change the message.
161 -balloonmsg
163 The argument is the message to be displayed in the balloon that
164 will be popped up when the mouse pauses over this client. As with
165 -statusmsg if this is not specified, then it takes its value from
166 the -msg specification if any. If neither -balloonmsg nor -msg are
167 specified, or they are the empty string then no balloon is popped
168 up instead of an empty balloon. If you give it a scalar reference
169 then it is dereferenced before being displayed. Useful if the post‐
170 command is used to change the message.
171 -msg
173 The catch-all for -statusmsg and -balloonmsg. This is a convenient
174 way of specifying the same message to be displayed in both the bal‐
175 loon and the status bar for the client.
176 -initwait
178 -state
179 -statusbar
180 -balloonposition
181 -postcommand
182 -cancelcommand
183 -motioncommand
184 These options allow you to override the balloon's default value for
185 those option for some of the widgets it is attached to. It accepts
186 the same values as above and will default to the Balloon's value.
187 detach(widget)
189 Detaches the specified widget from the help system.
191 destroy
193 Destroys the specified balloon.
195
197 The balloon label is advertised as "message".
198
200 See the balloon demo included with the widget demo script that came
201 with the distribution for examples on various ways to use balloons.
202
204 Because of the overhead associated with each balloon you create (from
205 tracking the mouse movement to know when to activate and deactivate
206 them) you will see the best performance (low CPU consumption) if you
207 create as few balloons as possible and attach them to as many widgets
208 as you can. In other words, don't create a balloon for each widget you
209 want to attach one to.
210
212 Pressing any button will deactivate (cancel) the current balloon, if
213 one exists. You can usually make the balloon reappear by moving the
214 mouse a little. Creative use of the 3 command options can help you out
215 also. If the mouse is over the balloon when a menu is unposted then the
216 balloon will remain until you move off of it.
217
219 If using balloons attached to listbox entries or canvas items in a
220 scrolled widget, then the subwidget have to be used:
221 $balloon->attach($w->Subwidget("scrolled"), -msg => ...);
223
225 Rajappa Iyer <rsi@earthling.net> did the original coding.
226 Jason A. Smith <smithj4@rpi.edu> added support for menus and made some
228 other enhancements.
229 Slaven Rezic <srezic@cpan.org> added support for canvas items.
231 Gerhard Petrowitsch <gerhard@petrowitsch.de> added intelligent posi‐
233 tioning
234 Jack Dunnigan <dunniganj@cpan.org> Made positioning more intelligent
236 and added support for multiple monitors under single logical screen.
237
239 The code and documentation was derived from Balloon.tcl from the Tix4.0
240 distribution by Ioi Lam and modified by the above mentioned authors.
241 This code may be redistributed under the same terms as Perl.
242perl v5.8.8 2008-02-05 Balloon(3)