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
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 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 Balloon Position
67 By default, the balloon pops up at the lower right side of the client.
68 If it would extend outside the lower screen border, its positioned at
69 the upper right side. If it would extend outside the right screen
70 border it's shown on the lower left side of the client. If it would
71 extend outside both the lower and the right screen border, it's
72 positioned at the upper left side of the client. Thus, the little arrow
73 always points to the attached client.
74
76 Balloon accepts all of the options that the Frame widget accepts. In
77 addition, the following options are also recognized.
78 -initwait
80 Specifies the amount of time to wait without activity before
81 popping up a help balloon. Specified in milliseconds. Defaults to
82 350 milliseconds. This applies to both the popped up balloon and
83 the status bar message.
84 -state
86 Can be one of 'balloon', 'status', 'both' or 'none' indicating that
87 the help balloon, status bar help, both or none respectively should
88 be activated when the mouse pauses over the client widget. Default
89 is 'both'.
90 -statusbar
92 Specifies the widget used to display the status message. This
93 widget should accept the -text option and is typically a Label. If
94 the widget accepts the -textvariable option and that option is
95 defined then it is used instead of the -text option.
96 -balloonposition
98 Can be one of 'widget' or 'mouse'. It controls where the balloon
99 will popup. 'widget' makes the balloon appear at the lower right
100 corner of the widget it is attached to (default), and 'mouse' makes
101 the balloon appear below and to the right of the current mouse
102 position.
103 -postcommand
105 This option takes a CODE reference which will be executed before
106 the balloon and statusbar messages are displayed and should return
107 a true or false value to indicate whether you want the balloon to
108 be displayed or not. This also lets you control where the balloon
109 is positioned by returning a true value that looks like X,Y
110 (matches this regular expression: "/^(\d+),(\d+)$/"). If the
111 postcommand returns a value that matches that re then those
112 coordinates will be used as the position to post the balloon.
113 Warning: this subroutine should return quickly or the balloon
114 response will appear slow.
115 -cancelcommand
117 This option takes a CODE reference which will be executed before
118 the balloon and statusbar messages are canceled and should return a
119 true or false value to indicate whether you want the balloon to be
120 canceled or not. Warning: this subroutine should return quickly or
121 the balloon response will appear slow.
122 -motioncommand
124 This option takes a CODE reference which will be executed for any
125 motion event and should return a true or false value to indicate
126 whether the currently displayed balloon should be canceled
127 (deactivated). If it returns true then the balloon will definitely
128 be canceled, if it returns false then it may still be canceled
129 depending the internal rules. Note: a new balloon may be posted
130 after the -initwait time interval, use the -postcommand option to
131 control that behavior. Warning: the subroutine should be extremely
132 fast or the balloon response will appear slow and consume a lot of
133 CPU time (it is executed every time the mouse moves over the
134 widgets the balloon is attached to).
135 -numscreens
137 This option accepts an integer 1 or greater. This option should be
138 used to avoid disjointed balloons across multiple screens in single
139 logical sceen (SLS) mode. This only currently works in the
140 horizontal direction. Example: If you are running dual screens in
141 SLS mode then you would set this value to 2. Default value is 1.
142
144 The Balloon widget supports only three non-standard methods:
145 attach(widget, options)
147 Attaches the widget indicated by widget to the help system. The allowed
148 options are:
149 -statusmsg
151 The argument is the message to be shown on the status bar when the
152 mouse pauses over this client. If this is not specified, but -msg
153 is specified then the message displayed on the status bar is the
154 same as the argument for -msg. If you give it a scalar reference
155 then it is dereferenced before being displayed. Useful if the
156 postcommand is used to change the message.
157 -balloonmsg
159 The argument is the message to be displayed in the balloon that
160 will be popped up when the mouse pauses over this client. As with
161 -statusmsg if this is not specified, then it takes its value from
162 the -msg specification if any. If neither -balloonmsg nor -msg are
163 specified, or they are the empty string then no balloon is popped
164 up instead of an empty balloon. If you give it a scalar reference
165 then it is dereferenced before being displayed. Useful if the
166 postcommand is used to change the message.
167 -msg
169 The catch-all for -statusmsg and -balloonmsg. This is a convenient
170 way of specifying the same message to be displayed in both the
171 balloon and the status bar for the client.
172 -initwait
174 -state
175 -statusbar
176 -balloonposition
177 -postcommand
178 -cancelcommand
179 -motioncommand
180 These options allow you to override the balloon's default value for
181 those option for some of the widgets it is attached to. It accepts
182 the same values as above and will default to the Balloon's value.
183 detach(widget)
185 Detaches the specified widget from the help system.
186 destroy
188 Destroys the specified balloon.
189
191 The balloon label is advertised as "message".
192
194 See the balloon demo included with the widget demo script that came
195 with the distribution for examples on various ways to use balloons.
196
198 Because of the overhead associated with each balloon you create (from
199 tracking the mouse movement to know when to activate and deactivate
200 them) you will see the best performance (low CPU consumption) if you
201 create as few balloons as possible and attach them to as many widgets
202 as you can. In other words, don't create a balloon for each widget you
203 want to attach one to.
204
206 Pressing any button will deactivate (cancel) the current balloon, if
207 one exists. You can usually make the balloon reappear by moving the
208 mouse a little. Creative use of the 3 command options can help you out
209 also. If the mouse is over the balloon when a menu is unposted then the
210 balloon will remain until you move off of it.
211
213 If using balloons attached to listbox entries or canvas items in a
214 scrolled widget, then the subwidget have to be used:
215 $balloon->attach($w->Subwidget("scrolled"), -msg => ...);
217
219 Rajappa Iyer <rsi@earthling.net> did the original coding.
220 Jason A. Smith <smithj4@rpi.edu> added support for menus and made some
222 other enhancements.
223 Slaven Rezic <srezic@cpan.org> added support for canvas items.
225 Gerhard Petrowitsch <gerhard@petrowitsch.de> added intelligent
227 positioning
228 Jack Dunnigan <dunniganj@cpan.org> Made positioning more intelligent
230 and added support for multiple monitors under single logical screen.
231
233 The code and documentation was derived from Balloon.tcl from the Tix4.0
234 distribution by Ioi Lam and modified by the above mentioned authors.
235 This code may be redistributed under the same terms as Perl.
236perl v5.12.0 2010-05-13 Balloon(3)