Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | '\" |
2 | '\" Copyright (c) 1990 The Regents of the University of California. | |
3 | '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. | |
4 | '\" Copyright (c) 1998 by Scriptics Corporation. | |
5 | '\" | |
6 | '\" See the file "license.terms" for information on usage and redistribution | |
7 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. | |
8 | '\" | |
9 | '\" RCS: @(#) $Id: bind.n,v 1.7.2.2 2004/10/28 10:19:29 dkf Exp $ | |
10 | '\" | |
11 | '\" The definitions below are for supplemental macros used in Tcl/Tk | |
12 | '\" manual entries. | |
13 | '\" | |
14 | '\" .AP type name in/out ?indent? | |
15 | '\" Start paragraph describing an argument to a library procedure. | |
16 | '\" type is type of argument (int, etc.), in/out is either "in", "out", | |
17 | '\" or "in/out" to describe whether procedure reads or modifies arg, | |
18 | '\" and indent is equivalent to second arg of .IP (shouldn't ever be | |
19 | '\" needed; use .AS below instead) | |
20 | '\" | |
21 | '\" .AS ?type? ?name? | |
22 | '\" Give maximum sizes of arguments for setting tab stops. Type and | |
23 | '\" name are examples of largest possible arguments that will be passed | |
24 | '\" to .AP later. If args are omitted, default tab stops are used. | |
25 | '\" | |
26 | '\" .BS | |
27 | '\" Start box enclosure. From here until next .BE, everything will be | |
28 | '\" enclosed in one large box. | |
29 | '\" | |
30 | '\" .BE | |
31 | '\" End of box enclosure. | |
32 | '\" | |
33 | '\" .CS | |
34 | '\" Begin code excerpt. | |
35 | '\" | |
36 | '\" .CE | |
37 | '\" End code excerpt. | |
38 | '\" | |
39 | '\" .VS ?version? ?br? | |
40 | '\" Begin vertical sidebar, for use in marking newly-changed parts | |
41 | '\" of man pages. The first argument is ignored and used for recording | |
42 | '\" the version when the .VS was added, so that the sidebars can be | |
43 | '\" found and removed when they reach a certain age. If another argument | |
44 | '\" is present, then a line break is forced before starting the sidebar. | |
45 | '\" | |
46 | '\" .VE | |
47 | '\" End of vertical sidebar. | |
48 | '\" | |
49 | '\" .DS | |
50 | '\" Begin an indented unfilled display. | |
51 | '\" | |
52 | '\" .DE | |
53 | '\" End of indented unfilled display. | |
54 | '\" | |
55 | '\" .SO | |
56 | '\" Start of list of standard options for a Tk widget. The | |
57 | '\" options follow on successive lines, in four columns separated | |
58 | '\" by tabs. | |
59 | '\" | |
60 | '\" .SE | |
61 | '\" End of list of standard options for a Tk widget. | |
62 | '\" | |
63 | '\" .OP cmdName dbName dbClass | |
64 | '\" Start of description of a specific option. cmdName gives the | |
65 | '\" option's name as specified in the class command, dbName gives | |
66 | '\" the option's name in the option database, and dbClass gives | |
67 | '\" the option's class in the option database. | |
68 | '\" | |
69 | '\" .UL arg1 arg2 | |
70 | '\" Print arg1 underlined, then print arg2 normally. | |
71 | '\" | |
72 | '\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $ | |
73 | '\" | |
74 | '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. | |
75 | .if t .wh -1.3i ^B | |
76 | .nr ^l \n(.l | |
77 | .ad b | |
78 | '\" # Start an argument description | |
79 | .de AP | |
80 | .ie !"\\$4"" .TP \\$4 | |
81 | .el \{\ | |
82 | . ie !"\\$2"" .TP \\n()Cu | |
83 | . el .TP 15 | |
84 | .\} | |
85 | .ta \\n()Au \\n()Bu | |
86 | .ie !"\\$3"" \{\ | |
87 | \&\\$1 \\fI\\$2\\fP (\\$3) | |
88 | .\".b | |
89 | .\} | |
90 | .el \{\ | |
91 | .br | |
92 | .ie !"\\$2"" \{\ | |
93 | \&\\$1 \\fI\\$2\\fP | |
94 | .\} | |
95 | .el \{\ | |
96 | \&\\fI\\$1\\fP | |
97 | .\} | |
98 | .\} | |
99 | .. | |
100 | '\" # define tabbing values for .AP | |
101 | .de AS | |
102 | .nr )A 10n | |
103 | .if !"\\$1"" .nr )A \\w'\\$1'u+3n | |
104 | .nr )B \\n()Au+15n | |
105 | .\" | |
106 | .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n | |
107 | .nr )C \\n()Bu+\\w'(in/out)'u+2n | |
108 | .. | |
109 | .AS Tcl_Interp Tcl_CreateInterp in/out | |
110 | '\" # BS - start boxed text | |
111 | '\" # ^y = starting y location | |
112 | '\" # ^b = 1 | |
113 | .de BS | |
114 | .br | |
115 | .mk ^y | |
116 | .nr ^b 1u | |
117 | .if n .nf | |
118 | .if n .ti 0 | |
119 | .if n \l'\\n(.lu\(ul' | |
120 | .if n .fi | |
121 | .. | |
122 | '\" # BE - end boxed text (draw box now) | |
123 | .de BE | |
124 | .nf | |
125 | .ti 0 | |
126 | .mk ^t | |
127 | .ie n \l'\\n(^lu\(ul' | |
128 | .el \{\ | |
129 | .\" Draw four-sided box normally, but don't draw top of | |
130 | .\" box if the box started on an earlier page. | |
131 | .ie !\\n(^b-1 \{\ | |
132 | \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' | |
133 | .\} | |
134 | .el \}\ | |
135 | \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' | |
136 | .\} | |
137 | .\} | |
138 | .fi | |
139 | .br | |
140 | .nr ^b 0 | |
141 | .. | |
142 | '\" # VS - start vertical sidebar | |
143 | '\" # ^Y = starting y location | |
144 | '\" # ^v = 1 (for troff; for nroff this doesn't matter) | |
145 | .de VS | |
146 | .if !"\\$2"" .br | |
147 | .mk ^Y | |
148 | .ie n 'mc \s12\(br\s0 | |
149 | .el .nr ^v 1u | |
150 | .. | |
151 | '\" # VE - end of vertical sidebar | |
152 | .de VE | |
153 | .ie n 'mc | |
154 | .el \{\ | |
155 | .ev 2 | |
156 | .nf | |
157 | .ti 0 | |
158 | .mk ^t | |
159 | \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' | |
160 | .sp -1 | |
161 | .fi | |
162 | .ev | |
163 | .\} | |
164 | .nr ^v 0 | |
165 | .. | |
166 | '\" # Special macro to handle page bottom: finish off current | |
167 | '\" # box/sidebar if in box/sidebar mode, then invoked standard | |
168 | '\" # page bottom macro. | |
169 | .de ^B | |
170 | .ev 2 | |
171 | 'ti 0 | |
172 | 'nf | |
173 | .mk ^t | |
174 | .if \\n(^b \{\ | |
175 | .\" Draw three-sided box if this is the box's first page, | |
176 | .\" draw two sides but no top otherwise. | |
177 | .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c | |
178 | .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c | |
179 | .\} | |
180 | .if \\n(^v \{\ | |
181 | .nr ^x \\n(^tu+1v-\\n(^Yu | |
182 | \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c | |
183 | .\} | |
184 | .bp | |
185 | 'fi | |
186 | .ev | |
187 | .if \\n(^b \{\ | |
188 | .mk ^y | |
189 | .nr ^b 2 | |
190 | .\} | |
191 | .if \\n(^v \{\ | |
192 | .mk ^Y | |
193 | .\} | |
194 | .. | |
195 | '\" # DS - begin display | |
196 | .de DS | |
197 | .RS | |
198 | .nf | |
199 | .sp | |
200 | .. | |
201 | '\" # DE - end display | |
202 | .de DE | |
203 | .fi | |
204 | .RE | |
205 | .sp | |
206 | .. | |
207 | '\" # SO - start of list of standard options | |
208 | .de SO | |
209 | .SH "STANDARD OPTIONS" | |
210 | .LP | |
211 | .nf | |
212 | .ta 5.5c 11c | |
213 | .ft B | |
214 | .. | |
215 | '\" # SE - end of list of standard options | |
216 | .de SE | |
217 | .fi | |
218 | .ft R | |
219 | .LP | |
220 | See the \\fBoptions\\fR manual entry for details on the standard options. | |
221 | .. | |
222 | '\" # OP - start of full description for a single option | |
223 | .de OP | |
224 | .LP | |
225 | .nf | |
226 | .ta 4c | |
227 | Command-Line Name: \\fB\\$1\\fR | |
228 | Database Name: \\fB\\$2\\fR | |
229 | Database Class: \\fB\\$3\\fR | |
230 | .fi | |
231 | .IP | |
232 | .. | |
233 | '\" # CS - begin code excerpt | |
234 | .de CS | |
235 | .RS | |
236 | .nf | |
237 | .ta .25i .5i .75i 1i | |
238 | .. | |
239 | '\" # CE - end code excerpt | |
240 | .de CE | |
241 | .fi | |
242 | .RE | |
243 | .. | |
244 | .de UL | |
245 | \\$1\l'|0\(ul'\\$2 | |
246 | .. | |
247 | .TH bind n 8.0 Tk "Tk Built-In Commands" | |
248 | .BS | |
249 | '\" Note: do not modify the .SH NAME line immediately below! | |
250 | .SH NAME | |
251 | bind \- Arrange for X events to invoke Tcl scripts | |
252 | .SH SYNOPSIS | |
253 | \fBbind\fI tag\fR ?\fIsequence\fR? ?\fB+\fR??\fIscript\fR? | |
254 | .BE | |
255 | ||
256 | .SH "INTRODUCTION" | |
257 | .PP | |
258 | The \fBbind\fR command associates Tcl scripts with X events. | |
259 | If all three arguments are specified, \fBbind\fR will | |
260 | arrange for \fIscript\fR (a Tcl script) to be evaluated whenever | |
261 | the event(s) given by \fIsequence\fR occur in the window(s) | |
262 | identified by \fItag\fR. | |
263 | If \fIscript\fR is prefixed with a ``+'', then it is appended to | |
264 | any existing binding for \fIsequence\fR; otherwise \fIscript\fR replaces | |
265 | any existing binding. | |
266 | If \fIscript\fR is an empty string then the current binding for | |
267 | \fIsequence\fR is destroyed, leaving \fIsequence\fR unbound. | |
268 | In all of the cases where a \fIscript\fR argument is provided, | |
269 | \fBbind\fR returns an empty string. | |
270 | .PP | |
271 | If \fIsequence\fR is specified without a \fIscript\fR, then the | |
272 | script currently bound to \fIsequence\fR is returned, or | |
273 | an empty string is returned if there is no binding for \fIsequence\fR. | |
274 | If neither \fIsequence\fR nor \fIscript\fR is specified, then the | |
275 | return value is a list whose elements are all the sequences | |
276 | for which there exist bindings for \fItag\fR. | |
277 | .PP | |
278 | The \fItag\fR argument determines which window(s) the binding applies to. | |
279 | If \fItag\fR begins with a dot, as in \fB.a.b.c\fR, then it must | |
280 | be the path name for a window; otherwise it may be an arbitrary | |
281 | string. | |
282 | Each window has an associated list of tags, and a binding applies | |
283 | to a particular window if its tag is among those specified for | |
284 | the window. | |
285 | Although the \fBbindtags\fR command may be used to assign an | |
286 | arbitrary set of binding tags to a window, the default binding | |
287 | tags provide the following behavior: | |
288 | .IP \(bu 3 | |
289 | If a tag is the name of an internal window the binding applies | |
290 | to that window. | |
291 | .IP \(bu 3 | |
292 | If the tag is the name of a toplevel window the binding applies | |
293 | to the toplevel window and all its internal windows. | |
294 | .IP \(bu 3 | |
295 | If the tag is the name of a class of widgets, such as \fBButton\fR, | |
296 | the binding applies to all widgets in that class; | |
297 | .IP \(bu 3 | |
298 | If \fItag\fR has the value \fBall\fR, | |
299 | the binding applies to all windows in the application. | |
300 | .SH "EVENT PATTERNS" | |
301 | .PP | |
302 | The \fIsequence\fR argument specifies a sequence of one or more | |
303 | event patterns, with optional white space between the patterns. Each | |
304 | .VS | |
305 | event pattern may | |
306 | take one of three forms. In the simplest case it is a single | |
307 | .VE | |
308 | printing ASCII character, such as \fBa\fR or \fB[\fR. The character | |
309 | may not be a space character or the character \fB<\fR. This form of | |
310 | pattern matches a \fBKeyPress\fR event for the particular | |
311 | character. The second form of pattern is longer but more general. | |
312 | It has the following syntax: | |
313 | .CS | |
314 | \fB<\fImodifier-modifier-type-detail\fB>\fR | |
315 | .CE | |
316 | The entire event pattern is surrounded by angle brackets. | |
317 | Inside the angle brackets are zero or more modifiers, an event | |
318 | type, and an extra piece of information (\fIdetail\fR) identifying | |
319 | a particular button or keysym. Any of the fields may be omitted, | |
320 | as long as at least one of \fItype\fR and \fIdetail\fR is present. | |
321 | The fields must be separated by white space or dashes. | |
322 | .VS | |
323 | .PP | |
324 | The third form of pattern is used to specify a user-defined, named virtual | |
325 | event. It has the following syntax: | |
326 | .CS | |
327 | \fB<<\fIname\fB>>\fR | |
328 | .CE | |
329 | The entire virtual event pattern is surrounded by double angle brackets. | |
330 | Inside the angle brackets is the user-defined name of the virtual event. | |
331 | Modifiers, such as \fBShift\fR or \fBControl\fR, may not be combined with a | |
332 | virtual event to modify it. Bindings on a virtual event may be created | |
333 | before the virtual event is defined, and if the definition of a virtual | |
334 | event changes dynamically, all windows bound to that virtual event will | |
335 | respond immediately to the new definition. | |
336 | .PP | |
337 | Some widgets (e.g. \fBmenu\fR and \fBtext\fR) issue virtual events | |
338 | when their internal state is updated in some ways. Please see the | |
339 | manual page for each widget for details. | |
340 | .VE | |
341 | .SH "MODIFIERS" | |
342 | .PP | |
343 | Modifiers consist of any of the following values: | |
344 | .DS | |
345 | .ta 6c | |
346 | \fBControl\fR \fBMod2, M2\fR | |
347 | \fBShift\fR \fBMod3, M3\fR | |
348 | \fBLock\fR \fBMod4, M4\fR | |
349 | \fBButton1, B1\fR \fBMod5, M5\fR | |
350 | \fBButton2, B2\fR \fBMeta, M\fR | |
351 | \fBButton3, B3\fR \fBAlt\fR | |
352 | \fBButton4, B4\fR \fBDouble\fR | |
353 | \fBButton5, B5\fR \fBTriple\fR | |
354 | \fBMod1, M1\fR \fBQuadruple\fR | |
355 | .DE | |
356 | Where more than one value is listed, separated by commas, the values | |
357 | are equivalent. | |
358 | Most of the modifiers have the obvious X meanings. | |
359 | For example, \fBButton1\fR requires that | |
360 | button 1 be depressed when the event occurs. | |
361 | For a binding to match a given event, the modifiers in the event | |
362 | must include all of those specified in the event pattern. | |
363 | An event may also contain additional modifiers not specified in | |
364 | the binding. | |
365 | For example, if button 1 is pressed while the shift and control keys | |
366 | are down, the pattern \fB<Control-Button-1>\fR will match | |
367 | the event, but \fB<Mod1-Button-1>\fR will not. | |
368 | If no modifiers are specified, then any combination of modifiers may | |
369 | be present in the event. | |
370 | .PP | |
371 | \fBMeta\fR and \fBM\fR refer to whichever of the | |
372 | \fBM1\fR through \fBM5\fR modifiers is associated with the Meta | |
373 | key(s) on the keyboard (keysyms \fBMeta_R\fR and \fBMeta_L\fR). | |
374 | If there are no Meta keys, or if they are not associated with any | |
375 | modifiers, then \fBMeta\fR and \fBM\fR will not match any events. | |
376 | Similarly, the \fBAlt\fR modifier refers to whichever modifier | |
377 | is associated with the alt key(s) on the keyboard (keysyms | |
378 | \fBAlt_L\fR and \fBAlt_R\fR). | |
379 | .PP | |
380 | The \fBDouble\fR, \fBTriple\fR and \fBQuadruple\fR modifiers are a | |
381 | convenience for specifying double mouse clicks and other repeated | |
382 | events. They cause a particular event pattern to be repeated 2, 3 or 4 | |
383 | times, and also place a time and space requirement on the sequence: for a | |
384 | sequence of events to match a \fBDouble\fR, \fBTriple\fR or \fBQuadruple\fR | |
385 | pattern, all of the events must occur close together in time and without | |
386 | substantial mouse motion in between. For example, \fB<Double-Button-1>\fR | |
387 | is equivalent to \fB<Button-1><Button-1>\fR with the extra time and space | |
388 | requirement. | |
389 | ||
390 | .SH "EVENT TYPES" | |
391 | .PP | |
392 | The \fItype\fR field may be any of the standard X event types, with a | |
393 | few extra abbreviations. The \fItype\fR field will also accept a | |
394 | couple non-standard X event types that were added to better support | |
395 | the Macintosh and Windows platforms. Below is a list of all the valid | |
396 | types; where two names appear together, they are synonyms. | |
397 | .DS | |
398 | .ta \w'ButtonPress, Button\0\0\0'u +\w'KeyPress, Key\0\0\0'u | |
399 | \fBActivate Destroy Map | |
400 | ButtonPress, Button Enter MapRequest | |
401 | ButtonRelease Expose Motion | |
402 | Circulate FocusIn MouseWheel | |
403 | CirculateRequest FocusOut Property | |
404 | Colormap Gravity Reparent | |
405 | Configure KeyPress, Key ResizeRequest | |
406 | ConfigureRequest KeyRelease Unmap | |
407 | Create Leave Visibility | |
408 | Deactivate\fR | |
409 | .DE | |
410 | .VS | |
411 | Most of the above events have the same fields and behaviors as events | |
412 | in the X Windowing system. You can find more detailed descriptions of | |
413 | these events in any X window programming book. A couple of the events | |
414 | are extensions to the X event system to support features unique to the | |
415 | Macintosh and Windows platforms. We provide a little more detail on | |
416 | these events here. These include: | |
417 | .IP "\fBActivate\fR, \fBDeactivate\fR" 5 | |
418 | These two events are sent to every sub-window of a toplevel when they | |
419 | change state. In addition to the focus Window, the Macintosh platform | |
420 | and Windows platforms have a notion of an active window (which often | |
421 | has but is not required to have the focus). On the Macintosh, widgets | |
422 | in the active window have a different appearance than widgets in | |
423 | deactive windows. The \fBActivate\fR event is sent to all the | |
424 | sub-windows in a toplevel when it changes from being deactive to | |
425 | active. Likewise, the \fBDeactive\fR event is sent when the window's | |
426 | state changes from active to deactive. There are no useful percent | |
427 | substitutions you would make when binding to these events. | |
428 | .IP \fBMouseWheel\fR 5 | |
429 | Some mice on the Windows platform support a mouse wheel which is used | |
430 | for scrolling documents without using the scrollbars. By rolling the | |
431 | wheel, the system will generate \fBMouseWheel\fR events that the | |
432 | application can use to scroll. On Windows, the event is | |
433 | always routed to the window that currently has focus (like \fBKey\fR | |
434 | events.) On Mac OS X, | |
435 | the event is routed to the window under the pointer. When the event | |
436 | is received you can use the \fB%D\fR substitution to get the | |
437 | \fIdelta\fR field for the event, which is a integer value describing how | |
438 | the mouse wheel has moved. The smallest value for which the | |
439 | system will report is defined by the OS. On Windows 95 & 98 machines | |
440 | this value is at least 120 before it is reported. However, higher | |
441 | resolution devices may be available in the future. On Mac OS X, the value is | |
442 | not scaled by 120, but a value of 1 corresponds to roughly one text line. | |
443 | The sign of the value determines which direction your widget should scroll. | |
444 | Positive values should scroll up and negative values should scroll down. | |
445 | .VE | |
446 | .IP "\fBKeyPress\fP, \fBKeyRelease\fP" 5 | |
447 | The \fBKeyPress\fP and \fBKeyRelease\fP events are generated | |
448 | whenever a key is pressed or released. \fBKeyPress\fP and \fBKeyRelease\fP | |
449 | events are sent to the window which currently has the keyboard focus. | |
450 | .IP "\fBButtonPress\fP, \fBButtonRelease\fP, \fBMotion\fP" 5 | |
451 | The \fBButtonPress\fP and \fBButtonRelease\fP events | |
452 | are generated when the user presses or releases a mouse button. | |
453 | \fBMotion\fP events are generated whenever the pointer is moved. | |
454 | \fBButtonPress\fP, \fBButtonRelease\fP, and \fBMotion\fP events are | |
455 | normally sent to the window containing the pointer. | |
456 | .RS | |
457 | .PP | |
458 | When a mouse button is pressed, the window containing the pointer | |
459 | automatically obtains a temporary pointer grab. | |
460 | Subsequent \fBButtonPress\fP, \fBButtonRelease\fP, and \fBMotion\fP | |
461 | events will be sent to that window, | |
462 | regardless of which window contains the pointer, | |
463 | until all buttons have been released. | |
464 | .RE | |
465 | .IP \fBConfigure\fP 5 | |
466 | A \fBConfigure\fP event is sent to a window whenever its | |
467 | size, position, or border width changes, and sometimes | |
468 | when it has changed position in the stacking order. | |
469 | .IP "\fBMap\fP, \fBUnmap\fP" 5 | |
470 | The \fBMap\fP and \fBUnmap\fP events are generated whenever the mapping | |
471 | state of a window changes. | |
472 | .RS | |
473 | .PP | |
474 | Windows are created in the unmapped state. | |
475 | Top-level windows become mapped when they transition to the | |
476 | \fBnormal\fP state, and are unmapped in the \fBwithdrawn\fP | |
477 | and \fBiconic\fP states. | |
478 | Other windows become mapped when they are placed under control | |
479 | of a geometry manager (for example \fBpack\fP or \fBgrid\fP). | |
480 | .PP | |
481 | A window is \fIviewable\fP only if it and all of its ancestors are mapped. | |
482 | Note that geometry managers typically do not map their children until | |
483 | they have been mapped themselves, and unmap all children | |
484 | when they become unmapped; hence in Tk \fBMap\fP and \fBUnmap\fP | |
485 | events indicate whether or not a window is viewable. | |
486 | .RE | |
487 | .IP \fBVisibility\fP 5 | |
488 | A window is said to be \fIobscured\fP when another window | |
489 | above it in the stacking order fully or partially overlaps it. | |
490 | \fBVisibility\fP events are generated whenever a window's | |
491 | obscurity state changes; the \fIstate\fP field (\fB%s\fP) | |
492 | specifies the new state. | |
493 | .IP \fBExpose\fP 5 | |
494 | An \fBExpose\fP event is generated whenever all or part of a | |
495 | window should be redrawn (for example, when a window is | |
496 | first mapped or if it becomes unobscured). | |
497 | It is normally not necessary for client applications to | |
498 | handle \fBExpose\fP events, since Tk handles them internally. | |
499 | .IP \fBDestroy\fP 5 | |
500 | A \fBDestroy\fP event is delivered to a window when | |
501 | it is destroyed. | |
502 | .RS | |
503 | .PP | |
504 | When the \fBDestroy\fP event is delivered | |
505 | to a widget, it is in a ``half-dead'' state: the widget still exists, | |
506 | but most operations on it will fail. | |
507 | .RE | |
508 | .IP "\fBFocusIn\fP, \fBFocusOut\fP" 5 | |
509 | The \fBFocusIn\fP and \fBFocusOut\fP events are generated | |
510 | whenever the keyboard focus changes. | |
511 | A \fBFocusOut\fP event is sent to the old focus window, | |
512 | and a \fBFocusIn\fP event is sent to the new one. | |
513 | .RS | |
514 | .PP | |
515 | In addition, | |
516 | if the old and new focus windows do not share a common parent, | |
517 | ``virtual crossing'' focus events are sent to the intermediate | |
518 | windows in the hierarchy. | |
519 | Thus a \fBFocusIn\fP event indicates | |
520 | that the target window or one of its descendants has acquired the focus, | |
521 | and a \fBFocusOut\fP event indicates that the focus | |
522 | has been changed to a window outside the target window's hierarchy. | |
523 | .PP | |
524 | The keyboard focus may be changed explicitly by a call to \fBfocus\fP, | |
525 | or implicitly by the window manager. | |
526 | .RE | |
527 | .IP "\fBEnter\fP, \fBLeave\fP" 5 | |
528 | An \fBEnter\fP event is sent to a window when the pointer | |
529 | enters that window, and a \fBLeave\fP event is sent when | |
530 | the pointer leaves it. | |
531 | .RS | |
532 | .PP | |
533 | If there is a pointer grab in effect, \fBEnter\fP and \fBLeave\fP | |
534 | events are only delivered to the window owning the grab. | |
535 | .PP | |
536 | In addition, when the pointer moves | |
537 | between two windows, \fBEnter\fP and \fBLeave\fP | |
538 | ``virtual crossing'' events are sent to intermediate windows | |
539 | in the hierarchy in the same manner as for \fBFocusIn\fP and | |
540 | \fBFocusOut\fP events. | |
541 | .RE | |
542 | .IP \fBProperty\fP | |
543 | A \fBProperty\fP event is sent to a window whenever an X property | |
544 | belonging to that window is changed or deleted. | |
545 | \fBProperty\fP events are not normally delivered to Tk applications as | |
546 | they are handled by the Tk core. | |
547 | .IP \fBColormap\fP | |
548 | A \fBColormap\fP event is generated whenever the colormap | |
549 | associated with a window has been changed, installed, or uninstalled. | |
550 | .RS | |
551 | .PP | |
552 | Widgets may be assigned a private colormap by | |
553 | specifying a \fB-colormap\fP option; the window manager | |
554 | is responsible for installing and uninstalling colormaps | |
555 | as necessary. | |
556 | .PP | |
557 | Note that Tk provides no useful details for this event type. | |
558 | .RE | |
559 | '\" The following events were added in TIP#47 | |
560 | .IP "\fBMapRequest\fP, \fBCirculateRequest\fP, \fBResizeRequest\fP, \fBConfigureRequest\fP, \fBCreate\fP" 5 | |
561 | These events are not normally delivered to Tk applications. | |
562 | They are included for completeness, to make it possible to | |
563 | write X11 window managers in Tk. | |
564 | (These events are only delivered when a client has | |
565 | selected \fBSubstructureRedirectMask\fP on a window; | |
566 | the Tk core does not use this mask.) | |
567 | .IP "\fBGravity\fP, \fBReparent\fP, \fBCirculate\fP" 5 | |
568 | The events \fBGravity\fP and \fBReparent\fP | |
569 | are not normally delivered to Tk applications. | |
570 | They are included for completeness. | |
571 | .RS | |
572 | .PP | |
573 | A \fBCirculate\fP event indicates that the window has moved | |
574 | to the top or to the bottom of the stacking order as | |
575 | a result of an \fBXCirculateSubwindows\fP protocol request. | |
576 | Note that the stacking order may be changed for other reasons | |
577 | which do not generate a \fBCirculate\fP event, and that | |
578 | Tk does not use \fBXCirculateSubwindows()\fP internally. | |
579 | This event type is included only for completeness; | |
580 | there is no reliable way to track changes to a window's | |
581 | position in the stacking order. | |
582 | .RE | |
583 | .SH "EVENT DETAILS" | |
584 | .PP | |
585 | The last part of a long event specification is \fIdetail\fR. In the | |
586 | case of a \fBButtonPress\fR or \fBButtonRelease\fR event, it is the | |
587 | number of a button (1-5). If a button number is given, then only an | |
588 | event on that particular button will match; if no button number is | |
589 | given, then an event on any button will match. Note: giving a | |
590 | specific button number is different than specifying a button modifier; | |
591 | in the first case, it refers to a button being pressed or released, | |
592 | while in the second it refers to some other button that is already | |
593 | depressed when the matching event occurs. If a button | |
594 | number is given then \fItype\fR may be omitted: if will default | |
595 | to \fBButtonPress\fR. For example, the specifier \fB<1>\fR | |
596 | is equivalent to \fB<ButtonPress-1>\fR. | |
597 | .PP | |
598 | If the event type is \fBKeyPress\fR or \fBKeyRelease\fR, then | |
599 | \fIdetail\fR may be specified in the form of an X keysym. Keysyms | |
600 | are textual specifications for particular keys on the keyboard; | |
601 | they include all the alphanumeric ASCII characters (e.g. ``a'' is | |
602 | the keysym for the ASCII character ``a''), plus descriptions for | |
603 | non-alphanumeric characters (``comma'' is the keysym for the comma | |
604 | character), plus descriptions for all the non-ASCII keys on the | |
605 | keyboard (``Shift_L'' is the keysym for the left shift key, and | |
606 | ``F1'' is the keysym for the F1 function key, if it exists). The | |
607 | complete list of keysyms is not presented here; it is | |
608 | available in other X documentation and may vary from system to | |
609 | system. | |
610 | If necessary, you can use the \fB%K\fR notation described below | |
611 | to print out the keysym name for a particular key. | |
612 | If a keysym \fIdetail\fR is given, then the | |
613 | \fItype\fR field may be omitted; it will default to \fBKeyPress\fR. | |
614 | For example, \fB<Control-comma>\fR is equivalent to | |
615 | \fB<Control-KeyPress-comma>\fR. | |
616 | .SH "BINDING SCRIPTS AND SUBSTITUTIONS" | |
617 | .PP | |
618 | The \fIscript\fR argument to \fBbind\fR is a Tcl script, | |
619 | which will be executed whenever the given event sequence occurs. | |
620 | \fICommand\fR will be executed in the same interpreter that the | |
621 | \fBbind\fR command was executed in, and it will run at global | |
622 | level (only global variables will be accessible). | |
623 | If \fIscript\fR contains | |
624 | any \fB%\fR characters, then the script will not be | |
625 | executed directly. Instead, a new script will be | |
626 | generated by replacing each \fB%\fR, and the character following | |
627 | it, with information from the current event. The replacement | |
628 | depends on the character following the \fB%\fR, as defined in the | |
629 | list below. Unless otherwise indicated, the | |
630 | replacement string is the decimal value of the given field from | |
631 | the current event. | |
632 | Some of the substitutions are only valid for | |
633 | certain types of events; if they are used for other types of events | |
634 | the value substituted is undefined. | |
635 | .IP \fB%%\fR 5 | |
636 | Replaced with a single percent. | |
637 | .IP \fB%#\fR 5 | |
638 | The number of the last client request processed by the server | |
639 | (the \fIserial\fR field from the event). Valid for all event | |
640 | types. | |
641 | .IP \fB%a\fR 5 | |
642 | The \fIabove\fR field from the event, | |
643 | formatted as a hexadecimal number. | |
644 | Valid only for \fBConfigure\fR events. | |
645 | Indicates the sibling window immediately below the receiving window | |
646 | in the stacking order, or \fB0\fP if the receiving window is at the | |
647 | bottom. | |
648 | .IP \fB%b\fR 5 | |
649 | The number of the button that was pressed or released. Valid only | |
650 | for \fBButtonPress\fR and \fBButtonRelease\fR events. | |
651 | .IP \fB%c\fR 5 | |
652 | The \fIcount\fR field from the event. Valid only for \fBExpose\fR events. | |
653 | Indicates that there are \fIcount\fP pending \fBExpose\fP events which have not | |
654 | yet been delivered to the window. | |
655 | .IP \fB%d\fR 5 | |
656 | The \fIdetail\fR field from the event. The \fB%d\fR is replaced by | |
657 | a string identifying the detail. For \fBEnter\fR, | |
658 | \fBLeave\fR, \fBFocusIn\fR, and \fBFocusOut\fR events, | |
659 | the string will be one of the following: | |
660 | .RS | |
661 | .DS | |
662 | .ta 6c | |
663 | \fBNotifyAncestor NotifyNonlinearVirtual | |
664 | NotifyDetailNone NotifyPointer | |
665 | NotifyInferior NotifyPointerRoot | |
666 | NotifyNonlinear NotifyVirtual\fR | |
667 | .DE | |
668 | For \fBConfigureRequest\fR events, the string will be one of: | |
669 | .DS | |
670 | .ta 6c | |
671 | \fBAbove Opposite | |
672 | Below None | |
673 | BottomIf TopIf\fR | |
674 | .DE | |
675 | For events other than these, the substituted string is undefined. | |
676 | .RE | |
677 | .IP \fB%f\fR 5 | |
678 | The \fIfocus\fR field from the event (\fB0\fR or \fB1\fR). Valid only | |
679 | for \fBEnter\fR and \fBLeave\fR events. \fB1\fP if the receiving | |
680 | window is the focus window or a descendant of the focus window, | |
681 | \fB0\fP otherwise. | |
682 | .IP \fB%h\fR 5 | |
683 | .VS | |
684 | The \fIheight\fR field from the event. Valid for the \fBConfigure\fR, | |
685 | \fBConfigureRequest\fR, \fBCreate\fR, \fBResizeRequest\fR, and | |
686 | \fBExpose\fR events. | |
687 | Indicates the new or requested height of the window. | |
688 | .VE | |
689 | .IP \fB%i\fR 5 | |
690 | The \fIwindow\fR field from the event, represented as a hexadecimal | |
691 | integer. Valid for all event types. | |
692 | .IP \fB%k\fR 5 | |
693 | The \fIkeycode\fR field from the event. Valid only for \fBKeyPress\fR | |
694 | and \fBKeyRelease\fR events. | |
695 | .IP \fB%m\fR 5 | |
696 | The \fImode\fR field from the event. The substituted string is one of | |
697 | \fBNotifyNormal\fR, \fBNotifyGrab\fR, \fBNotifyUngrab\fR, or | |
698 | .VS | |
699 | \fBNotifyWhileGrabbed\fR. Valid only for \fBEnter\fR, | |
700 | \fBFocusIn\fR, \fBFocusOut\fR, and \fBLeave\fR events. | |
701 | .VE | |
702 | .IP \fB%o\fR 5 | |
703 | The \fIoverride_redirect\fR field from the event. Valid only for | |
704 | \fBMap\fR, \fBReparent\fR, and \fBConfigure\fR events. | |
705 | .IP \fB%p\fR 5 | |
706 | The \fIplace\fR field from the event, substituted as one of the | |
707 | strings \fBPlaceOnTop\fR or \fBPlaceOnBottom\fR. Valid only | |
708 | for \fBCirculate\fR and \fBCirculateRequest\fR events. | |
709 | .IP \fB%s\fR 5 | |
710 | The \fIstate\fR field from the event. For \fBButtonPress\fR, | |
711 | \fBButtonRelease\fR, \fBEnter\fR, \fBKeyPress\fR, \fBKeyRelease\fR, | |
712 | \fBLeave\fR, and \fBMotion\fR events, a decimal string | |
713 | is substituted. For \fBVisibility\fR, one of the strings | |
714 | \fBVisibilityUnobscured\fR, \fBVisibilityPartiallyObscured\fR, | |
715 | and \fBVisibilityFullyObscured\fR is substituted. | |
716 | For \fBProperty\fP events, substituted with | |
717 | either the string \fBNewValue\fP (indicating that the property | |
718 | has been created or modified) or \fBDelete\fP (indicating that | |
719 | the property has been removed). | |
720 | .IP \fB%t\fR 5 | |
721 | The \fItime\fR field from the event. | |
722 | This is the X server timestamp (typically the time since | |
723 | the last server reset) in milliseconds, when the event occurred. | |
724 | Valid for most events. | |
725 | .IP \fB%w\fR 5 | |
726 | The \fIwidth\fR field from the event. | |
727 | Indicates the new or requested width of the window. | |
728 | Valid only for | |
729 | .VS | |
730 | \fBConfigure\fR, \fBConfigureRequest\fR, \fBCreate\fR, | |
731 | \fBResizeRequest\fR, and \fBExpose\fR events. | |
732 | .VE | |
733 | .IP "\fB%x\fR, \fB%y\fR" 5 | |
734 | The \fIx\fR and \fIy\fR fields from the event. | |
735 | For \fBButtonPress\fP, \fBButtonRelease\fP, \fBMotion\fP, | |
736 | \fBKeyPress\fP, \fBKeyRelease\fP, and \fBMouseWheel\fP events, | |
737 | \fB%x\fP and \fB%y\fP indicate the position of the mouse pointer | |
738 | relative to the receiving window. | |
739 | For \fBEnter\fP and \fBLeave\fP events, the position where the | |
740 | mouse pointer crossed the window, relative to the receiving window. | |
741 | For \fBConfigure\fP and \fBCreate\fP requests, the \fIx\fP and \fIy\fP | |
742 | coordinates of the window relative to its parent window. | |
743 | .IP \fB%A\fR 5 | |
744 | Substitutes the UNICODE character corresponding to the event, or | |
745 | the empty string if the event doesn't correspond to a UNICODE character | |
746 | (e.g. the shift key was pressed). \fBXmbLookupString\fR (or | |
747 | \fBXLookupString\fR when input method support is turned off) does all | |
748 | the work of translating from the event to a UNICODE character. | |
749 | Valid only for \fBKeyPress\fR and \fBKeyRelease\fR events. | |
750 | .IP \fB%B\fR 5 | |
751 | The \fIborder_width\fR field from the event. Valid only for | |
752 | \fBConfigure\fR, \fBConfigureRequest\fR, and \fBCreate\fR events. | |
753 | .IP \fB%D\fR 5 | |
754 | .VS | |
755 | This reports the \fIdelta\fR value of a \fBMouseWheel\fR event. The | |
756 | \fIdelta\fR value represents the rotation units the mouse wheel has | |
757 | been moved. On Windows 95 & 98 systems the smallest value for the | |
758 | delta is 120. Future systems may support higher resolution values for | |
759 | the delta. The sign of the value represents the direction the mouse | |
760 | wheel was scrolled. | |
761 | .VE | |
762 | .IP \fB%E\fR 5 | |
763 | The \fIsend_event\fR field from the event. Valid for all event types. | |
764 | \fB0\fP indicates that this is a ``normal'' event, \fB1\fP indicates | |
765 | that it is a ``synthetic'' event generated by \fBSendEvent\fP. | |
766 | .IP \fB%K\fR 5 | |
767 | The keysym corresponding to the event, substituted as a textual | |
768 | string. Valid only for \fBKeyPress\fR and \fBKeyRelease\fR events. | |
769 | .IP \fB%N\fR 5 | |
770 | The keysym corresponding to the event, substituted as a decimal | |
771 | number. Valid only for \fBKeyPress\fR and \fBKeyRelease\fR events. | |
772 | .IP \fB%P\fR 5 | |
773 | The name of the property being updated or deleted (which | |
774 | may be converted to an XAtom using \fBwinfo atom\fR.) Valid | |
775 | only for \fBProperty\fP events. | |
776 | .IP \fB%R\fR 5 | |
777 | The \fIroot\fR window identifier from the event. Valid only for | |
778 | events containing a \fIroot\fR field. | |
779 | .IP \fB%S\fR 5 | |
780 | The \fIsubwindow\fR window identifier from the event, | |
781 | formatted as a hexadecimal number. | |
782 | Valid only for events containing a \fIsubwindow\fR field. | |
783 | .IP \fB%T\fR 5 | |
784 | The \fItype\fR field from the event. Valid for all event types. | |
785 | .IP \fB%W\fR 5 | |
786 | The path name of the window to which the event was reported (the | |
787 | \fIwindow\fR field from the event). Valid for all event types. | |
788 | .IP \fB%X\fR 5 | |
789 | The \fIx_root\fR field from the event. | |
790 | If a virtual-root window manager is being used then the substituted | |
791 | value is the corresponding x-coordinate in the virtual root. | |
792 | Valid only for | |
793 | \fBButtonPress\fR, \fBButtonRelease\fR, \fBKeyPress\fR, \fBKeyRelease\fR, | |
794 | and \fBMotion\fR events. | |
795 | Same meaning as \fB%x\fP, except relative to the (virtual) root window. | |
796 | .IP \fB%Y\fR 5 | |
797 | The \fIy_root\fR field from the event. | |
798 | If a virtual-root window manager is being used then the substituted | |
799 | value is the corresponding y-coordinate in the virtual root. | |
800 | Valid only for | |
801 | \fBButtonPress\fR, \fBButtonRelease\fR, \fBKeyPress\fR, \fBKeyRelease\fR, | |
802 | and \fBMotion\fR events. | |
803 | Same meaning as \fB%y\fP, except relative to the (virtual) root window. | |
804 | .LP | |
805 | The replacement string for a %-replacement is formatted as a proper | |
806 | Tcl list element. | |
807 | This means that it will be surrounded with braces | |
808 | if it contains spaces, or special characters such as \fB$\fR and | |
809 | \fB{\fR may be preceded by backslashes. | |
810 | This guarantees that the string will be passed through the Tcl | |
811 | parser when the binding script is evaluated. | |
812 | Most replacements are numbers or well-defined strings such | |
813 | as \fBAbove\fR; for these replacements no special formatting | |
814 | is ever necessary. | |
815 | The most common case where reformatting occurs is for the \fB%A\fR | |
816 | substitution. For example, if \fIscript\fR is | |
817 | .CS | |
818 | \fBinsert\0%A\fR | |
819 | .CE | |
820 | and the character typed is an open square bracket, then the script | |
821 | actually executed will be | |
822 | .CS | |
823 | \fBinsert\0\e[\fR | |
824 | .CE | |
825 | This will cause the \fBinsert\fR to receive the original replacement | |
826 | string (open square bracket) as its first argument. | |
827 | If the extra backslash hadn't been added, Tcl would not have been | |
828 | able to parse the script correctly. | |
829 | .SH "MULTIPLE MATCHES" | |
830 | .PP | |
831 | It is possible for several bindings to match a given X event. | |
832 | If the bindings are associated with different \fItag\fR's, | |
833 | then each of the bindings will be executed, in order. | |
834 | By default, a binding for the widget will be executed first, followed | |
835 | by a class binding, a binding for its toplevel, and | |
836 | an \fBall\fR binding. | |
837 | The \fBbindtags\fR command may be used to change this order for | |
838 | a particular window or to associate additional binding tags with | |
839 | the window. | |
840 | .PP | |
841 | The \fBcontinue\fR and \fBbreak\fR commands may be used inside a | |
842 | binding script to control the processing of matching scripts. | |
843 | If \fBcontinue\fR is invoked, then the current binding script | |
844 | is terminated but Tk will continue processing binding scripts | |
845 | associated with other \fItag\fR's. | |
846 | If the \fBbreak\fR command is invoked within a binding script, | |
847 | then that script terminates and no other scripts will be invoked | |
848 | for the event. | |
849 | .PP | |
850 | If more than one binding matches a particular event and they | |
851 | have the same \fItag\fR, then the most specific binding | |
852 | is chosen and its script is evaluated. | |
853 | The following tests are applied, in order, to determine which of | |
854 | several matching sequences is more specific: | |
855 | (a) an event pattern that specifies a specific button or key is more specific | |
856 | than one that doesn't; | |
857 | (b) a longer sequence (in terms of number | |
858 | of events matched) is more specific than a shorter sequence; | |
859 | (c) if the modifiers specified in one pattern are a subset of the | |
860 | modifiers in another pattern, then the pattern with more modifiers | |
861 | is more specific. | |
862 | (d) a virtual event whose physical pattern matches the sequence is less | |
863 | specific than the same physical pattern that is not associated with a | |
864 | virtual event. | |
865 | (e) given a sequence that matches two or more virtual events, one | |
866 | of the virtual events will be chosen, but the order is undefined. | |
867 | .PP | |
868 | If the matching sequences contain more than one event, then tests | |
869 | (c)-(e) are applied in order from the most recent event to the least recent | |
870 | event in the sequences. If these tests fail to determine a winner, then the | |
871 | most recently registered sequence is the winner. | |
872 | .PP | |
873 | If there are two (or more) virtual events that are both triggered by the | |
874 | same sequence, and both of those virtual events are bound to the same window | |
875 | tag, then only one of the virtual events will be triggered, and it will | |
876 | be picked at random: | |
877 | .CS | |
878 | event add <<Paste>> <Control-y> | |
879 | event add <<Paste>> <Button-2> | |
880 | event add <<Scroll>> <Button-2> | |
881 | \fBbind\fR Entry <<Paste>> {puts Paste} | |
882 | \fBbind\fR Entry <<Scroll>> {puts Scroll} | |
883 | .CE | |
884 | If the user types Control-y, the \fB<<Paste>>\fR binding | |
885 | will be invoked, but if the user presses button 2 then one of | |
886 | either the \fB<<Paste>>\fR or the \fB<<Scroll>>\fR bindings will | |
887 | be invoked, but exactly which one gets invoked is undefined. | |
888 | .PP | |
889 | If an X event does not match any of the existing bindings, then the | |
890 | event is ignored. | |
891 | An unbound event is not considered to be an error. | |
892 | .SH "MULTI-EVENT SEQUENCES AND IGNORED EVENTS" | |
893 | .PP | |
894 | When a \fIsequence\fR specified in a \fBbind\fR command contains | |
895 | more than one event pattern, then its script is executed whenever | |
896 | the recent events (leading up to and including the current event) | |
897 | match the given sequence. This means, for example, that if button 1 is | |
898 | clicked repeatedly the sequence \fB<Double-ButtonPress-1>\fR will match | |
899 | each button press but the first. | |
900 | If extraneous events that would prevent a match occur in the middle | |
901 | of an event sequence then the extraneous events are | |
902 | ignored unless they are \fBKeyPress\fR or \fBButtonPress\fR events. | |
903 | For example, \fB<Double-ButtonPress-1>\fR will match a sequence of | |
904 | presses of button 1, even though there will be \fBButtonRelease\fR | |
905 | events (and possibly \fBMotion\fR events) between the | |
906 | \fBButtonPress\fR events. | |
907 | Furthermore, a \fBKeyPress\fR event may be preceded by any number | |
908 | of other \fBKeyPress\fR events for modifier keys without the | |
909 | modifier keys preventing a match. | |
910 | For example, the event sequence \fBaB\fR will match a press of the | |
911 | \fBa\fR key, a release of the \fBa\fR key, a press of the \fBShift\fR | |
912 | key, and a press of the \fBb\fR key: the press of \fBShift\fR is | |
913 | ignored because it is a modifier key. | |
914 | Finally, if several \fBMotion\fR events occur in a row, only | |
915 | the last one is used for purposes of matching binding sequences. | |
916 | .SH "ERRORS" | |
917 | .PP | |
918 | If an error occurs in executing the script for a binding then the | |
919 | \fBbgerror\fR mechanism is used to report the error. | |
920 | The \fBbgerror\fR command will be executed at global level | |
921 | (outside the context of any Tcl procedure). | |
922 | .SH "EXAMPLES" | |
923 | Arrange for a string describing the motion of the mouse to be printed | |
924 | out when the mouse is double-clicked: | |
925 | .CS | |
926 | \fBbind\fR . <Double-1> { | |
927 | puts "hi from (%x,%y)" | |
928 | } | |
929 | .CE | |
930 | .PP | |
931 | A little GUI that displays what the keysym name of the last key | |
932 | pressed is: | |
933 | .CS | |
934 | set keysym "Press any key" | |
935 | pack [label .l -textvariable keysym -padx 2m -pady 1m] | |
936 | \fBbind\fR . <Key> { | |
937 | set keysym "You pressed %K" | |
938 | } | |
939 | .CE | |
940 | ||
941 | .SH "SEE ALSO" | |
942 | bgerror(n), bindtags(n), event(n), focus(n), grab(n), keysyms(n) | |
943 | ||
944 | .SH KEYWORDS | |
945 | binding, event |