Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | |
2 | =head1 NAME | |
3 | ||
4 | Tk::Balloon - pop up help balloons. | |
5 | ||
6 | =for pm Tixish/Balloon.pm | |
7 | ||
8 | =for category Tix Extensions | |
9 | ||
10 | =head1 SYNOPSIS | |
11 | ||
12 | use Tk::Balloon; | |
13 | ... | |
14 | $b = $top->Balloon(-statusbar => $status_bar_widget); | |
15 | ||
16 | # Normal Balloon: | |
17 | $b->attach($widget, | |
18 | -balloonmsg => "Balloon help message", | |
19 | -statusmsg => "Status bar message"); | |
20 | ||
21 | # Balloon attached to entries in a menu widget: | |
22 | $b->attach($menu, -state => 'status', | |
23 | -msg => ['first menu entry', | |
24 | 'second menu entry', | |
25 | ... | |
26 | ], | |
27 | ); | |
28 | ||
29 | # Balloon attached to individual items in a canvas widget: | |
30 | $b->attach($canvas, -balloonposition => 'mouse', | |
31 | -msg => {'item1' => 'msg1', | |
32 | 'tag2' => 'msg2', | |
33 | ... | |
34 | }, | |
35 | ); | |
36 | ||
37 | =head1 DESCRIPTION | |
38 | ||
39 | B<Balloon> provides the framework to create and attach help | |
40 | balloons to various widgets so that when the mouse pauses over the | |
41 | widget for more than a specified amount of time, a help balloon is | |
42 | popped up. | |
43 | ||
44 | =head2 Balloons and Menus | |
45 | ||
46 | If the balloon is attached to a B<Menu> widget and the message arguments | |
47 | are array references, then each element in the array will be the | |
48 | message corresponding to a menu entry. The balloon message will then | |
49 | be shown for the entry which the mouse pauses over. Otherwise it is | |
50 | assumed that the balloon is to be attached to the B<Menu> as a whole. | |
51 | You can have separate status and balloon messages just like normal | |
52 | balloons. | |
53 | ||
54 | =head2 Balloons and Canvases | |
55 | ||
56 | If the balloon is attached to a B<Canvas> widget and the message | |
57 | arguments are hash references, then each hash key should correspond to | |
58 | a canvas item ID or tag and the associated value will correspond to the | |
59 | message for that canvas item. The balloon message will then be shown for | |
60 | the current item (the one at the position of the mouse). Otherwise it is | |
61 | assumed that the balloon is to be attached to the B<Canvas> as a whole. | |
62 | You can have separate status and balloon messages just like normal | |
63 | balloons. | |
64 | ||
65 | =head1 OPTIONS | |
66 | ||
67 | B<Balloon> accepts all of the options that the B<Frame> widget | |
68 | accepts. In addition, the following options are also recognized. | |
69 | ||
70 | =over 4 | |
71 | ||
72 | =item B<-initwait> | |
73 | ||
74 | Specifies the amount of time to wait without activity before | |
75 | popping up a help balloon. Specified in milliseconds. Defaults to | |
76 | 350 milliseconds. This applies to both the popped up balloon and | |
77 | the status bar message. | |
78 | ||
79 | =item B<-state> | |
80 | ||
81 | Can be one of B<'balloon'>, B<'status'>, B<'both'> or B<'none'> | |
82 | indicating that the help balloon, status bar help, both or none | |
83 | respectively should be activated when the mouse pauses over the | |
84 | client widget. Default is B<'both'>. | |
85 | ||
86 | =item B<-statusbar> | |
87 | ||
88 | Specifies the widget used to display the status message. This | |
89 | widget should accept the B<-text> option and is typically a | |
90 | B<Label>. If the widget accepts the B<-textvariable> option and | |
91 | that option is defined then it is used instead of the B<-text> | |
92 | option. | |
93 | ||
94 | =item B<-balloonposition> | |
95 | ||
96 | Can be one of B<'widget'> or B<'mouse'>. It controls where the balloon | |
97 | will popup. B<'widget'> makes the balloon appear at the lower right | |
98 | corner of the widget it is attached to (default), and B<'mouse'> makes | |
99 | the balloon appear below and to the right of the current mouse position. | |
100 | ||
101 | =item B<-postcommand> | |
102 | ||
103 | This option takes a B<CODE> reference which will be executed before the | |
104 | balloon and statusbar messages are displayed and should return a true | |
105 | or false value to indicate whether you want the balloon to be displayed | |
106 | or not. This also lets you control where the balloon is positioned by | |
107 | returning a true value that looks like I<X,Y> (matches this regular | |
108 | expression: C</^(\d+),(\d+)$/>). If the postcommand returns a value that | |
109 | matches that re then those coordinates will be used as the position to | |
110 | post the balloon. I<Warning:> this subroutine should return quickly or | |
111 | the balloon response will appear slow. | |
112 | ||
113 | =item B<-cancelcommand> | |
114 | ||
115 | This option takes a B<CODE> reference which will be executed before the | |
116 | balloon and statusbar messages are canceled and should return a true | |
117 | or false value to indicate whether you want the balloon to be canceled | |
118 | or not. I<Warning:> this subroutine should return quickly or the balloon | |
119 | response will appear slow. | |
120 | ||
121 | =item B<-motioncommand> | |
122 | ||
123 | This option takes a B<CODE> reference which will be executed for any | |
124 | motion event and should return a true or false value to indicate | |
125 | whether the currently displayed balloon should be canceled (deactivated). | |
126 | If it returns true then the balloon will definitely be canceled, if it | |
127 | returns false then it may still be canceled depending the internal rules. | |
128 | I<Note:> a new balloon may be posted after the B<-initwait> time | |
129 | interval, use the B<-postcommand> option to control that behavior. | |
130 | I<Warning:> the subroutine should be extremely fast or the balloon | |
131 | response will appear slow and consume a lot of CPU time (it is executed | |
132 | every time the mouse moves over the widgets the balloon is attached to). | |
133 | ||
134 | =back | |
135 | ||
136 | =head1 METHODS | |
137 | ||
138 | The B<Balloon> widget supports only three non-standard methods: | |
139 | ||
140 | =head2 B<attach(>I<widget>, I<options>B<)> | |
141 | ||
142 | Attaches the widget indicated by I<widget> to the help system. The | |
143 | allowed options are: | |
144 | ||
145 | =over 4 | |
146 | ||
147 | =item B<-statusmsg> | |
148 | ||
149 | The argument is the message to be shown on the status bar when the | |
150 | mouse pauses over this client. If this is not specified, but | |
151 | B<-msg> is specified then the message displayed on the status bar | |
152 | is the same as the argument for B<-msg>. If you give it a scalar | |
153 | reference then it is dereferenced before being displayed. Useful | |
154 | if the postcommand is used to change the message. | |
155 | ||
156 | =item B<-balloonmsg> | |
157 | ||
158 | The argument is the message to be displayed in the balloon that | |
159 | will be popped up when the mouse pauses over this client. As with | |
160 | B<-statusmsg> if this is not specified, then it takes its value | |
161 | from the B<-msg> specification if any. If neither B<-balloonmsg> | |
162 | nor B<-msg> are specified, or they are the empty string then | |
163 | no balloon is popped up instead of an empty balloon. If you | |
164 | give it a scalar reference then it is dereferenced before being | |
165 | displayed. Useful if the postcommand is used to change the message. | |
166 | ||
167 | =item B<-msg> | |
168 | ||
169 | The catch-all for B<-statusmsg> and B<-balloonmsg>. This is a | |
170 | convenient way of specifying the same message to be displayed in | |
171 | both the balloon and the status bar for the client. | |
172 | ||
173 | =item B<-initwait> | |
174 | ||
175 | =item B<-state> | |
176 | ||
177 | =item B<-statusbar> | |
178 | ||
179 | =item B<-balloonposition> | |
180 | ||
181 | =item B<-postcommand> | |
182 | ||
183 | =item B<-cancelcommand> | |
184 | ||
185 | =item B<-motioncommand> | |
186 | ||
187 | These options allow you to override the balloon's default value for | |
188 | those option for some of the widgets it is attached to. It accepts the | |
189 | same values as above and will default to the B<Balloon>'s value. | |
190 | ||
191 | =back | |
192 | ||
193 | =head2 B<detach(>I<widget>B<)> | |
194 | ||
195 | Detaches the specified I<widget> from the help system. | |
196 | ||
197 | =head2 B<destroy> | |
198 | ||
199 | Destroys the specified balloon. | |
200 | ||
201 | =head1 EXAMPLES | |
202 | ||
203 | See the balloon demo included with the widget demo script that came with | |
204 | the distribution for examples on various ways to use balloons. | |
205 | ||
206 | =head1 NOTES | |
207 | ||
208 | Because of the overhead associated with each balloon you create (from | |
209 | tracking the mouse movement to know when to activate and deactivate | |
210 | them) you will see the best performance (low CPU consumption) if you | |
211 | create as few balloons as possible and attach them to as many widgets | |
212 | as you can. In other words, don't create a balloon for each widget | |
213 | you want to attach one to. | |
214 | ||
215 | =head1 CAVEATS | |
216 | ||
217 | Pressing any button will deactivate (cancel) the current balloon, | |
218 | if one exists. You can usually make the balloon reappear by moving | |
219 | the mouse a little. Creative use of the 3 command options can help | |
220 | you out also. If the mouse is over the balloon when a menu is unposted | |
221 | then the balloon will remain until you move off of it. | |
222 | ||
223 | =head1 BUGS | |
224 | ||
225 | Hopefully none, probably some. | |
226 | ||
227 | =head1 AUTHORS | |
228 | ||
229 | B<Rajappa Iyer> rsi@earthling.net did the original coding. | |
230 | ||
231 | B<Jason A. Smith> <smithj4@rpi.edu> added support for menus and made some | |
232 | other enhancements. | |
233 | ||
234 | B<Slaven Rezic> <eserte@cs.tu-berlin.de> added support for canvas items. | |
235 | ||
236 | =head1 HISTORY | |
237 | ||
238 | The code and documentation was derived from Balloon.tcl from the | |
239 | Tix4.0 distribution by Ioi Lam and modified by the above mentioned | |
240 | authors. This code may be redistributed under the same terms as Perl. | |
241 | ||
242 | =cut | |
243 |