util/X86LINUX64/man/mann/event.n

   1 '\"
   2 '\" Copyright (c) 1996 Sun Microsystems, Inc.
   3 '\" Copyright (c) 1998-2000 Ajuba Solutions.
   4 '\"
   5 '\" See the file "license.terms" for information on usage and redistribution
   6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   7 '\"
   8 .TH event n 8.3 Tk "Tk Built-In Commands"
   9 .\" The -*- nroff -*- definitions below are for supplemental macros used
  10 .\" in Tcl/Tk manual entries.
  11 .\"
  12 .\" .AP type name in/out ?indent?
  13 .\"     Start paragraph describing an argument to a library procedure.
  14 .\"     type is type of argument (int, etc.), in/out is either "in", "out",
  15 .\"     or "in/out" to describe whether procedure reads or modifies arg,
  16 .\"     and indent is equivalent to second arg of .IP (shouldn't ever be
  17 .\"     needed;  use .AS below instead)
  18 .\"
  19 .\" .AS ?type? ?name?
  20 .\"     Give maximum sizes of arguments for setting tab stops.  Type and
  21 .\"     name are examples of largest possible arguments that will be passed
  22 .\"     to .AP later.  If args are omitted, default tab stops are used.
  23 .\"
  24 .\" .BS
  25 .\"     Start box enclosure.  From here until next .BE, everything will be
  26 .\"     enclosed in one large box.
  27 .\"
  28 .\" .BE
  29 .\"     End of box enclosure.
  30 .\"
  31 .\" .CS
  32 .\"     Begin code excerpt.
  33 .\"
  34 .\" .CE
  35 .\"     End code excerpt.
  36 .\"
  37 .\" .VS ?version? ?br?
  38 .\"     Begin vertical sidebar, for use in marking newly-changed parts
  39 .\"     of man pages.  The first argument is ignored and used for recording
  40 .\"     the version when the .VS was added, so that the sidebars can be
  41 .\"     found and removed when they reach a certain age.  If another argument
  42 .\"     is present, then a line break is forced before starting the sidebar.
  43 .\"
  44 .\" .VE
  45 .\"     End of vertical sidebar.
  46 .\"
  47 .\" .DS
  48 .\"     Begin an indented unfilled display.
  49 .\"
  50 .\" .DE
  51 .\"     End of indented unfilled display.
  52 .\"
  53 .\" .SO ?manpage?
  54 .\"     Start of list of standard options for a Tk widget. The manpage
  55 .\"     argument defines where to look up the standard options; if
  56 .\"     omitted, defaults to "options". The options follow on successive
  57 .\"     lines, in three columns separated by tabs.
  58 .\"
  59 .\" .SE
  60 .\"     End of list of standard options for a Tk widget.
  61 .\"
  62 .\" .OP cmdName dbName dbClass
  63 .\"     Start of description of a specific option.  cmdName gives the
  64 .\"     option's name as specified in the class command, dbName gives
  65 .\"     the option's name in the option database, and dbClass gives
  66 .\"     the option's class in the option database.
  67 .\"
  68 .\" .UL arg1 arg2
  69 .\"     Print arg1 underlined, then print arg2 normally.
  70 .\"
  71 .\" .QW arg1 ?arg2?
  72 .\"     Print arg1 in quotes, then arg2 normally (for trailing punctuation).
  73 .\"
  74 .\" .PQ arg1 ?arg2?
  75 .\"     Print an open parenthesis, arg1 in quotes, then arg2 normally
  76 .\"     (for trailing punctuation) and then a closing parenthesis.
  77 .\"
  78 .\"     # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
  79 .if t .wh -1.3i ^B
  80 .nr ^l \n(.l
  81 .ad b
  82 .\"     # Start an argument description
  83 .de AP
  84 .ie !"\\$4"" .TP \\$4
  85 .el \{\
  86 .   ie !"\\$2"" .TP \\n()Cu
  87 .   el          .TP 15
  88 .\}
  89 .ta \\n()Au \\n()Bu
  90 .ie !"\\$3"" \{\
  91 \&\\$1 \\fI\\$2\\fP (\\$3)
  92 .\".b
  93 .\}
  94 .el \{\
  95 .br
  96 .ie !"\\$2"" \{\
  97 \&\\$1  \\fI\\$2\\fP
  98 .\}
  99 .el \{\
 100 \&\\fI\\$1\\fP
 101 .\}
 102 .\}
 103 ..
 104 .\"     # define tabbing values for .AP
 105 .de AS
 106 .nr )A 10n
 107 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
 108 .nr )B \\n()Au+15n
 109 .\"
 110 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
 111 .nr )C \\n()Bu+\\w'(in/out)'u+2n
 112 ..
 113 .AS Tcl_Interp Tcl_CreateInterp in/out
 114 .\"     # BS - start boxed text
 115 .\"     # ^y = starting y location
 116 .\"     # ^b = 1
 117 .de BS
 118 .br
 119 .mk ^y
 120 .nr ^b 1u
 121 .if n .nf
 122 .if n .ti 0
 123 .if n \l'\\n(.lu\(ul'
 124 .if n .fi
 125 ..
 126 .\"     # BE - end boxed text (draw box now)
 127 .de BE
 128 .nf
 129 .ti 0
 130 .mk ^t
 131 .ie n \l'\\n(^lu\(ul'
 132 .el \{\
 133 .\"     Draw four-sided box normally, but don't draw top of
 134 .\"     box if the box started on an earlier page.
 135 .ie !\\n(^b-1 \{\
 136 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 137 .\}
 138 .el \}\
 139 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 140 .\}
 141 .\}
 142 .fi
 143 .br
 144 .nr ^b 0
 145 ..
 146 .\"     # VS - start vertical sidebar
 147 .\"     # ^Y = starting y location
 148 .\"     # ^v = 1 (for troff;  for nroff this doesn't matter)
 149 .de VS
 150 .if !"\\$2"" .br
 151 .mk ^Y
 152 .ie n 'mc \s12\(br\s0
 153 .el .nr ^v 1u
 154 ..
 155 .\"     # VE - end of vertical sidebar
 156 .de VE
 157 .ie n 'mc
 158 .el \{\
 159 .ev 2
 160 .nf
 161 .ti 0
 162 .mk ^t
 163 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
 164 .sp -1
 165 .fi
 166 .ev
 167 .\}
 168 .nr ^v 0
 169 ..
 170 .\"     # Special macro to handle page bottom:  finish off current
 171 .\"     # box/sidebar if in box/sidebar mode, then invoked standard
 172 .\"     # page bottom macro.
 173 .de ^B
 174 .ev 2
 175 'ti 0
 176 'nf
 177 .mk ^t
 178 .if \\n(^b \{\
 179 .\"     Draw three-sided box if this is the box's first page,
 180 .\"     draw two sides but no top otherwise.
 181 .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
 182 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 183 .\}
 184 .if \\n(^v \{\
 185 .nr ^x \\n(^tu+1v-\\n(^Yu
 186 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
 187 .\}
 188 .bp
 189 'fi
 190 .ev
 191 .if \\n(^b \{\
 192 .mk ^y
 193 .nr ^b 2
 194 .\}
 195 .if \\n(^v \{\
 196 .mk ^Y
 197 .\}
 198 ..
 199 .\"     # DS - begin display
 200 .de DS
 201 .RS
 202 .nf
 203 .sp
 204 ..
 205 .\"     # DE - end display
 206 .de DE
 207 .fi
 208 .RE
 209 .sp
 210 ..
 211 .\"     # SO - start of list of standard options
 212 .de SO
 213 'ie '\\$1'' .ds So \\fBoptions\\fR
 214 'el .ds So \\fB\\$1\\fR
 215 .SH "STANDARD OPTIONS"
 216 .LP
 217 .nf
 218 .ta 5.5c 11c
 219 .ft B
 220 ..
 221 .\"     # SE - end of list of standard options
 222 .de SE
 223 .fi
 224 .ft R
 225 .LP
 226 See the \\*(So manual entry for details on the standard options.
 227 ..
 228 .\"     # OP - start of full description for a single option
 229 .de OP
 230 .LP
 231 .nf
 232 .ta 4c
 233 Command-Line Name:      \\fB\\$1\\fR
 234 Database Name:  \\fB\\$2\\fR
 235 Database Class: \\fB\\$3\\fR
 236 .fi
 237 .IP
 238 ..
 239 .\"     # CS - begin code excerpt
 240 .de CS
 241 .RS
 242 .nf
 243 .ta .25i .5i .75i 1i
 244 ..
 245 .\"     # CE - end code excerpt
 246 .de CE
 247 .fi
 248 .RE
 249 ..
 250 .\"     # UL - underline word
 251 .de UL
 252 \\$1\l'|0\(ul'\\$2
 253 ..
 254 .\"     # QW - apply quotation marks to word
 255 .de QW
 256 .ie '\\*(lq'"' ``\\$1''\\$2
 257 .\"" fix emacs highlighting
 258 .el \\*(lq\\$1\\*(rq\\$2
 259 ..
 260 .\"     # PQ - apply parens and quotation marks to word
 261 .de PQ
 262 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
 263 .\"" fix emacs highlighting
 264 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
 265 ..
 266 .\"     # QR - quoted range
 267 .de QR
 268 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
 269 .\"" fix emacs highlighting
 270 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
 271 ..
 272 .\"     # MT - "empty" string
 273 .de MT
 274 .QW ""
 275 ..
 276 .BS
 277 '\" Note:  do not modify the .SH NAME line immediately below!
 278 .SH NAME
 279 event \- Miscellaneous event facilities: define virtual events and generate events
 280 .SH SYNOPSIS
 281 \fBevent\fI option \fR?\fIarg arg ...\fR?
 282 .BE
 283 .SH DESCRIPTION
 284 .PP
 285 The \fBevent\fR command provides several facilities for dealing with
 286 window system events, such as defining virtual events and synthesizing
 287 events.  The command has several different forms, determined by the
 288 first argument.  The following forms are currently supported:
 289 .TP
 290 \fBevent add <<\fIvirtual\fB>>\fI sequence \fR?\fIsequence ...\fR?
 291 Associates the virtual event \fIvirtual\fR with the physical
 292 event sequence(s) given by the \fIsequence\fR arguments, so that
 293 the virtual event will trigger whenever any one of the \fIsequence\fRs
 294 occurs.
 295 \fIVirtual\fR may be any string value and \fIsequence\fR may have
 296 any of the values allowed for the \fIsequence\fR argument to the
 297 \fBbind\fR command.
 298 If \fIvirtual\fR is already defined, the new physical event sequences
 299 add to the existing sequences for the event.
 300 .TP
 301 \fBevent delete <<\fIvirtual\fB>> \fR?\fIsequence\fR \fIsequence ...\fR?
 302 Deletes each of the \fIsequence\fRs from those associated with
 303 the virtual event given by \fIvirtual\fR.
 304 \fIVirtual\fR may be any string value and \fIsequence\fR may have
 305 any of the values allowed for the \fIsequence\fR argument to the
 306 \fBbind\fR command.
 307 Any \fIsequence\fRs not currently associated with \fIvirtual\fR
 308 are ignored.
 309 If no \fIsequence\fR argument is provided, all physical event sequences
 310 are removed for \fIvirtual\fR, so that the virtual event will not
 311 trigger anymore.
 312 .TP
 313 \fBevent generate \fIwindow event \fR?\fIoption value option value ...\fR?
 314 Generates a window event and arranges for it to be processed just as if
 315 it had come from the window system.
 316 \fIWindow\fR gives the path name of the window for which the event
 317 will be generated; it may also be an identifier (such as returned by
 318 \fBwinfo id\fR) as long as it is for a window in the current application.
 319 \fIEvent\fR provides a basic description of
 320 the event, such as \fB<Shift-Button-2>\fR or \fB<<Paste>>\fR.
 321 If \fIWindow\fR is empty the whole screen is meant, and coordinates
 322 are relative to the screen.
 323 \fIEvent\fR may have any of the forms allowed for the \fIsequence\fR
 324 argument of the \fBbind\fR command except that it must consist
 325 of a single event pattern, not a sequence.
 326 \fIOption-value\fR pairs may be used to specify additional
 327 attributes of the event, such as the x and y mouse position;  see
 328 \fBEVENT FIELDS\fR below.  If the \fB\-when\fR option is not specified, the
 329 event is processed immediately:  all of the handlers for the event
 330 will complete before the \fBevent generate\fR command returns.
 331 If the \fB\-when\fR option is specified then it determines when the
 332 event is processed.  Certain events, such as key events, require
 333 that the window has focus to receive the event properly.
 334 .TP
 335 \fBevent info \fR?\fB<<\fIvirtual\fB>>\fR?
 336 Returns information about virtual events.
 337 If the \fB<<\fIvirtual\fB>>\fR argument is omitted, the return value
 338 is a list of all the virtual events that are currently defined.
 339 If \fB<<\fIvirtual\fB>>\fR is specified then the return value is
 340 a list whose elements are the physical event sequences currently
 341 defined for the given virtual event;  if the virtual event is
 342 not defined then an empty string is returned.
 343 .RS
 344 .PP
 345 Note that virtual events that are not bound to physical event
 346 sequences are \fInot\fR returned by \fBevent info\fR.
 347 .RE
 348 .SH "EVENT FIELDS"
 349 .PP
 350 The following options are supported for the \fBevent generate\fR
 351 command.  These correspond to the
 352 .QW %
 353 expansions allowed in binding scripts for the \fBbind\fR command.
 354 .TP
 355 \fB\-above\fI window\fR
 356 \fIWindow\fR specifies the \fIabove\fR field for the event,
 357 either as a window path name or as an integer window id.
 358 Valid for \fBConfigure\fR events.
 359 Corresponds to the \fB%a\fR substitution for binding scripts.
 360 .TP
 361 \fB\-borderwidth\fI size\fR
 362 \fISize\fR must be a screen distance;  it specifies the
 363 \fIborder_width\fR field for the event.
 364 Valid for \fBConfigure\fR events.
 365 Corresponds to the \fB%B\fR substitution for binding scripts.
 366 .TP
 367 \fB\-button\fI number\fR
 368 \fINumber\fR must be an integer;  it specifies the \fIdetail\fR field
 369 for a \fBButtonPress\fR or \fBButtonRelease\fR event, overriding
 370 any button  number provided in the base \fIevent\fR argument.
 371 Corresponds to the \fB%b\fR substitution for binding scripts.
 372 .TP
 373 \fB\-count\fI number\fR
 374 \fINumber\fR must be an integer;  it specifies the \fIcount\fR field
 375 for the event.  Valid for \fBExpose\fR events.
 376 Corresponds to the \fB%c\fR substitution for binding scripts.
 377 .TP
 378 \fB\-data\fI string\fR
 379 \fIString\fR may be any value; it specifies the \fIuser_data\fR field
 380 for the event.  Only valid for virtual events.  Corresponds to the
 381 \fB%d\fR substitution for virtual events in binding scripts.
 382 .TP
 383 \fB\-delta\fI number\fR
 384 \fINumber\fR must be an integer;  it specifies the \fIdelta\fR field
 385 for the \fBMouseWheel\fR event.  The \fIdelta\fR refers to the
 386 direction and magnitude the mouse wheel was rotated.  Note the value
 387 is not a screen distance but are units of motion in the mouse wheel.
 388 Typically these values are multiples of 120.  For example, 120 should
 389 scroll the text widget up 4 lines and \-240 would scroll the text
 390 widget down 8 lines.  Of course, other widgets may define different
 391 behaviors for mouse wheel motion.  This field corresponds to the
 392 \fB%D\fR substitution for binding scripts.
 393 .TP
 394 \fB\-detail\fI detail\fR
 395 \fIDetail\fR specifies the \fIdetail\fR field for the event
 396 and must be one of the following:
 397 .RS
 398 .DS
 399 .ta 6c
 400 \fBNotifyAncestor\fR    \fBNotifyNonlinearVirtual\fR
 401 \fBNotifyDetailNone\fR  \fBNotifyPointer\fR
 402 \fBNotifyInferior\fR    \fBNotifyPointerRoot\fR
 403 \fBNotifyNonlinear\fR   \fBNotifyVirtual\fR
 404 .DE
 405 Valid for \fBEnter\fR, \fBLeave\fR, \fBFocusIn\fR and
 406 \fBFocusOut\fR events.
 407 Corresponds to the \fB%d\fR substitution for binding scripts.
 408 .RE
 409 .TP
 410 \fB\-focus\fI boolean\fR
 411 \fIBoolean\fR must be a boolean value;  it specifies the \fIfocus\fR
 412 field for the event.
 413 Valid for \fBEnter\fR and \fBLeave\fR events.
 414 Corresponds to the \fB%f\fR substitution for binding scripts.
 415 .TP
 416 \fB\-height\fI size\fR
 417 \fISize\fR must be a screen distance;  it specifies the \fIheight\fR
 418 field for the event.  Valid for \fBConfigure\fR events.
 419 Corresponds to the \fB%h\fR substitution for binding scripts.
 420 .TP
 421 \fB\-keycode\fI number\fR
 422 \fINumber\fR  must be an integer;  it specifies the \fIkeycode\fR
 423 field for the event.
 424 Valid for \fBKeyPress\fR and \fBKeyRelease\fR events.
 425 Corresponds to the \fB%k\fR substitution for binding scripts.
 426 .TP
 427 \fB\-keysym\fI name\fR
 428 \fIName\fR must be the name of a valid keysym, such as \fBg\fR,
 429 \fBspace\fR, or \fBReturn\fR;  its corresponding
 430 keycode value is used as the \fIkeycode\fR field for event, overriding
 431 any detail specified in the base \fIevent\fR argument.
 432 Valid for \fBKeyPress\fR and \fBKeyRelease\fR events.
 433 Corresponds to the \fB%K\fR substitution for binding scripts.
 434 .TP
 435 \fB\-mode\fI notify\fR
 436 \fINotify\fR specifies the \fImode\fR field for the event and must be
 437 one of \fBNotifyNormal\fR, \fBNotifyGrab\fR, \fBNotifyUngrab\fR, or
 438 \fBNotifyWhileGrabbed\fR.
 439 Valid for \fBEnter\fR, \fBLeave\fR, \fBFocusIn\fR, and
 440 \fBFocusOut\fR events.
 441 Corresponds to the \fB%m\fR substitution for binding scripts.
 442 .TP
 443 \fB\-override\fI boolean\fR
 444 \fIBoolean\fR must be a boolean value;  it specifies the
 445 \fIoverride_redirect\fR field for the event.
 446 Valid for \fBMap\fR, \fBReparent\fR, and \fBConfigure\fR events.
 447 Corresponds to the \fB%o\fR substitution for binding scripts.
 448 .TP
 449 \fB\-place\fI where\fR
 450 \fIWhere\fR specifies the \fIplace\fR field for the event;  it must be
 451 either \fBPlaceOnTop\fR or \fBPlaceOnBottom\fR.
 452 Valid for \fBCirculate\fR events.
 453 Corresponds to the \fB%p\fR substitution for binding scripts.
 454 .TP
 455 \fB\-root\fI window\fR
 456 \fIWindow\fR must be either a window path name or an integer window
 457 identifier;  it specifies the \fIroot\fR field for the event.
 458 Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR,
 459 \fBButtonRelease\fR, \fBEnter\fR, \fBLeave\fR, and \fBMotion\fR
 460 events.
 461 Corresponds to the \fB%R\fR substitution for binding scripts.
 462 .TP
 463 \fB\-rootx\fI coord\fR
 464 \fICoord\fR must be a screen distance;  it specifies the \fIx_root\fR
 465 field for the event.
 466 Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR,
 467 \fBButtonRelease\fR, \fBEnter\fR, \fBLeave\fR, and \fBMotion\fR
 468 events.  Corresponds to the \fB%X\fR substitution for binding scripts.
 469 .TP
 470 \fB\-rooty\fI coord\fR
 471 \fICoord\fR must be a screen distance;  it specifies the \fIy_root\fR
 472 field for the event.
 473 Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR,
 474 \fBButtonRelease\fR, \fBEnter\fR, \fBLeave\fR, and \fBMotion\fR
 475 events.
 476 Corresponds to the \fB%Y\fR substitution for binding scripts.
 477 .TP
 478 \fB\-sendevent\fI boolean\fR
 479 \fIBoolean\fR must be a boolean value;  it specifies the \fIsend_event\fR
 480 field for the event.  Valid for all events.  Corresponds to the
 481 \fB%E\fR substitution for binding scripts.
 482 .TP
 483 \fB\-serial\fI number\fR
 484 \fINumber\fR must be an integer;  it specifies the \fIserial\fR field
 485 for the event.  Valid for all events.
 486 Corresponds to the \fB%#\fR substitution for binding scripts.
 487 .TP
 488 \fB\-state\fI state\fR
 489 \fIState\fR specifies the \fIstate\fR field for the event.
 490 For \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR,
 491 \fBButtonRelease\fR, \fBEnter\fR, \fBLeave\fR, and \fBMotion\fR events
 492 it must be an integer value.
 493 For \fBVisibility\fR events it must be one of \fBVisibilityUnobscured\fR,
 494 \fBVisibilityPartiallyObscured\fR, or \fBVisibilityFullyObscured\fR.
 495 This option overrides any modifiers such as \fBMeta\fR or \fBControl\fR
 496 specified in the base \fIevent\fR.
 497 Corresponds to the \fB%s\fR substitution for binding scripts.
 498 .TP
 499 \fB\-subwindow\fI window\fR
 500 \fIWindow\fR specifies the \fIsubwindow\fR field for the event, either
 501 as a path name for a Tk widget or as an integer window identifier.
 502 Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR,
 503 \fBButtonRelease\fR, \fBEnter\fR, \fBLeave\fR, and \fBMotion\fR events.
 504 Similar to \fB%S\fR substitution for binding scripts.
 505 .TP
 506 \fB\-time\fI integer\fR
 507 \fIInteger\fR must be an integer value;  it specifies the \fItime\fR field
 508 for the event.
 509 Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR,
 510 \fBButtonRelease\fR, \fBEnter\fR, \fBLeave\fR, \fBMotion\fR,
 511 and \fBProperty\fR events.
 512 Corresponds to the \fB%t\fR substitution for binding scripts.
 513 .TP
 514 \fB\-warp\fI boolean\fR
 515 \fIboolean\fR must be a boolean value;  it specifies whether
 516 the screen pointer should be warped as well.
 517 Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR,
 518 \fBButtonRelease\fR, and \fBMotion\fR events.  The pointer will
 519 only warp to a window if it is mapped.
 520 .TP
 521 \fB\-width\fI size\fR
 522 \fISize\fR must be a screen distance;  it specifies the \fIwidth\fR field
 523 for the event.
 524 Valid for \fBConfigure\fR events.
 525 Corresponds to the \fB%w\fR substitution for binding scripts.
 526 .TP
 527 \fB\-when\fI when\fR
 528 \fIWhen\fR determines when the event will be processed;  it must have one
 529 of the following values:
 530 .RS
 531 .IP \fBnow\fR 10
 532 Process the event immediately, before the command returns.
 533 This also happens if the \fB\-when\fR option is omitted.
 534 .IP \fBtail\fR 10
 535 Place the event on Tcl's event queue behind any events already
 536 queued for this application.
 537 .IP \fBhead\fR 10
 538 Place the event at the front of Tcl's event queue, so that it
 539 will be handled before any other events already queued.
 540 .IP \fBmark\fR 10
 541 Place the event at the front of Tcl's event queue but behind any
 542 other events already queued with \fB\-when mark\fR.
 543 This option is useful when generating a series of events that should
 544 be processed in order but at the front of the queue.
 545 .RE
 546 .TP
 547 \fB\-x\fI coord\fR
 548 \fICoord\fR must be a screen distance;  it specifies the \fIx\fR field
 549 for the event.
 550 Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR,
 551 \fBButtonRelease\fR, \fBMotion\fR, \fBEnter\fR, \fBLeave\fR,
 552 \fBExpose\fR, \fBConfigure\fR, \fBGravity\fR, and \fBReparent\fR
 553 events.
 554 Corresponds to the \fB%x\fR substitution for binding scripts.
 555 If \fIWindow\fR is empty the coordinate is relative to the
 556 screen, and this option corresponds to the \fB%X\fR substitution
 557 for binding scripts.
 558 .TP
 559 \fB\-y\fI coord\fR
 560 \fICoord\fR must be a screen distance;  it specifies the \fIy\fR
 561 field for the event.
 562 Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR,
 563 \fBButtonRelease\fR, \fBMotion\fR, \fBEnter\fR, \fBLeave\fR,
 564 \fBExpose\fR, \fBConfigure\fR, \fBGravity\fR, and \fBReparent\fR
 565 events.
 566 Corresponds to the \fB%y\fR substitution for binding scripts.
 567 If \fIWindow\fR is empty the coordinate is relative to the
 568 screen, and this option corresponds to the \fB%Y\fR substitution
 569 for binding scripts.
 570 .PP
 571 Any options that are not specified when generating an event are filled
 572 with the value 0, except for \fIserial\fR, which is filled with the
 573 next X event serial number.
 574 .SH "PREDEFINED VIRTUAL EVENTS"
 575 .PP
 576 Tk defines the following virtual events for the purposes of
 577 notification:
 578 .TP
 579 \fB<<AltUnderlined>>\fR
 580 This is sent to widget to notify it that the letter it has underlined
 581 (as an accelerator indicator) with the \fB\-underline\fR option has
 582 been pressed in combination with the Alt key. The usual response to
 583 this is to either focus into the widget (or some related widget) or to
 584 invoke the widget.
 585 .TP
 586 \fB<<Invoke>>\fR
 587 This can be sent to some widgets (e.g. button, listbox, menu) as an
 588 alternative to <space>.
 589 .TP
 590 \fB<<ListboxSelect>>\fR
 591 This is sent to a listbox when the set of selected item(s) in the
 592 listbox is updated.
 593 .TP
 594 \fB<<MenuSelect>>\fR
 595 This is sent to a menu when the currently selected item in the menu
 596 changes. It is intended for use with context-sensitive help systems.
 597 .TP
 598 \fB<<Modified>>\fR
 599 This is sent to a text widget when the contents of the widget are
 600 changed.
 601 .TP
 602 \fB<<Selection>>\fR
 603 This is sent to a text widget when the selection in the widget is
 604 changed.
 605 .TP
 606 \fB<<ThemeChanged>>\fR
 607 This is sent to a text widget when the ttk (Tile) theme changed.
 608 .TP
 609 \fB<<TraverseIn>>\fR
 610 This is sent to a widget when the focus enters the widget because of a
 611 user-driven
 612 .QW "tab to widget"
 613 action.
 614 .TP
 615 \fB<<TraverseOut>>\fR
 616 This is sent to a widget when the focus leaves the widget because of a
 617 user-driven
 618 .QW "tab to widget"
 619 action.
 620 .PP
 621 Tk defines the following virtual events for the purposes of unifying
 622 bindings across multiple platforms. Users expect them to behave in the
 623 following way:
 624 .TP
 625 \fB<<Clear>>\fR
 626 Delete the currently selected widget contents.
 627 .TP
 628 \fB<<Copy>>\fR
 629 Copy the currently selected widget contents to the clipboard.
 630 .TP
 631 \fB<<Cut>>\fR
 632 Move the currently selected widget contents to the clipboard.
 633 .TP
 634 \fB<<LineEnd>>\fR
 635 .
 636 Move to the end of the line in the current widget while deselecting any
 637 selected contents.
 638 .TP
 639 \fB<<LineStart>>\fR
 640 .
 641 Move to the start of the line in the current widget while deselecting any
 642 selected contents.
 643 .TP
 644 \fB<<NextChar>>\fR
 645 .
 646 Move to the next item (i.e., visible character) in the current widget while
 647 deselecting any selected contents.
 648 .TP
 649 \fB<<NextLine>>\fR
 650 .
 651 Move to the next line in the current widget while deselecting any selected
 652 contents.
 653 .TP
 654 \fB<<NextPara>>\fR
 655 .
 656 Move to the next paragraph in the current widget while deselecting any
 657 selected contents.
 658 .TP
 659 \fB<<NextWord>>\fR
 660 .
 661 Move to the next group of items (i.e., visible word) in the current widget
 662 while deselecting any selected contents.
 663 .TP
 664 \fB<<Paste>>\fR
 665 Replace the currently selected widget contents with the contents of
 666 the clipboard.
 667 .TP
 668 \fB<<PasteSelection>>\fR
 669 Insert the contents of the selection at the mouse location. (This
 670 event has meaningful \fB%x\fR and \fB%y\fR substitutions).
 671 .TP
 672 \fB<<PrevChar>>\fR
 673 .
 674 Move to the previous item (i.e., visible character) in the current widget
 675 while deselecting any selected contents.
 676 .TP
 677 \fB<<PrevLine>>\fR
 678 .
 679 Move to the previous line in the current widget while deselecting any selected
 680 contents.
 681 .TP
 682 \fB<<PrevPara>>\fR
 683 .
 684 Move to the previous paragraph in the current widget while deselecting any
 685 selected contents.
 686 .TP
 687 \fB<<PrevWindow>>\fR
 688 Traverse to the previous window.
 689 .TP
 690 \fB<<PrevWord>>\fR
 691 .
 692 Move to the previous group of items (i.e., visible word) in the current widget
 693 while deselecting any selected contents.
 694 .TP
 695 \fB<<Redo>>\fR
 696 Redo one undone action.
 697 .TP
 698 \fB<<SelectAll>>\fR
 699 .
 700 Set the range of selected contents to the complete widget.
 701 .TP
 702 \fB<<SelectLineEnd>>\fR
 703 .
 704 Move to the end of the line in the current widget while extending the range
 705 of selected contents.
 706 .TP
 707 \fB<<SelectLineStart>>\fR
 708 .
 709 Move to the start of the line in the current widget while extending the range
 710 of selected contents.
 711 .TP
 712 \fB<<SelectNextChar>>\fR
 713 .
 714 Move to the next item (i.e., visible character) in the current widget while
 715 extending the range of selected contents.
 716 .TP
 717 \fB<<SelectNextLine>>\fR
 718 .
 719 Move to the next line in the current widget while extending the range of
 720 selected contents.
 721 .TP
 722 \fB<<SelectNextPara>>\fR
 723 .
 724 Move to the next paragraph in the current widget while extending the range
 725 of selected contents.
 726 .TP
 727 \fB<<SelectNextWord>>\fR
 728 .
 729 Move to the next group of items (i.e., visible word) in the current widget
 730 while extending the range of selected contents.
 731 .TP
 732 \fB<<SelectNone>>\fR
 733 .
 734 Reset the range of selected contents to be empty.
 735 .TP
 736 \fB<<SelectPrevChar>>\fR
 737 .
 738 Move to the previous item (i.e., visible character) in the current widget
 739 while extending the range of selected contents.
 740 .TP
 741 \fB<<SelectPrevLine>>\fR
 742 .
 743 Move to the previous line in the current widget while extending the range of
 744 selected contents.
 745 .TP
 746 \fB<<SelectPrevPara>>\fR
 747 .
 748 Move to the previous paragraph in the current widget while extending the
 749 range of selected contents.
 750 .TP
 751 \fB<<SelectPrevWord>>\fR
 752 .
 753 Move to the previous group of items (i.e., visible word) in the current widget
 754 while extending the range of selected contents.
 755 .TP
 756 \fB<<ToggleSelection>>\fR
 757 .
 758 Toggle the selection.
 759 .TP
 760 \fB<<Undo>>\fR
 761 .
 762 Undo the last action.
 763 .SH EXAMPLES
 764 .SS "MAPPING KEYS TO VIRTUAL EVENTS"
 765 .PP
 766 In order for a virtual event binding to trigger, two things must
 767 happen.  First, the virtual event must be defined with the
 768 \fBevent add\fR command.  Second, a binding must be created for
 769 the virtual event with the \fBbind\fR command.
 770 Consider the following virtual event definitions:
 771 .PP
 772 .CS
 773 \fBevent add\fR <<Paste>> <Control-y>
 774 \fBevent add\fR <<Paste>> <Button-2>
 775 \fBevent add\fR <<Save>> <Control-X><Control-S>
 776 \fBevent add\fR <<Save>> <Shift-F12>
 777 if {[tk windowingsystem] eq "aqua"} {
 778     \fBevent add\fR <<Save>> <Command-s>
 779 }
 780 .CE
 781 .PP
 782 In the \fBbind\fR command, a virtual event can be bound like any other
 783 builtin event type as follows:
 784 .PP
 785 .CS
 786 bind Entry <<Paste>> {%W insert [selection get]}
 787 .CE
 788 .PP
 789 The double angle brackets are used to specify that a virtual event is being
 790 bound.  If the user types Control-y or presses button 2, or if
 791 a \fB<<Paste>>\fR virtual event is synthesized with \fBevent generate\fR,
 792 then the \fB<<Paste>>\fR binding will be invoked.
 793 .PP
 794 If a virtual binding has the exact same sequence as a separate
 795 physical binding, then the physical binding will take precedence.
 796 Consider the following example:
 797 .PP
 798 .CS
 799 \fBevent add\fR <<Paste>> <Control-y> <Meta-Control-y>
 800 bind Entry <Control-y> {puts Control-y}
 801 bind Entry <<Paste>> {puts Paste}
 802 .CE
 803 .PP
 804 When the user types Control-y the \fB<Control-y>\fR binding
 805 will be invoked, because a physical event is considered
 806 more specific than a virtual event, all other things being equal.
 807 However, when the user types Meta-Control-y the
 808 \fB<<Paste>>\fR binding will be invoked, because the
 809 \fBMeta\fR modifier in the physical pattern associated with the
 810 virtual binding is more specific than the \fB<Control-y\fR> sequence for
 811 the physical event.
 812 .PP
 813 Bindings on a virtual event may be created before the virtual event exists.
 814 Indeed, the virtual event never actually needs to be defined, for instance,
 815 on platforms where the specific virtual event would meaningless or
 816 ungeneratable.
 817 .PP
 818 When a definition of a virtual event changes at run time, all windows
 819 will respond immediately to the new definition.
 820 Starting from the preceding example, if the following code is executed:
 821 .PP
 822 .CS
 823 bind Entry <Control-y> {}
 824 \fBevent add\fR <<Paste>> <Key-F6>
 825 .CE
 826 .PP
 827 the behavior will change such in two ways.  First, the shadowed
 828 \fB<<Paste>>\fR binding will emerge.
 829 Typing Control-y will no longer invoke the \fB<Control-y>\fR binding,
 830 but instead invoke the virtual event \fB<<Paste>>\fR.  Second,
 831 pressing the F6 key will now also invoke the \fB<<Paste>>\fR binding.
 832 .SS "MOVING THE MOUSE POINTER"
 833 .PP
 834 Sometimes it is useful to be able to really move the mouse pointer. For
 835 example, if you have some software that is capable of demonstrating directly
 836 to the user how to use the program. To do this, you need to
 837 .QW warp
 838 the mouse around by using \fBevent generate\fR, like this:
 839 .PP
 840 .CS
 841 for {set xy 0} {$xy < 200} {incr xy} {
 842     \fBevent generate\fR . <Motion> -x $xy -y $xy -warp 1
 843     update
 844     after 50
 845 }
 846 .CE
 847 .PP
 848 Note that it is usually considered bad style to move the mouse pointer for the
 849 user because it removes control from them. Therefore this technique should be
 850 used with caution. Also note that it is not guaranteed to function on all
 851 platforms.
 852 .SH "SEE ALSO"
 853 bind(n)
 854 .SH KEYWORDS
 855 event, binding, define, handle, virtual event
 856 '\" Local Variables:
 857 '\" mode: nroff
 858 '\" End: