Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | # Copyright (c) 1996 Sun Microsystems, Inc. |
2 | # See the file "license.terms" for information on usage and redistribution | |
3 | # of this file, and for a DISCLAIMER OF ALL WARRANTIES. | |
4 | # | |
5 | # | |
6 | ||
7 | =head1 NAME | |
8 | ||
9 | Tk::event - Miscellaneous event facilities: define virtual events and generate events | |
10 | ||
11 | =for category Binding Events and Callbacks | |
12 | ||
13 | =head1 SYNOPSIS | |
14 | ||
15 | I<$widget>-E<gt>B<event>I<Action>(?I<arg, arg, ...>?); | |
16 | ||
17 | =head1 DESCRIPTION | |
18 | ||
19 | The B<event>I<Action> methods provides several facilities for dealing with | |
20 | window system events, such as defining virtual events and synthesizing | |
21 | events. Virtual events are shared by all widgets of the same | |
22 | B<MainWindow>. Different L<MainWindow|Tk::MainWindow>s can have different | |
23 | virtual event. | |
24 | ||
25 | The following methods are currently supported: | |
26 | ||
27 | =over 4 | |
28 | ||
29 | =item I<$widget>-E<gt>B<eventAdd>(B<'E<lt>E<lt>>I<virtual>B<E<gt>E<gt>'>I<, sequence >?,I<sequence, ...>?) | |
30 | ||
31 | Associates the virtual event I<virtual> with the physical | |
32 | event sequence(s) given by the I<sequence> arguments, so that | |
33 | the virtual event will trigger whenever any one of the I<sequence>s | |
34 | occurs. | |
35 | I<Virtual> may be any string value and I<sequence> may have | |
36 | any of the values allowed for the I<sequence> argument to the | |
37 | L<bind|Tk::bind> method. | |
38 | If I<virtual> is already defined, the new physical event sequences | |
39 | add to the existing sequences for the event. | |
40 | ||
41 | =item I<$widget>-E<gt>B<eventDelete>(B<'E<lt>E<lt>>I<virtual>B<E<gt>E<gt>'> ?,I<sequence,> I<sequence, ...>?) | |
42 | ||
43 | Deletes each of the I<sequence>s from those associated with | |
44 | the virtual event given by I<virtual>. | |
45 | I<Virtual> may be any string value and I<sequence> may have | |
46 | any of the values allowed for the I<sequence> argument to the | |
47 | L<bind|Tk::bind> method. | |
48 | Any I<sequence>s not currently associated with I<virtual> | |
49 | are ignored. | |
50 | If no I<sequence> argument is provided, all physical event sequences | |
51 | are removed for I<virtual>, so that the virtual event will not | |
52 | trigger anymore. | |
53 | ||
54 | =item I<$widget>-E<gt>B<eventGenerate>(I<event> ?,I<option =E<gt> value, option =E<gt> value, ...>?) | |
55 | ||
56 | Generates a window event and arranges for it to be processed just as if | |
57 | it had come from the window system. | |
58 | I<$window> is a reference to the window for which the event | |
59 | will be generated. | |
60 | I<Event> provides a basic description of | |
61 | the event, such as B<E<lt>Shift-Button-2E<gt>> or B<E<lt>E<lt>PasteE<gt>E<gt>>. | |
62 | If I<Window> is empty the whole screen is meant, and coordinates | |
63 | are relative to the screen. | |
64 | I<Event> may have any of the forms allowed for the I<sequence> | |
65 | argument of the L<bind|Tk::bind> method except that it must consist | |
66 | of a single event pattern, not a sequence. | |
67 | I<Option-value> pairs may be used to specify additional | |
68 | attributes of the event, such as the x and y mouse position; | |
69 | see L<"EVENT FIELDS"> below. If the B<-when> option is not specified, the | |
70 | event is processed immediately: all of the handlers for the event | |
71 | will complete before the B<eventGenerate> method returns. | |
72 | If the B<-when> option is specified then it determines when the | |
73 | event is processed. | |
74 | ||
75 | =item I<$widget>-E<gt>B<eventInfo>(?'B<E<lt>E<lt>>I<virtual>B<E<gt>E<gt>'>?) | |
76 | ||
77 | Returns information about virtual events. | |
78 | If the B<E<lt>E<lt>>I<virtual>B<E<gt>E<gt>> argument is omitted, the return value | |
79 | is a list of all the virtual events that are currently defined. | |
80 | If B<E<lt>E<lt>>I<virtual>B<E<gt>E<gt>> is specified then the return value is | |
81 | a list whose elements are the physical event sequences currently | |
82 | defined for the given virtual event; if the virtual event is | |
83 | not defined then B<undef> is returned. | |
84 | ||
85 | =back | |
86 | ||
87 | =head1 EVENT FIELDS | |
88 | ||
89 | The following options are supported for the B<eventGenerate> | |
90 | method. These correspond to the ``%'' expansions | |
91 | allowed in binding callback for the L<bind|Tk::bind> method. | |
92 | ||
93 | =over 4 | |
94 | ||
95 | =item B<-above> => I<window> | |
96 | ||
97 | I<Window> specifies the I<above> field for the event, | |
98 | either as a window path name or as an integer window id. | |
99 | Valid for B<Configure> events. | |
100 | Corresponds to the L<%a|Tk::bind/'a'> substitution for binding scripts. | |
101 | ||
102 | =item B<-borderwidth> => I<size> | |
103 | ||
104 | I<Size> must be a screen distance; it specifies the | |
105 | I<border_width> field for the event. | |
106 | Valid for B<Configure> events. | |
107 | Corresponds to the L<%B|Tk::bind/'B'> substitution for binding scripts. | |
108 | ||
109 | =item B<-button> => I<number> | |
110 | ||
111 | I<Number> must be an integer; it specifies the I<detail> field | |
112 | for a B<ButtonPress> or B<ButtonRelease> event, overriding | |
113 | any button number provided in the base I<event> argument. | |
114 | Corresponds to the L<%b|Tk::bind/'b'> substitution for binding scripts. | |
115 | ||
116 | =item B<-count> => I<number> | |
117 | ||
118 | I<Number> must be an integer; it specifies the I<count> field | |
119 | for the event. Valid for B<Expose> events. | |
120 | Corresponds to the L<%c|Tk::bind/'c'> substitution for binding scripts. | |
121 | ||
122 | =item B<-detail> => I<detail> | |
123 | ||
124 | I<Detail> specifies the I<detail> field for the event | |
125 | and must be one of the following: | |
126 | ||
127 | =over 8 | |
128 | ||
129 | NotifyAncestor NotifyNonlinearVirtual | |
130 | NotifyDetailNone NotifyPointer | |
131 | NotifyInferior NotifyPointerRoot | |
132 | NotifyNonlinear NotifyVirtual | |
133 | ||
134 | Valid for B<Enter>, B<Leave>, B<FocusIn> and | |
135 | B<FocusOut> events. | |
136 | Corresponds to the L<%d|Tk::bind/'d'> substitution for binding scripts. | |
137 | ||
138 | =back | |
139 | ||
140 | =item B<-focus>I< boolean> | |
141 | ||
142 | I<Boolean> must be a boolean value; it specifies the I<focus> | |
143 | field for the event. | |
144 | Valid for B<Enter> and B<Leave> events. | |
145 | Corresponds to the L<%f|Tk::bind/'f'> substitution for binding scripts. | |
146 | ||
147 | =item B<-height>I< size> | |
148 | ||
149 | I<Size> must be a screen distance; it specifies the I<height> | |
150 | field for the event. Valid for B<Configure> events. | |
151 | Corresponds to the L<%h|Tk::bind/'h'> substitution for binding scripts. | |
152 | ||
153 | =item B<-keycode>I< number> | |
154 | ||
155 | I<Number> must be an integer; it specifies the I<keycode> | |
156 | field for the event. | |
157 | Valid for B<KeyPress> and B<KeyRelease> events. | |
158 | Corresponds to the L<%k|Tk::bind/'k'> substitution for binding scripts. | |
159 | ||
160 | =item B<-keysym>I< name> | |
161 | ||
162 | I<Name> must be the name of a valid keysym, such as B<g>, | |
163 | B<space>, or B<Return>; its corresponding | |
164 | keycode value is used as the I<keycode> field for event, overriding | |
165 | any detail specified in the base I<event> argument. | |
166 | Valid for B<KeyPress> and B<KeyRelease> events. | |
167 | Corresponds to the L<%K|Tk::bind/'K'> substitution for binding scripts. | |
168 | ||
169 | =item B<-mode>I< notify> | |
170 | ||
171 | I<Notify> specifies the I<mode> field for the event and must be | |
172 | one of B<NotifyNormal>, B<NotifyGrab>, B<NotifyUngrab>, or | |
173 | B<NotifyWhileGrabbed>. | |
174 | Valid for B<Enter>, B<Leave>, B<FocusIn>, and | |
175 | B<FocusOut> events. | |
176 | Corresponds to the L<%m|Tk::bind/'m'> substitution for binding scripts. | |
177 | ||
178 | =item B<-override>I< boolean> | |
179 | ||
180 | I<Boolean> must be a boolean value; it specifies the | |
181 | I<override_redirect> field for the event. | |
182 | Valid for B<Map>, B<Reparent>, and B<Configure> events. | |
183 | Corresponds to the L<%o|Tk::bind/'o'> substitution for binding scripts. | |
184 | ||
185 | =item B<-place>I< where> | |
186 | ||
187 | I<Where> specifies the I<place> field for the event; it must be | |
188 | either B<PlaceOnTop> or B<PlaceOnBottom>. | |
189 | Valid for B<Circulate> events. | |
190 | Corresponds to the L<%p|Tk::bind/'p'> substitution for binding scripts. | |
191 | ||
192 | =item B<-root>I< window> | |
193 | ||
194 | I<Window> must be either a window path name or an integer window | |
195 | identifier; it specifies the I<root> field for the event. | |
196 | Valid for B<KeyPress>, B<KeyRelease>, B<ButtonPress>, | |
197 | B<ButtonRelease>, B<Enter>, B<Leave>, and B<Motion> | |
198 | events. | |
199 | Corresponds to the L<%R|Tk::bind/'R'> substitution for binding scripts. | |
200 | ||
201 | =item B<-rootx>I< coord> | |
202 | ||
203 | I<Coord> must be a screen distance; it specifies the I<x_root> | |
204 | field for the event. | |
205 | Valid for B<KeyPress>, B<KeyRelease>, B<ButtonPress>, | |
206 | B<ButtonRelease>, B<Enter>, B<Leave>, and B<Motion> | |
207 | events. Corresponds to the L<%X|Tk::bind/'X'> substitution for binding scripts. | |
208 | ||
209 | =item B<-rooty>I< coord> | |
210 | ||
211 | I<Coord> must be a screen distance; it specifies the I<y_root> | |
212 | field for the event. | |
213 | Valid for B<KeyPress>, B<KeyRelease>, B<ButtonPress>, | |
214 | B<ButtonRelease>, B<Enter>, B<Leave>, and B<Motion> | |
215 | events. | |
216 | Corresponds to the L<%Y|Tk::bind/'Y'> substitution for binding scripts. | |
217 | ||
218 | =item B<-sendevent>I< boolean> | |
219 | ||
220 | B<Boolean> must be a boolean value; it specifies the I<send_event> | |
221 | field for the event. Valid for all events. Corresponds to the | |
222 | L<%E|Tk::bind/'E'> substitution for binding scripts. | |
223 | ||
224 | =item B<-serial>I< number> | |
225 | ||
226 | I<Number> must be an integer; it specifies the I<serial> field | |
227 | for the event. Valid for all events. | |
228 | Corresponds to the L<%#|Tk::bind/'#'> substitution for binding scripts. | |
229 | ||
230 | =item B<-state>I< state> | |
231 | ||
232 | I<State> specifies the I<state> field for the event. | |
233 | For B<KeyPress>, B<KeyRelease>, B<ButtonPress>, | |
234 | B<ButtonRelease>, B<Enter>, B<Leave>, and B<Motion> events | |
235 | it must be an integer value. | |
236 | For B<Visibility> events it must be one of B<VisibilityUnobscured>, | |
237 | B<VisibilityPartiallyObscured>, or B<VisibilityFullyObscured>. | |
238 | This option overrides any modifiers such as B<Meta> or B<Control> | |
239 | specified in the base I<event>. | |
240 | Corresponds to the L<%s|Tk::bind/'s'> substitution for binding scripts. | |
241 | ||
242 | =item B<-subwindow>I< window> | |
243 | ||
244 | I<Window> specifies the I<subwindow> field for the event, either | |
245 | as a path name for a Tk widget or as an integer window identifier. | |
246 | Valid for B<KeyPress>, B<KeyRelease>, B<ButtonPress>, | |
247 | B<ButtonRelease>, B<Enter>, B<Leave>, and B<Motion> events. | |
248 | Similar to L<%S|Tk::bind/'S'> substitution for binding scripts. | |
249 | ||
250 | =item B<-time>I< integer> | |
251 | ||
252 | I<Integer> must be an integer value; it specifies the I<time> field | |
253 | for the event. | |
254 | Valid for B<KeyPress>, B<KeyRelease>, B<ButtonPress>, | |
255 | B<ButtonRelease>, B<Enter>, B<Leave>, B<Motion>, | |
256 | and B<Property> events. | |
257 | Corresponds to the L<%t|Tk::bind/'t'> substitution for binding scripts. | |
258 | ||
259 | ||
260 | =item B<-warp>I< boolean> | |
261 | ||
262 | I<boolean> must be a boolean value; it specifies whether | |
263 | the screen pointer should be warped as well. | |
264 | Valid for B<KeyPress>, B<KeyRelease>, B<ButtonPress>, | |
265 | B<ButtonRelease>, and B<Motion> events. | |
266 | ||
267 | =item B<-width>I< size> | |
268 | ||
269 | I<Size> must be a screen distance; it specifies the I<width> field | |
270 | for the event. | |
271 | Valid for B<Configure> events. | |
272 | Corresponds to the L<%w|Tk::bind/'w'> substitution for binding scripts. | |
273 | ||
274 | =item B<-when>I< when> | |
275 | ||
276 | I<When> determines when the event will be processed; it must have one | |
277 | of the following values: | |
278 | ||
279 | =over 8 | |
280 | ||
281 | =item B<now> | |
282 | ||
283 | Process the event immediately, before the command returns. | |
284 | This also happens if the B<-when> option is omitted. | |
285 | ||
286 | =item B<tail> | |
287 | ||
288 | Place the event on perl/Tk's event queue behind any events already | |
289 | queued for this application. | |
290 | ||
291 | =item B<head> | |
292 | ||
293 | Place the event at the front of perl/Tk's event queue, so that it | |
294 | will be handled before any other events already queued. | |
295 | ||
296 | =item B<mark> | |
297 | ||
298 | Place the event at the front of perl/Tk's event queue but behind any | |
299 | other events already queued with B<-when mark>. | |
300 | This option is useful when generating a series of events that should | |
301 | be processed in order but at the front of the queue. | |
302 | ||
303 | =back | |
304 | ||
305 | =item B<-x>I< coord> | |
306 | ||
307 | I<Coord> must be a screen distance; it specifies the I<x> field | |
308 | for the event. | |
309 | Valid for B<KeyPress>, B<KeyRelease>, B<ButtonPress>, | |
310 | B<ButtonRelease>, B<Motion>, B<Enter>, B<Leave>, | |
311 | B<Expose>, B<Configure>, B<Gravity>, and B<Reparent> | |
312 | events. | |
313 | Corresponds to the the L<%x|Tk::bind/'x'> substitution for binding scripts. | |
314 | If I<Window> is empty the coordinate is relative to the | |
315 | screen, and this option corresponds to the L<%X|Tk::bind/'X'> substitution | |
316 | for binding scripts. | |
317 | ||
318 | =item B<-y>I< coord> | |
319 | ||
320 | I<Coord> must be a screen distance; it specifies the I<y> | |
321 | field for the event. | |
322 | Valid for B<KeyPress>, B<KeyRelease>, B<ButtonPress>, | |
323 | B<ButtonRelease>, B<Motion>, B<Enter>, B<Leave>, | |
324 | B<Expose>, B<Configure>, B<Gravity>, and B<Reparent> | |
325 | events. | |
326 | Corresponds to the the L<%y|Tk::bind/'y'> substitution for binding scripts. | |
327 | If I<Window> is empty the coordinate is relative to the | |
328 | screen, and this option corresponds to the L<%Y|Tk::bind/'Y'> substitution | |
329 | for binding scripts. | |
330 | ||
331 | Any options that are not specified when generating an event are filled | |
332 | with the value 0, except for I<serial>, which is filled with the | |
333 | next X event serial number. | |
334 | ||
335 | =back | |
336 | ||
337 | =head1 VIRTUAL EVENT EXAMPLES | |
338 | ||
339 | In order for a virtual event binding to trigger, two things must | |
340 | happen. First, the virtual event must be defined with the | |
341 | B<eventAdd> method. Second, a binding must be created for | |
342 | the virtual event with the B<bind> method. | |
343 | Consider the following virtual event definitions: | |
344 | ||
345 | $widget->eventAdd('<<Paste>>' => '<Control-y>'); | |
346 | $widget->eventAdd('<<Paste>>' => '<Button-2>'); | |
347 | $widget->eventAdd('<<Save>>' => '<Control-X><Control-S>'); | |
348 | $widget->eventAdd('<<Save>>' => '<Shift-F12>'); | |
349 | ||
350 | In the B<bind> method, a virtual event can be bound like any other | |
351 | builtin event type as follows: | |
352 | ||
353 | $entry->bind('Tk::Entry', '<<Paste>>' => sub { | |
354 | $entry->Insert($entry->selectionGet) }); | |
355 | ||
356 | The double angle brackets are used to specify that a virtual event is being | |
357 | bound. If the user types Control-y or presses button 2, or if | |
358 | a B<E<lt>E<lt>PasteE<gt>E<gt>> virtual event is synthesized with B<eventGenerate>, | |
359 | then the B<E<lt>E<lt>PasteE<gt>E<gt>> binding will be invoked. | |
360 | ||
361 | If a virtual binding has the exact same sequence as a separate | |
362 | physical binding, then the physical binding will take precedence. | |
363 | Consider the following example: | |
364 | ||
365 | $mw->eventAdd('<<Paste>>' => '<Control-y>','<Meta-Control-y>'); | |
366 | $mw->bind('Tk::Entry', '<Control-y>' => sub{print 'Control-y'}); | |
367 | $mw->bind('Tk::Entry', '<<Paste>>' => sub{print 'Paste'}); | |
368 | ||
369 | When the user types Control-y the B<E<lt>Control-yE<gt>> binding | |
370 | will be invoked, because a physical event is considered | |
371 | more specific than a virtual event, all other things being equal. | |
372 | However, when the user types Meta-Control-y the | |
373 | B<E<lt>E<lt>PasteE<gt>E<gt>> binding will be invoked, because the | |
374 | B<Meta> modifier in the physical pattern associated with the | |
375 | virtual binding is more specific than the B<E<lt>Control-y>E<gt> sequence for | |
376 | the physical event. | |
377 | ||
378 | Bindings on a virtual event may be created before the virtual event exists. | |
379 | Indeed, the virtual event never actually needs to be defined, for instance, | |
380 | on platforms where the specific virtual event would meaningless or | |
381 | ungeneratable. | |
382 | ||
383 | When a definition of a virtual event changes at run time, all windows | |
384 | will respond immediately to the new definition. | |
385 | Starting from the preceding example, if the following code is executed: | |
386 | ||
387 | $entry->bind(ref($entry), '<Control-y>' => undef); | |
388 | $entry->eventAdd('<<Paste>>' => '<Key-F6>'); | |
389 | ||
390 | the behavior will change such in two ways. First, the shadowed | |
391 | B<E<lt>E<lt>PasteE<gt>E<gt>> binding will emerge. | |
392 | Typing Control-y will no longer invoke the B<E<lt>Control-yE<gt>> binding, | |
393 | but instead invoke the virtual event B<E<lt>E<lt>PasteE<gt>E<gt>>. Second, | |
394 | pressing the F6 key will now also invoke the B<E<lt>E<lt>PasteE<gt>E<gt>> binding. | |
395 | ||
396 | =head1 SEE ALSO | |
397 | ||
398 | L<Tk::bind|Tk::bind> | |
399 | L<Tk::callbacks|Tk::callbacks> | |
400 | ||
401 | =head1 KEYWORDS | |
402 | ||
403 | event, binding, define, handle, virtual event | |
404 | ||
405 | =cut | |
406 |