Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | # Copyright (c) 1990 The Regents of the University of California. |
2 | # Copyright (c) 1994-1996 Sun Microsystems, Inc. | |
3 | # See the file "license.terms" for information on usage and redistribution | |
4 | # of this file, and for a DISCLAIMER OF ALL WARRANTIES. | |
5 | # | |
6 | # | |
7 | ||
8 | =head1 NAME | |
9 | ||
10 | Tk::bind - Arrange for X events to invoke callbacks | |
11 | ||
12 | =for category Binding Events and Callbacks | |
13 | ||
14 | =head1 SYNOPSIS | |
15 | ||
16 | Retrieve bindings: | |
17 | ||
18 | S< >I<$widget>-E<gt>B<bind> | |
19 | ||
20 | S< >I<$widget>-E<gt>B<bind>(I<tag>) | |
21 | ||
22 | S< >I<$widget>-E<gt>B<bind>(I<sequence>) | |
23 | ||
24 | S< >I<$widget>-E<gt>B<bind>(I<tag>,I<sequence>) | |
25 | ||
26 | Associate and destroy bindings: | |
27 | ||
28 | S< >I<$widget>-E<gt>B<bind>(I<sequence>,I<callback>) | |
29 | ||
30 | S< >I<$widget>-E<gt>B<bind>(I<tag>,I<sequence>,I<callback>) | |
31 | ||
32 | =head1 DESCRIPTION | |
33 | ||
34 | The B<bind> method associates callbacks with X events. | |
35 | If I<callback> is specified, B<bind> will | |
36 | arrange for I<callback> to be evaluated whenever | |
37 | the event(s) given by I<sequence> occur in the window(s) | |
38 | identified by I<$widget> or I<tag>. | |
39 | If I<callback> is an empty string then the current binding for | |
40 | I<sequence> is destroyed, leaving I<sequence> unbound. | |
41 | In all of the cases where a I<callback> argument is provided, | |
42 | B<bind> returns an empty string. | |
43 | ||
44 | If I<sequence> is specified without a I<callback>, then the | |
45 | callback currently bound to I<sequence> is returned, or | |
46 | B<undef> is returned if there is no binding for I<sequence>. | |
47 | If neither I<sequence> nor I<callback> is specified, then the | |
48 | return value is a list whose elements are all the sequences | |
49 | for which there exist bindings for I<tag>. | |
50 | ||
51 | If no I<tag> is specified then the B<bind> refers to I<$widget>. | |
52 | If I<tag> is specified then it is typically a class name and the B<bind> | |
53 | refers to all instances of the class on the B<MainWindow> associated | |
54 | with I<$widget>. (It is possible for I<tag> to be another "widget object" | |
55 | but this practice is deprecated.) Perl's B<ref>(I<$object>) can be used | |
56 | to get the class name of any object. | |
57 | Each window has an associated list of tags, and a binding applies | |
58 | to a particular window if its tag is among those specified for | |
59 | the window. | |
60 | Although the B<bindtags> method may be used to assign an | |
61 | arbitrary set of binding tags to a window, the default binding | |
62 | tags provide the following behavior: | |
63 | ||
64 | If a tag is the name of an internal window the binding applies | |
65 | to that window. | |
66 | ||
67 | If the tag is the name of a toplevel window the binding applies | |
68 | to the toplevel window and all its internal windows. | |
69 | ||
70 | If the tag is the name of a class of widgets, such as B<Tk::Button>, | |
71 | the binding applies to all widgets in that class; | |
72 | ||
73 | If I<tag> has the value B<all>, | |
74 | the binding applies to all windows descended from the MainWindow | |
75 | of the application. | |
76 | ||
77 | =head1 EVENT PATTERNS | |
78 | ||
79 | The I<sequence> argument specifies a sequence of one or more | |
80 | event patterns, with optional white space between the patterns. Each | |
81 | event pattern has the following syntax: | |
82 | ||
83 | S< >'<modifier-modifier-type-detail>' | |
84 | ||
85 | The entire event pattern is surrounded by angle brackets, and normally | |
86 | needs to be quoted, as angle brackets are special to perl. | |
87 | Inside the angle brackets are zero or more modifiers, an event | |
88 | type, and an extra piece of information (I<detail>) identifying | |
89 | a particular button or keysym. Any of the fields may be omitted, | |
90 | as long as at least one of I<type> and I<detail> is present. | |
91 | The fields must be separated by white space or dashes. | |
92 | ||
93 | A second form of pattern is used to specify a user-defined, named virtual | |
94 | event; see L<Tk::event> for details. It has the following syntax: | |
95 | ||
96 | S< ><<name>> | |
97 | ||
98 | The entire virtual event pattern is surrounded by double angle brackets. | |
99 | Inside the angle brackets is the user-defined name of the virtual event. | |
100 | Modifiers, such as B<Shift> or B<Control>, may not be combined with a | |
101 | virtual event to modify it. Bindings on a virtual event may be created | |
102 | before the virtual event is defined, and if the definition of a virtual | |
103 | event changes dynamically, all windows bound to that virtual event will | |
104 | respond immediately to the new definition. | |
105 | ||
106 | =head1 MODIFIERS | |
107 | ||
108 | Modifiers consist of any of the following values: | |
109 | ||
110 | Control Mod2, M2 | |
111 | Shift Mod3, M3 | |
112 | Lock Mod4, M4 | |
113 | Button1, B1 Mod5, M5 | |
114 | Button2, B2 Meta, M | |
115 | Button3, B3 Alt | |
116 | Button4, B4 Double | |
117 | Button5, B5 Triple | |
118 | Mod1, M1 | |
119 | ||
120 | Where more than one value is listed, separated by commas, the values | |
121 | are equivalent. | |
122 | Most of the modifiers have the obvious X meanings. | |
123 | For example, B<Button1> requires that | |
124 | button 1 be depressed when the event occurs. | |
125 | For a binding to match a given event, the modifiers in the event | |
126 | must include all of those specified in the event pattern. | |
127 | An event may also contain additional modifiers not specified in | |
128 | the binding. | |
129 | For example, if button 1 is pressed while the shift and control keys | |
130 | are down, the pattern B<E<lt>Control-Button-1E<gt>> will match | |
131 | the event, but B<E<lt>Mod1-Button-1E<gt>> will not. | |
132 | If no modifiers are specified, then any combination of modifiers may | |
133 | be present in the event. | |
134 | ||
135 | B<Meta> and B<M> refer to whichever of the | |
136 | B<M1> through B<M5> modifiers is associated with the meta | |
137 | key(s) on the keyboard (keysyms B<Meta_R> and B<Meta_L>). | |
138 | If there are no meta keys, or if they are not associated with any | |
139 | modifiers, then B<Meta> and B<M> will not match any events. | |
140 | Similarly, the B<Alt> modifier refers to whichever modifier | |
141 | is associated with the alt key(s) on the keyboard (keysyms | |
142 | B<Alt_L> and B<Alt_R>). | |
143 | ||
144 | The B<Double> and B<Triple> modifiers are a convenience | |
145 | for specifying double mouse clicks and other repeated | |
146 | events. They cause a particular event pattern to be | |
147 | repeated 2 or 3 times, and also place a time and space requirement | |
148 | on the sequence: for a sequence of events to match a B<Double> | |
149 | or B<Triple> pattern, all of the events must occur close together | |
150 | in time and without substantial mouse motion in between. | |
151 | For example, B<E<lt>Double-Button-1E<gt>> | |
152 | is equivalent to B<E<lt>Button-1E<gt>E<lt>Button-1E<gt>> with the extra | |
153 | time and space requirement. | |
154 | ||
155 | =head1 EVENT TYPES | |
156 | ||
157 | The I<type> field may be any of the standard X event types, with a | |
158 | few extra abbreviations. Below is a list of all the valid types; | |
159 | where two names appear together, they are synonyms. | |
160 | ||
161 | ButtonPress, Button Expose Map | |
162 | ButtonRelease FocusIn Motion | |
163 | Circulate FocusOut Property | |
164 | Colormap Gravity Reparent | |
165 | Configure KeyPress, Key Unmap | |
166 | Destroy KeyRelease Visibility | |
167 | Enter Leave Activate | |
168 | Deactivate | |
169 | ||
170 | The last part of a long event specification is I<detail>. In the | |
171 | case of a B<ButtonPress> or B<ButtonRelease> event, it is the | |
172 | number of a button (1-5). If a button number is given, then only an | |
173 | event on that particular button will match; if no button number is | |
174 | given, then an event on any button will match. Note: giving a | |
175 | specific button number is different than specifying a button modifier; | |
176 | in the first case, it refers to a button being pressed or released, | |
177 | while in the second it refers to some other button that is already | |
178 | depressed when the matching event occurs. If a button | |
179 | number is given then I<type> may be omitted: if will default | |
180 | to B<ButtonPress>. For example, the specifier B<E<lt>1E<gt>> | |
181 | is equivalent to B<E<lt>ButtonPress-1E<gt>>. | |
182 | ||
183 | If the event type is B<KeyPress> or B<KeyRelease>, then | |
184 | I<detail> may be specified in the form of an X keysym. Keysyms | |
185 | are textual specifications for particular keys on the keyboard; | |
186 | they include all the alphanumeric ASCII characters (e.g. ``a'' is | |
187 | the keysym for the ASCII character ``a''), plus descriptions for | |
188 | non-alphanumeric characters (``comma'' is the keysym for the comma | |
189 | character), plus descriptions for all the non-ASCII keys on the | |
190 | keyboard (``Shift_L'' is the keysm for the left shift key, and | |
191 | ``F1'' is the keysym for the F1 function key, if it exists). The | |
192 | complete list of keysyms is not presented here; it is | |
193 | available in other X documentation and may vary from system to | |
194 | system. | |
195 | If necessary, you can use the B<'K'> notation described below | |
196 | to print out the keysym name for a particular key. | |
197 | If a keysym I<detail> is given, then the | |
198 | I<type> field may be omitted; it will default to B<KeyPress>. | |
199 | For example, B<E<lt>Control-commaE<gt>> is equivalent to | |
200 | B<E<lt>Control-KeyPress-commaE<gt>>. | |
201 | ||
202 | =head1 BINDING CALLBACKS AND SUBSTITUTIONS | |
203 | ||
204 | The I<callback> argument to B<bind> is a perl/Tk callback. | |
205 | which will be executed whenever the given event sequence occurs. | |
206 | (See L<Tk::callbacks> for description of the possible forms.) | |
207 | I<Callback> will be associated with the same B<MainWindow> | |
208 | that is associated with the I<$widget> that was used to invoke | |
209 | the B<bind> method, and it will run as though called from B<MainLoop>. | |
210 | If I<callback> contains | |
211 | any B<Ev>(I<%>) calls, then each "nested" B<Ev>(I<%>) | |
212 | "callback" will be evaluated when the event occurs to form arguments | |
213 | to be passed to the main I<callback>. | |
214 | The replacement | |
215 | depends on the character I<%>, as defined in the | |
216 | list below. Unless otherwise indicated, the | |
217 | replacement string is the numeric (decimal) value of the given field from | |
218 | the current event. Perl/Tk has enhanced this mechanism slightly compared | |
219 | to the comparable Tcl/Tk mechanism. The enhancements are not yet all | |
220 | reflected in the list below. | |
221 | Some of the substitutions are only valid for | |
222 | certain types of events; if they are used for other types of events | |
223 | the value substituted is undefined (not the same as B<undef>!). | |
224 | ||
225 | =over 4 | |
226 | ||
227 | =item B<'#'> | |
228 | ||
229 | The number of the last client request processed by the server | |
230 | (the I<serial> field from the event). Valid for all event | |
231 | types. | |
232 | ||
233 | =item B<'a'> | |
234 | ||
235 | The I<above> field from the event, | |
236 | formatted as a hexadecimal number. | |
237 | Valid only for B<Configure> events. | |
238 | ||
239 | =item B<'b'> | |
240 | ||
241 | The number of the button that was pressed or released. Valid only | |
242 | for B<ButtonPress> and B<ButtonRelease> events. | |
243 | ||
244 | =item B<'c'> | |
245 | ||
246 | The I<count> field from the event. Valid only for B<Expose> events. | |
247 | ||
248 | =item B<'d'> | |
249 | ||
250 | The I<detail> field from the event. The B<'d'> is replaced by | |
251 | a string identifying the detail. For B<Enter>, | |
252 | B<Leave>, B<FocusIn>, and B<FocusOut> events, | |
253 | the string will be one of the following: | |
254 | ||
255 | =over 8 | |
256 | ||
257 | NotifyAncestor NotifyNonlinearVirtual | |
258 | NotifyDetailNone NotifyPointer | |
259 | NotifyInferior NotifyPointerRoot | |
260 | NotifyNonlinear NotifyVirtual | |
261 | ||
262 | For events other than these, the substituted string is undefined. | |
263 | (Note that this is I<not> the same as Detail part of sequence | |
264 | use to specify the event.) | |
265 | ||
266 | =back | |
267 | ||
268 | =item B<'f'> | |
269 | ||
270 | The I<focus> field from the event (B<0> or B<1>). Valid only | |
271 | for B<Enter> and B<Leave> events. | |
272 | ||
273 | =item B<'h'> | |
274 | ||
275 | The I<height> field from the event. Valid only for B<Configure>, | |
276 | B<Expose>, and B<GraphicsExpose> events. | |
277 | ||
278 | =item B<'k'> | |
279 | ||
280 | The I<keycode> field from the event. Valid only for B<KeyPress> | |
281 | and B<KeyRelease> events. | |
282 | ||
283 | =item B<'m'> | |
284 | ||
285 | The I<mode> field from the event. The substituted string is one of | |
286 | B<NotifyNormal>, B<NotifyGrab>, B<NotifyUngrab>, or | |
287 | B<NotifyWhileGrabbed>. Valid only for B<EnterWindow>, | |
288 | B<FocusIn>, B<FocusOut>, and B<LeaveWindow> events. | |
289 | ||
290 | =item B<'o'> | |
291 | ||
292 | The I<override_redirect> field from the event. Valid only for | |
293 | B<Map>, B<Reparent>, and B<Configure> events. | |
294 | ||
295 | =item B<'p'> | |
296 | ||
297 | The I<place> field from the event, substituted as one of the | |
298 | strings B<PlaceOnTop> or B<PlaceOnBottom>. Valid only | |
299 | for B<Circulate> events. | |
300 | ||
301 | =item B<'s'> | |
302 | ||
303 | The I<state> field from the event. For B<ButtonPress>, | |
304 | B<ButtonRelease>, B<Enter>, B<KeyPress>, B<KeyRelease>, | |
305 | B<Leave>, and B<Motion> events, a decimal string | |
306 | is substituted. For B<Visibility>, one of the strings | |
307 | B<VisibilityUnobscured>, B<VisibilityPartiallyObscured>, | |
308 | and B<VisibilityFullyObscured> is substituted. | |
309 | ||
310 | =item B<'t'> | |
311 | ||
312 | The I<time> field from the event. Valid only for events that | |
313 | contain a I<time> field. | |
314 | ||
315 | =item B<'w'> | |
316 | ||
317 | The I<width> field from the event. Valid only for | |
318 | B<Configure>, B<Expose>, and B<GraphicsExpose> events. | |
319 | ||
320 | =item B<'x'> | |
321 | ||
322 | The I<x> field from the event. Valid only for events containing | |
323 | an I<x> field. | |
324 | ||
325 | =item B<'y'> | |
326 | ||
327 | The I<y> field from the event. Valid only for events containing | |
328 | a I<y> field. | |
329 | ||
330 | =item B<'@'> | |
331 | ||
332 | The string "@I<x,y>" where I<x> and I<y> are as above. | |
333 | Valid only for events containing I<x> and I<y> fields. | |
334 | This format is used my methods of B<Tk::Text> and similar widgets. | |
335 | ||
336 | =item B<'A'> | |
337 | ||
338 | Substitutes the ASCII character corresponding to the event, or | |
339 | the empty string if the event doesn't correspond to an ASCII character | |
340 | (e.g. the shift key was pressed). B<XLookupString> does all the | |
341 | work of translating from the event to an ASCII character. | |
342 | Valid only for B<KeyPress> and B<KeyRelease> events. | |
343 | ||
344 | =item B<'B'> | |
345 | ||
346 | The I<border_width> field from the event. Valid only for | |
347 | B<Configure> events. | |
348 | ||
349 | =item B<'E'> | |
350 | ||
351 | The I<send_event> field from the event. Valid for all event types. | |
352 | ||
353 | =item B<'K'> | |
354 | ||
355 | The keysym corresponding to the event, substituted as a textual | |
356 | string. Valid only for B<KeyPress> and B<KeyRelease> events. | |
357 | ||
358 | =item B<'N'> | |
359 | ||
360 | The keysym corresponding to the event, substituted as | |
361 | a decimal | |
362 | number. Valid only for B<KeyPress> and B<KeyRelease> events. | |
363 | ||
364 | =item B<'R'> | |
365 | ||
366 | The I<root> window identifier from the event. Valid only for | |
367 | events containing a I<root> field. | |
368 | ||
369 | =item B<'S'> | |
370 | ||
371 | The I<subwindow> window identifier from the event, | |
372 | as an object if it is one otherwise as a hexadecimal number. | |
373 | Valid only for events containing a I<subwindow> field. | |
374 | ||
375 | =item B<'T'> | |
376 | ||
377 | The I<type> field from the event. Valid for all event types. | |
378 | ||
379 | =item B<'W'> | |
380 | ||
381 | The window to which the event was reported (the | |
382 | $widget field from the event) - as an perl/Tk object. | |
383 | Valid for all event types. | |
384 | ||
385 | =item B<'X'> | |
386 | ||
387 | The I<x_root> field from the event. | |
388 | If a virtual-root window manager is being used then the substituted | |
389 | value is the corresponding x-coordinate in the virtual root. | |
390 | Valid only for | |
391 | B<ButtonPress>, B<ButtonRelease>, B<KeyPress>, B<KeyRelease>, | |
392 | and B<Motion> events. | |
393 | ||
394 | =item B<'Y'> | |
395 | ||
396 | The I<y_root> field from the event. | |
397 | If a virtual-root window manager is being used then the substituted | |
398 | value is the corresponding y-coordinate in the virtual root. | |
399 | Valid only for | |
400 | B<ButtonPress>, B<ButtonRelease>, B<KeyPress>, B<KeyRelease>, | |
401 | and B<Motion> events. | |
402 | ||
403 | =back | |
404 | ||
405 | =head1 MULTIPLE MATCHES | |
406 | ||
407 | It is possible for several bindings to match a given X event. | |
408 | If the bindings are associated with different I<tag>'s, | |
409 | then each of the bindings will be executed, in order. | |
410 | By default, a class binding will be executed first, followed | |
411 | by a binding for the widget, a binding for its toplevel, and | |
412 | an B<all> binding. | |
413 | The B<bindtags> method may be used to change this order for | |
414 | a particular window or to associate additional binding tags with | |
415 | the window. | |
416 | ||
417 | B<return> and B<Tk-E<gt>break> may be used inside a | |
418 | callback to control the processing of matching callbacks. | |
419 | If B<return> is invoked, then the current callback | |
420 | is terminated but Tk will continue processing callbacks | |
421 | associated with other I<tag>'s. | |
422 | If B<Tk-E<gt>break> is invoked within a callback, | |
423 | then that callback terminates and no other callbacks will be invoked | |
424 | for the event. | |
425 | (B<Tk-E<gt>break> is implemented via perl's B<die> with a special value | |
426 | which is "caught" by the perl/Tk "glue" code.) | |
427 | ||
428 | If more than one binding matches a particular event and they | |
429 | have the same I<tag>, then the most specific binding | |
430 | is chosen and its callback is evaluated. | |
431 | The following tests are applied, in order, to determine which of | |
432 | several matching sequences is more specific: | |
433 | (a) an event pattern that specifies a specific button or key is more specific | |
434 | than one that doesn't; | |
435 | (b) a longer sequence (in terms of number | |
436 | of events matched) is more specific than a shorter sequence; | |
437 | (c) if the modifiers specified in one pattern are a subset of the | |
438 | modifiers in another pattern, then the pattern with more modifiers | |
439 | is more specific. | |
440 | (d) a virtual event whose physical pattern matches the sequence is less | |
441 | specific than the same physical pattern that is not associated with a | |
442 | virtual event. | |
443 | (e) given a sequence that matches two or more virtual events, one | |
444 | of the virtual events will be chosen, but the order is undefined. | |
445 | ||
446 | If the matching sequences contain more than one event, then tests | |
447 | (c)-(e) are applied in order from the most recent event to the least recent | |
448 | event in the sequences. If these tests fail to determine a winner, then the | |
449 | most recently registered sequence is the winner. | |
450 | ||
451 | If there are two (or more) virtual events that are both triggered by the | |
452 | same sequence, and both of those virtual events are bound to the same window | |
453 | tag, then only one of the virtual events will be triggered, and it will | |
454 | be picked at random: | |
455 | ||
456 | $widget->eventAdd('<<Paste>>' => '<Control-y>'); | |
457 | $widget->eventAdd('<<Paste>>' => '<Button-2>'); | |
458 | $widget->eventAdd <<Scroll>>' => '<Button-2>'); | |
459 | $widget->bind('Tk::Entry','<<Paste>>',sub { print 'Paste'}); | |
460 | $widget->bind('Tk::Entry','<<Scroll>>', sub {print 'Scroll'}); | |
461 | ||
462 | If the user types Control-y, the B<E<lt>E<lt>PasteE<gt>E<gt>> binding | |
463 | will be invoked, but if the user presses button 2 then one of | |
464 | either the B<E<lt>E<lt>PasteE<gt>E<gt>> or the B<E<lt>E<lt>ScrollE<gt>E<gt>> bindings will | |
465 | be invoked, but exactly which one gets invoked is undefined. | |
466 | ||
467 | If an X event does not match any of the existing bindings, then the | |
468 | event is ignored. | |
469 | An unbound event is not considered to be an error. | |
470 | ||
471 | =head1 MULTI-EVENT SEQUENCES AND IGNORED EVENTS | |
472 | ||
473 | When a I<sequence> specified in a B<bind> method contains | |
474 | more than one event pattern, then its callback is executed whenever | |
475 | the recent events (leading up to and including the current event) | |
476 | match the given sequence. This means, for example, that if button 1 is | |
477 | clicked repeatedly the sequence B<E<lt>Double-ButtonPress-1E<gt>> will match | |
478 | each button press but the first. | |
479 | If extraneous events that would prevent a match occur in the middle | |
480 | of an event sequence then the extraneous events are | |
481 | ignored unless they are B<KeyPress> or B<ButtonPress> events. | |
482 | For example, B<E<lt>Double-ButtonPress-1E<gt>> will match a sequence of | |
483 | presses of button 1, even though there will be B<ButtonRelease> | |
484 | events (and possibly B<Motion> events) between the | |
485 | B<ButtonPress> events. | |
486 | Furthermore, a B<KeyPress> event may be preceded by any number | |
487 | of other B<KeyPress> events for modifier keys without the | |
488 | modifier keys preventing a match. | |
489 | For example, the event sequence B<aB> will match a press of the | |
490 | B<a> key, a release of the B<a> key, a press of the B<Shift> | |
491 | key, and a press of the B<b> key: the press of B<Shift> is | |
492 | ignored because it is a modifier key. | |
493 | Finally, if several B<Motion> events occur in a row, only | |
494 | the last one is used for purposes of matching binding sequences. | |
495 | ||
496 | =head1 ERRORS | |
497 | ||
498 | If an error occurs in executing the callback for a binding then the | |
499 | B<Tk::Error> mechanism is used to report the error. | |
500 | The B<Tk::Error> mechanism will be executed at same call level, | |
501 | and associated with the same B<MainWindow> as | |
502 | as the callback was invoked. | |
503 | ||
504 | =head1 CAVEATS | |
505 | ||
506 | Note that for the B<Canvas> widget, the call to B<bind> has to be | |
507 | fully qualified. This is because there is already a bind method for | |
508 | the B<Canvas> widget, which binds individual canvas tags. | |
509 | ||
510 | S< >I<$canvas>-E<gt>B<Tk::bind> | |
511 | ||
512 | =head1 SEE ALSO | |
513 | ||
514 | L<Tk::Error|Tk::Error> | |
515 | L<Tk::callbacks|Tk::callbacks> | |
516 | L<Tk::bindtags|Tk::bindtags> | |
517 | ||
518 | =head1 KEYWORDS | |
519 | ||
520 | Event, binding | |
521 | ||
522 | =cut | |
523 |