Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | .\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13 |
2 | .\" | |
3 | .\" Standard preamble: | |
4 | .\" ======================================================================== | |
5 | .de Sh \" Subsection heading | |
6 | .br | |
7 | .if t .Sp | |
8 | .ne 5 | |
9 | .PP | |
10 | \fB\\$1\fR | |
11 | .PP | |
12 | .. | |
13 | .de Sp \" Vertical space (when we can't use .PP) | |
14 | .if t .sp .5v | |
15 | .if n .sp | |
16 | .. | |
17 | .de Vb \" Begin verbatim text | |
18 | .ft CW | |
19 | .nf | |
20 | .ne \\$1 | |
21 | .. | |
22 | .de Ve \" End verbatim text | |
23 | .ft R | |
24 | .fi | |
25 | .. | |
26 | .\" Set up some character translations and predefined strings. \*(-- will | |
27 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left | |
28 | .\" double quote, and \*(R" will give a right double quote. | will give a | |
29 | .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to | |
30 | .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' | |
31 | .\" expand to `' in nroff, nothing in troff, for use with C<>. | |
32 | .tr \(*W-|\(bv\*(Tr | |
33 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' | |
34 | .ie n \{\ | |
35 | . ds -- \(*W- | |
36 | . ds PI pi | |
37 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch | |
38 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch | |
39 | . ds L" "" | |
40 | . ds R" "" | |
41 | . ds C` "" | |
42 | . ds C' "" | |
43 | 'br\} | |
44 | .el\{\ | |
45 | . ds -- \|\(em\| | |
46 | . ds PI \(*p | |
47 | . ds L" `` | |
48 | . ds R" '' | |
49 | 'br\} | |
50 | .\" | |
51 | .\" If the F register is turned on, we'll generate index entries on stderr for | |
52 | .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index | |
53 | .\" entries marked with X<> in POD. Of course, you'll have to process the | |
54 | .\" output yourself in some meaningful fashion. | |
55 | .if \nF \{\ | |
56 | . de IX | |
57 | . tm Index:\\$1\t\\n%\t"\\$2" | |
58 | .. | |
59 | . nr % 0 | |
60 | . rr F | |
61 | .\} | |
62 | .\" | |
63 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes | |
64 | .\" way too many mistakes in technical documents. | |
65 | .hy 0 | |
66 | .if n .na | |
67 | .\" | |
68 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). | |
69 | .\" Fear. Run. Save yourself. No user-serviceable parts. | |
70 | . \" fudge factors for nroff and troff | |
71 | .if n \{\ | |
72 | . ds #H 0 | |
73 | . ds #V .8m | |
74 | . ds #F .3m | |
75 | . ds #[ \f1 | |
76 | . ds #] \fP | |
77 | .\} | |
78 | .if t \{\ | |
79 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) | |
80 | . ds #V .6m | |
81 | . ds #F 0 | |
82 | . ds #[ \& | |
83 | . ds #] \& | |
84 | .\} | |
85 | . \" simple accents for nroff and troff | |
86 | .if n \{\ | |
87 | . ds ' \& | |
88 | . ds ` \& | |
89 | . ds ^ \& | |
90 | . ds , \& | |
91 | . ds ~ ~ | |
92 | . ds / | |
93 | .\} | |
94 | .if t \{\ | |
95 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" | |
96 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' | |
97 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' | |
98 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' | |
99 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' | |
100 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' | |
101 | .\} | |
102 | . \" troff and (daisy-wheel) nroff accents | |
103 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' | |
104 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' | |
105 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] | |
106 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' | |
107 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' | |
108 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] | |
109 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] | |
110 | .ds ae a\h'-(\w'a'u*4/10)'e | |
111 | .ds Ae A\h'-(\w'A'u*4/10)'E | |
112 | . \" corrections for vroff | |
113 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' | |
114 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' | |
115 | . \" for low resolution devices (crt and lpr) | |
116 | .if \n(.H>23 .if \n(.V>19 \ | |
117 | \{\ | |
118 | . ds : e | |
119 | . ds 8 ss | |
120 | . ds o a | |
121 | . ds d- d\h'-1'\(ga | |
122 | . ds D- D\h'-1'\(hy | |
123 | . ds th \o'bp' | |
124 | . ds Th \o'LP' | |
125 | . ds ae ae | |
126 | . ds Ae AE | |
127 | .\} | |
128 | .rm #[ #] #H #V #F C | |
129 | .\" ======================================================================== | |
130 | .\" | |
131 | .IX Title "BIND 1" | |
132 | .TH BIND 1 "2000-12-30" "perl v5.8.0" "User Contributed Perl Documentation" | |
133 | .SH "NAME" | |
134 | Tk::bind \- Arrange for X events to invoke callbacks | |
135 | .SH "SYNOPSIS" | |
136 | .IX Header "SYNOPSIS" | |
137 | Retrieve bindings: | |
138 | .PP | |
139 | \&\ \fI$widget\fR\->\fBbind\fR | |
140 | .PP | |
141 | \&\ \fI$widget\fR\->\fBbind\fR(\fItag\fR) | |
142 | .PP | |
143 | \&\ \fI$widget\fR\->\fBbind\fR(\fIsequence\fR) | |
144 | .PP | |
145 | \&\ \fI$widget\fR\->\fBbind\fR(\fItag\fR,\fIsequence\fR) | |
146 | .PP | |
147 | Associate and destroy bindings: | |
148 | .PP | |
149 | \&\ \fI$widget\fR\->\fBbind\fR(\fIsequence\fR,\fIcallback\fR) | |
150 | .PP | |
151 | \&\ \fI$widget\fR\->\fBbind\fR(\fItag\fR,\fIsequence\fR,\fIcallback\fR) | |
152 | .SH "DESCRIPTION" | |
153 | .IX Header "DESCRIPTION" | |
154 | The \fBbind\fR method associates callbacks with X events. | |
155 | If \fIcallback\fR is specified, \fBbind\fR will | |
156 | arrange for \fIcallback\fR to be evaluated whenever | |
157 | the event(s) given by \fIsequence\fR occur in the window(s) | |
158 | identified by \fI$widget\fR or \fItag\fR. | |
159 | If \fIcallback\fR is an empty string then the current binding for | |
160 | \&\fIsequence\fR is destroyed, leaving \fIsequence\fR unbound. | |
161 | In all of the cases where a \fIcallback\fR argument is provided, | |
162 | \&\fBbind\fR returns an empty string. | |
163 | .PP | |
164 | If \fIsequence\fR is specified without a \fIcallback\fR, then the | |
165 | callback currently bound to \fIsequence\fR is returned, or | |
166 | \&\fBundef\fR is returned if there is no binding for \fIsequence\fR. | |
167 | If neither \fIsequence\fR nor \fIcallback\fR is specified, then the | |
168 | return value is a list whose elements are all the sequences | |
169 | for which there exist bindings for \fItag\fR. | |
170 | .PP | |
171 | If no \fItag\fR is specified then the \fBbind\fR refers to \fI$widget\fR. | |
172 | If \fItag\fR is specified then it is typically a class name and the \fBbind\fR | |
173 | refers to all instances of the class on the \fBMainWindow\fR associated | |
174 | with \fI$widget\fR. (It is possible for \fItag\fR to be another \*(L"widget object\*(R" | |
175 | but this practice is deprecated.) Perl's \fBref\fR(\fI$object\fR) can be used | |
176 | to get the class name of any object. | |
177 | Each window has an associated list of tags, and a binding applies | |
178 | to a particular window if its tag is among those specified for | |
179 | the window. | |
180 | Although the \fBbindtags\fR method may be used to assign an | |
181 | arbitrary set of binding tags to a window, the default binding | |
182 | tags provide the following behavior: | |
183 | .PP | |
184 | If a tag is the name of an internal window the binding applies | |
185 | to that window. | |
186 | .PP | |
187 | If the tag is the name of a toplevel window the binding applies | |
188 | to the toplevel window and all its internal windows. | |
189 | .PP | |
190 | If the tag is the name of a class of widgets, such as \fBTk::Button\fR, | |
191 | the binding applies to all widgets in that class; | |
192 | .PP | |
193 | If \fItag\fR has the value \fBall\fR, | |
194 | the binding applies to all windows descended from the MainWindow | |
195 | of the application. | |
196 | .SH "EVENT PATTERNS" | |
197 | .IX Header "EVENT PATTERNS" | |
198 | The \fIsequence\fR argument specifies a sequence of one or more | |
199 | event patterns, with optional white space between the patterns. Each | |
200 | event pattern has the following syntax: | |
201 | .PP | |
202 | \&\ '<modifier\-modifier\-type\-detail>' | |
203 | .PP | |
204 | The entire event pattern is surrounded by angle brackets, and normally | |
205 | needs to be quoted, as angle brackets are special to perl. | |
206 | Inside the angle brackets are zero or more modifiers, an event | |
207 | type, and an extra piece of information (\fIdetail\fR) identifying | |
208 | a particular button or keysym. Any of the fields may be omitted, | |
209 | as long as at least one of \fItype\fR and \fIdetail\fR is present. | |
210 | The fields must be separated by white space or dashes. | |
211 | .PP | |
212 | A second form of pattern is used to specify a user\-defined, named virtual | |
213 | event; see Tk::event for details. It has the following syntax: | |
214 | .PP | |
215 | \&\ <<name>> | |
216 | .PP | |
217 | The entire virtual event pattern is surrounded by double angle brackets. | |
218 | Inside the angle brackets is the user-defined name of the virtual event. | |
219 | Modifiers, such as \fBShift\fR or \fBControl\fR, may not be combined with a | |
220 | virtual event to modify it. Bindings on a virtual event may be created | |
221 | before the virtual event is defined, and if the definition of a virtual | |
222 | event changes dynamically, all windows bound to that virtual event will | |
223 | respond immediately to the new definition. | |
224 | .SH "MODIFIERS" | |
225 | .IX Header "MODIFIERS" | |
226 | Modifiers consist of any of the following values: | |
227 | .PP | |
228 | .Vb 9 | |
229 | \& Control Mod2, M2 | |
230 | \& Shift Mod3, M3 | |
231 | \& Lock Mod4, M4 | |
232 | \& Button1, B1 Mod5, M5 | |
233 | \& Button2, B2 Meta, M | |
234 | \& Button3, B3 Alt | |
235 | \& Button4, B4 Double | |
236 | \& Button5, B5 Triple | |
237 | \& Mod1, M1 | |
238 | .Ve | |
239 | .PP | |
240 | Where more than one value is listed, separated by commas, the values | |
241 | are equivalent. | |
242 | Most of the modifiers have the obvious X meanings. | |
243 | For example, \fBButton1\fR requires that | |
244 | button 1 be depressed when the event occurs. | |
245 | For a binding to match a given event, the modifiers in the event | |
246 | must include all of those specified in the event pattern. | |
247 | An event may also contain additional modifiers not specified in | |
248 | the binding. | |
249 | For example, if button 1 is pressed while the shift and control keys | |
250 | are down, the pattern \fB<Control\-Button\-1>\fR will match | |
251 | the event, but \fB<Mod1\-Button\-1>\fR will not. | |
252 | If no modifiers are specified, then any combination of modifiers may | |
253 | be present in the event. | |
254 | .PP | |
255 | \&\fBMeta\fR and \fBM\fR refer to whichever of the | |
256 | \&\fBM1\fR through \fBM5\fR modifiers is associated with the meta | |
257 | key(s) on the keyboard (keysyms \fBMeta_R\fR and \fBMeta_L\fR). | |
258 | If there are no meta keys, or if they are not associated with any | |
259 | modifiers, then \fBMeta\fR and \fBM\fR will not match any events. | |
260 | Similarly, the \fBAlt\fR modifier refers to whichever modifier | |
261 | is associated with the alt key(s) on the keyboard (keysyms | |
262 | \&\fBAlt_L\fR and \fBAlt_R\fR). | |
263 | .PP | |
264 | The \fBDouble\fR and \fBTriple\fR modifiers are a convenience | |
265 | for specifying double mouse clicks and other repeated | |
266 | events. They cause a particular event pattern to be | |
267 | repeated 2 or 3 times, and also place a time and space requirement | |
268 | on the sequence: for a sequence of events to match a \fBDouble\fR | |
269 | or \fBTriple\fR pattern, all of the events must occur close together | |
270 | in time and without substantial mouse motion in between. | |
271 | For example, \fB<Double\-Button\-1>\fR | |
272 | is equivalent to \fB<Button\-1><Button\-1>\fR with the extra | |
273 | time and space requirement. | |
274 | .SH "EVENT TYPES" | |
275 | .IX Header "EVENT TYPES" | |
276 | The \fItype\fR field may be any of the standard X event types, with a | |
277 | few extra abbreviations. Below is a list of all the valid types; | |
278 | where two names appear together, they are synonyms. | |
279 | .PP | |
280 | .Vb 8 | |
281 | \& ButtonPress, Button Expose Map | |
282 | \& ButtonRelease FocusIn Motion | |
283 | \& Circulate FocusOut Property | |
284 | \& Colormap Gravity Reparent | |
285 | \& Configure KeyPress, Key Unmap | |
286 | \& Destroy KeyRelease Visibility | |
287 | \& Enter Leave Activate | |
288 | \& Deactivate | |
289 | .Ve | |
290 | .PP | |
291 | The last part of a long event specification is \fIdetail\fR. In the | |
292 | case of a \fBButtonPress\fR or \fBButtonRelease\fR event, it is the | |
293 | number of a button (1\-5). If a button number is given, then only an | |
294 | event on that particular button will match; if no button number is | |
295 | given, then an event on any button will match. Note: giving a | |
296 | specific button number is different than specifying a button modifier; | |
297 | in the first case, it refers to a button being pressed or released, | |
298 | while in the second it refers to some other button that is already | |
299 | depressed when the matching event occurs. If a button | |
300 | number is given then \fItype\fR may be omitted: if will default | |
301 | to \fBButtonPress\fR. For example, the specifier \fB<1>\fR | |
302 | is equivalent to \fB<ButtonPress\-1>\fR. | |
303 | .PP | |
304 | If the event type is \fBKeyPress\fR or \fBKeyRelease\fR, then | |
305 | \&\fIdetail\fR may be specified in the form of an X keysym. Keysyms | |
306 | are textual specifications for particular keys on the keyboard; | |
307 | they include all the alphanumeric \s-1ASCII\s0 characters (e.g. ``a'' is | |
308 | the keysym for the \s-1ASCII\s0 character ``a''), plus descriptions for | |
309 | non-alphanumeric characters (``comma'' is the keysym for the comma | |
310 | character), plus descriptions for all the non-ASCII keys on the | |
311 | keyboard (``Shift_L'' is the keysm for the left shift key, and | |
312 | ``F1'' is the keysym for the F1 function key, if it exists). The | |
313 | complete list of keysyms is not presented here; it is | |
314 | available in other X documentation and may vary from system to | |
315 | system. | |
316 | If necessary, you can use the \fB'K'\fR notation described below | |
317 | to print out the keysym name for a particular key. | |
318 | If a keysym \fIdetail\fR is given, then the | |
319 | \&\fItype\fR field may be omitted; it will default to \fBKeyPress\fR. | |
320 | For example, \fB<Control-comma>\fR is equivalent to | |
321 | \&\fB<Control-KeyPress-comma>\fR. | |
322 | .SH "BINDING CALLBACKS AND SUBSTITUTIONS" | |
323 | .IX Header "BINDING CALLBACKS AND SUBSTITUTIONS" | |
324 | The \fIcallback\fR argument to \fBbind\fR is a perl/Tk callback. | |
325 | which will be executed whenever the given event sequence occurs. | |
326 | (See Tk::callbacks for description of the possible forms.) | |
327 | \&\fICallback\fR will be associated with the same \fBMainWindow\fR | |
328 | that is associated with the \fI$widget\fR that was used to invoke | |
329 | the \fBbind\fR method, and it will run as though called from \fBMainLoop\fR. | |
330 | If \fIcallback\fR contains | |
331 | any \fBEv\fR(\fI%\fR) calls, then each \*(L"nested\*(R" \fBEv\fR(\fI%\fR) | |
332 | \&\*(L"callback\*(R" will be evaluated when the event occurs to form arguments | |
333 | to be passed to the main \fIcallback\fR. | |
334 | The replacement | |
335 | depends on the character \fI%\fR, as defined in the | |
336 | list below. Unless otherwise indicated, the | |
337 | replacement string is the numeric (decimal) value of the given field from | |
338 | the current event. Perl/Tk has enhanced this mechanism slightly compared | |
339 | to the comparable Tcl/Tk mechanism. The enhancements are not yet all | |
340 | reflected in the list below. | |
341 | Some of the substitutions are only valid for | |
342 | certain types of events; if they are used for other types of events | |
343 | the value substituted is undefined (not the same as \fBundef\fR!). | |
344 | .IP "\fB'#'\fR" 4 | |
345 | .IX Item "'#'" | |
346 | The number of the last client request processed by the server | |
347 | (the \fIserial\fR field from the event). Valid for all event | |
348 | types. | |
349 | .IP "\fB'a'\fR" 4 | |
350 | .IX Item "'a'" | |
351 | The \fIabove\fR field from the event, | |
352 | formatted as a hexadecimal number. | |
353 | Valid only for \fBConfigure\fR events. | |
354 | .IP "\fB'b'\fR" 4 | |
355 | .IX Item "'b'" | |
356 | The number of the button that was pressed or released. Valid only | |
357 | for \fBButtonPress\fR and \fBButtonRelease\fR events. | |
358 | .IP "\fB'c'\fR" 4 | |
359 | .IX Item "'c'" | |
360 | The \fIcount\fR field from the event. Valid only for \fBExpose\fR events. | |
361 | .IP "\fB'd'\fR" 4 | |
362 | .IX Item "'d'" | |
363 | The \fIdetail\fR field from the event. The \fB'd'\fR is replaced by | |
364 | a string identifying the detail. For \fBEnter\fR, | |
365 | \&\fBLeave\fR, \fBFocusIn\fR, and \fBFocusOut\fR events, | |
366 | the string will be one of the following: | |
367 | .RS 4 | |
368 | .Sp | |
369 | .Vb 4 | |
370 | \& NotifyAncestor NotifyNonlinearVirtual | |
371 | \& NotifyDetailNone NotifyPointer | |
372 | \& NotifyInferior NotifyPointerRoot | |
373 | \& NotifyNonlinear NotifyVirtual | |
374 | .Ve | |
375 | .Sp | |
376 | .RS 8 | |
377 | For events other than these, the substituted string is undefined. | |
378 | (Note that this is \fInot\fR the same as Detail part of sequence | |
379 | use to specify the event.) | |
380 | .RE | |
381 | .RE | |
382 | .RS 4 | |
383 | .RE | |
384 | .IP "\fB'f'\fR" 4 | |
385 | .IX Item "'f'" | |
386 | The \fIfocus\fR field from the event (\fB0\fR or \fB1\fR). Valid only | |
387 | for \fBEnter\fR and \fBLeave\fR events. | |
388 | .IP "\fB'h'\fR" 4 | |
389 | .IX Item "'h'" | |
390 | The \fIheight\fR field from the event. Valid only for \fBConfigure\fR, | |
391 | \&\fBExpose\fR, and \fBGraphicsExpose\fR events. | |
392 | .IP "\fB'k'\fR" 4 | |
393 | .IX Item "'k'" | |
394 | The \fIkeycode\fR field from the event. Valid only for \fBKeyPress\fR | |
395 | and \fBKeyRelease\fR events. | |
396 | .IP "\fB'm'\fR" 4 | |
397 | .IX Item "'m'" | |
398 | The \fImode\fR field from the event. The substituted string is one of | |
399 | \&\fBNotifyNormal\fR, \fBNotifyGrab\fR, \fBNotifyUngrab\fR, or | |
400 | \&\fBNotifyWhileGrabbed\fR. Valid only for \fBEnterWindow\fR, | |
401 | \&\fBFocusIn\fR, \fBFocusOut\fR, and \fBLeaveWindow\fR events. | |
402 | .IP "\fB'o'\fR" 4 | |
403 | .IX Item "'o'" | |
404 | The \fIoverride_redirect\fR field from the event. Valid only for | |
405 | \&\fBMap\fR, \fBReparent\fR, and \fBConfigure\fR events. | |
406 | .IP "\fB'p'\fR" 4 | |
407 | .IX Item "'p'" | |
408 | The \fIplace\fR field from the event, substituted as one of the | |
409 | strings \fBPlaceOnTop\fR or \fBPlaceOnBottom\fR. Valid only | |
410 | for \fBCirculate\fR events. | |
411 | .IP "\fB's'\fR" 4 | |
412 | .IX Item "'s'" | |
413 | The \fIstate\fR field from the event. For \fBButtonPress\fR, | |
414 | \&\fBButtonRelease\fR, \fBEnter\fR, \fBKeyPress\fR, \fBKeyRelease\fR, | |
415 | \&\fBLeave\fR, and \fBMotion\fR events, a decimal string | |
416 | is substituted. For \fBVisibility\fR, one of the strings | |
417 | \&\fBVisibilityUnobscured\fR, \fBVisibilityPartiallyObscured\fR, | |
418 | and \fBVisibilityFullyObscured\fR is substituted. | |
419 | .IP "\fB't'\fR" 4 | |
420 | .IX Item "'t'" | |
421 | The \fItime\fR field from the event. Valid only for events that | |
422 | contain a \fItime\fR field. | |
423 | .IP "\fB'w'\fR" 4 | |
424 | .IX Item "'w'" | |
425 | The \fIwidth\fR field from the event. Valid only for | |
426 | \&\fBConfigure\fR, \fBExpose\fR, and \fBGraphicsExpose\fR events. | |
427 | .IP "\fB'x'\fR" 4 | |
428 | .IX Item "'x'" | |
429 | The \fIx\fR field from the event. Valid only for events containing | |
430 | an \fIx\fR field. | |
431 | .IP "\fB'y'\fR" 4 | |
432 | .IX Item "'y'" | |
433 | The \fIy\fR field from the event. Valid only for events containing | |
434 | a \fIy\fR field. | |
435 | .IP "\fB'@'\fR" 4 | |
436 | .IX Item "'@'" | |
437 | The string "@\fIx,y\fR" where \fIx\fR and \fIy\fR are as above. | |
438 | Valid only for events containing \fIx\fR and \fIy\fR fields. | |
439 | This format is used my methods of \fBTk::Text\fR and similar widgets. | |
440 | .IP "\fB'A'\fR" 4 | |
441 | .IX Item "'A'" | |
442 | Substitutes the \s-1ASCII\s0 character corresponding to the event, or | |
443 | the empty string if the event doesn't correspond to an \s-1ASCII\s0 character | |
444 | (e.g. the shift key was pressed). \fBXLookupString\fR does all the | |
445 | work of translating from the event to an \s-1ASCII\s0 character. | |
446 | Valid only for \fBKeyPress\fR and \fBKeyRelease\fR events. | |
447 | .IP "\fB'B'\fR" 4 | |
448 | .IX Item "'B'" | |
449 | The \fIborder_width\fR field from the event. Valid only for | |
450 | \&\fBConfigure\fR events. | |
451 | .IP "\fB'E'\fR" 4 | |
452 | .IX Item "'E'" | |
453 | The \fIsend_event\fR field from the event. Valid for all event types. | |
454 | .IP "\fB'K'\fR" 4 | |
455 | .IX Item "'K'" | |
456 | The keysym corresponding to the event, substituted as a textual | |
457 | string. Valid only for \fBKeyPress\fR and \fBKeyRelease\fR events. | |
458 | .IP "\fB'N'\fR" 4 | |
459 | .IX Item "'N'" | |
460 | The keysym corresponding to the event, substituted as | |
461 | a decimal | |
462 | number. Valid only for \fBKeyPress\fR and \fBKeyRelease\fR events. | |
463 | .IP "\fB'R'\fR" 4 | |
464 | .IX Item "'R'" | |
465 | The \fIroot\fR window identifier from the event. Valid only for | |
466 | events containing a \fIroot\fR field. | |
467 | .IP "\fB'S'\fR" 4 | |
468 | .IX Item "'S'" | |
469 | The \fIsubwindow\fR window identifier from the event, | |
470 | as an object if it is one otherwise as a hexadecimal number. | |
471 | Valid only for events containing a \fIsubwindow\fR field. | |
472 | .IP "\fB'T'\fR" 4 | |
473 | .IX Item "'T'" | |
474 | The \fItype\fR field from the event. Valid for all event types. | |
475 | .IP "\fB'W'\fR" 4 | |
476 | .IX Item "'W'" | |
477 | The window to which the event was reported (the | |
478 | \&\f(CW$widget\fR field from the event) \- as an perl/Tk object. | |
479 | Valid for all event types. | |
480 | .IP "\fB'X'\fR" 4 | |
481 | .IX Item "'X'" | |
482 | The \fIx_root\fR field from the event. | |
483 | If a virtual-root window manager is being used then the substituted | |
484 | value is the corresponding x\-coordinate in the virtual root. | |
485 | Valid only for | |
486 | \&\fBButtonPress\fR, \fBButtonRelease\fR, \fBKeyPress\fR, \fBKeyRelease\fR, | |
487 | and \fBMotion\fR events. | |
488 | .IP "\fB'Y'\fR" 4 | |
489 | .IX Item "'Y'" | |
490 | The \fIy_root\fR field from the event. | |
491 | If a virtual-root window manager is being used then the substituted | |
492 | value is the corresponding y\-coordinate in the virtual root. | |
493 | Valid only for | |
494 | \&\fBButtonPress\fR, \fBButtonRelease\fR, \fBKeyPress\fR, \fBKeyRelease\fR, | |
495 | and \fBMotion\fR events. | |
496 | .SH "MULTIPLE MATCHES" | |
497 | .IX Header "MULTIPLE MATCHES" | |
498 | It is possible for several bindings to match a given X event. | |
499 | If the bindings are associated with different \fItag\fR's, | |
500 | then each of the bindings will be executed, in order. | |
501 | By default, a class binding will be executed first, followed | |
502 | by a binding for the widget, a binding for its toplevel, and | |
503 | an \fBall\fR binding. | |
504 | The \fBbindtags\fR method may be used to change this order for | |
505 | a particular window or to associate additional binding tags with | |
506 | the window. | |
507 | .PP | |
508 | \&\fBreturn\fR and \fBTk\->break\fR may be used inside a | |
509 | callback to control the processing of matching callbacks. | |
510 | If \fBreturn\fR is invoked, then the current callback | |
511 | is terminated but Tk will continue processing callbacks | |
512 | associated with other \fItag\fR's. | |
513 | If \fBTk\->break\fR is invoked within a callback, | |
514 | then that callback terminates and no other callbacks will be invoked | |
515 | for the event. | |
516 | (\fBTk\->break\fR is implemented via perl's \fBdie\fR with a special value | |
517 | which is \*(L"caught\*(R" by the perl/Tk \*(L"glue\*(R" code.) | |
518 | .PP | |
519 | If more than one binding matches a particular event and they | |
520 | have the same \fItag\fR, then the most specific binding | |
521 | is chosen and its callback is evaluated. | |
522 | The following tests are applied, in order, to determine which of | |
523 | several matching sequences is more specific: | |
524 | (a) an event pattern that specifies a specific button or key is more specific | |
525 | than one that doesn't; | |
526 | (b) a longer sequence (in terms of number | |
527 | of events matched) is more specific than a shorter sequence; | |
528 | (c) if the modifiers specified in one pattern are a subset of the | |
529 | modifiers in another pattern, then the pattern with more modifiers | |
530 | is more specific. | |
531 | (d) a virtual event whose physical pattern matches the sequence is less | |
532 | specific than the same physical pattern that is not associated with a | |
533 | virtual event. | |
534 | (e) given a sequence that matches two or more virtual events, one | |
535 | of the virtual events will be chosen, but the order is undefined. | |
536 | .PP | |
537 | If the matching sequences contain more than one event, then tests | |
538 | (c)\-(e) are applied in order from the most recent event to the least recent | |
539 | event in the sequences. If these tests fail to determine a winner, then the | |
540 | most recently registered sequence is the winner. | |
541 | .PP | |
542 | If there are two (or more) virtual events that are both triggered by the | |
543 | same sequence, and both of those virtual events are bound to the same window | |
544 | tag, then only one of the virtual events will be triggered, and it will | |
545 | be picked at random: | |
546 | .PP | |
547 | .Vb 5 | |
548 | \& $widget->eventAdd('<<Paste>>' => '<Control-y>'); | |
549 | \& $widget->eventAdd('<<Paste>>' => '<Button-2>'); | |
550 | \& $widget->eventAdd <<Scroll>>' => '<Button-2>'); | |
551 | \& $widget->bind('Tk::Entry','<<Paste>>',sub { print 'Paste'}); | |
552 | \& $widget->bind('Tk::Entry','<<Scroll>>', sub {print 'Scroll'}); | |
553 | .Ve | |
554 | .PP | |
555 | If the user types Control\-y, the \fB<<Paste>>\fR binding | |
556 | will be invoked, but if the user presses button 2 then one of | |
557 | either the \fB<<Paste>>\fR or the \fB<<Scroll>>\fR bindings will | |
558 | be invoked, but exactly which one gets invoked is undefined. | |
559 | .PP | |
560 | If an X event does not match any of the existing bindings, then the | |
561 | event is ignored. | |
562 | An unbound event is not considered to be an error. | |
563 | .SH "MULTI-EVENT SEQUENCES AND IGNORED EVENTS" | |
564 | .IX Header "MULTI-EVENT SEQUENCES AND IGNORED EVENTS" | |
565 | When a \fIsequence\fR specified in a \fBbind\fR method contains | |
566 | more than one event pattern, then its callback is executed whenever | |
567 | the recent events (leading up to and including the current event) | |
568 | match the given sequence. This means, for example, that if button 1 is | |
569 | clicked repeatedly the sequence \fB<Double\-ButtonPress\-1>\fR will match | |
570 | each button press but the first. | |
571 | If extraneous events that would prevent a match occur in the middle | |
572 | of an event sequence then the extraneous events are | |
573 | ignored unless they are \fBKeyPress\fR or \fBButtonPress\fR events. | |
574 | For example, \fB<Double\-ButtonPress\-1>\fR will match a sequence of | |
575 | presses of button 1, even though there will be \fBButtonRelease\fR | |
576 | events (and possibly \fBMotion\fR events) between the | |
577 | \&\fBButtonPress\fR events. | |
578 | Furthermore, a \fBKeyPress\fR event may be preceded by any number | |
579 | of other \fBKeyPress\fR events for modifier keys without the | |
580 | modifier keys preventing a match. | |
581 | For example, the event sequence \fBaB\fR will match a press of the | |
582 | \&\fBa\fR key, a release of the \fBa\fR key, a press of the \fBShift\fR | |
583 | key, and a press of the \fBb\fR key: the press of \fBShift\fR is | |
584 | ignored because it is a modifier key. | |
585 | Finally, if several \fBMotion\fR events occur in a row, only | |
586 | the last one is used for purposes of matching binding sequences. | |
587 | .SH "ERRORS" | |
588 | .IX Header "ERRORS" | |
589 | If an error occurs in executing the callback for a binding then the | |
590 | \&\fBTk::Error\fR mechanism is used to report the error. | |
591 | The \fBTk::Error\fR mechanism will be executed at same call level, | |
592 | and associated with the same \fBMainWindow\fR as | |
593 | as the callback was invoked. | |
594 | .SH "CAVEATS" | |
595 | .IX Header "CAVEATS" | |
596 | Note that for the \fBCanvas\fR widget, the call to \fBbind\fR has to be | |
597 | fully qualified. This is because there is already a bind method for | |
598 | the \fBCanvas\fR widget, which binds individual canvas tags. | |
599 | .PP | |
600 | \&\ \fI$canvas\fR\->\fBTk::bind\fR | |
601 | .SH "SEE ALSO" | |
602 | .IX Header "SEE ALSO" | |
603 | Tk::Error | |
604 | Tk::callbacks | |
605 | Tk::bindtags | |
606 | .SH "KEYWORDS" | |
607 | .IX Header "KEYWORDS" | |
608 | Event, binding |