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