| 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 |