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.
6 '\" See the file "license.terms" for information on usage and redistribution
7 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
9 .TH bind n 8.0 Tk "Tk Built-In Commands"
10 .\" The -*- nroff -*- definitions below are for supplemental macros used
11 .\" in Tcl/Tk manual entries.
13 .\" .AP type name in/out ?indent?
14 .\" Start paragraph describing an argument to a library procedure.
15 .\" type is type of argument (int, etc.), in/out is either "in", "out",
16 .\" or "in/out" to describe whether procedure reads or modifies arg,
17 .\" and indent is equivalent to second arg of .IP (shouldn't ever be
18 .\" needed; use .AS below instead)
21 .\" Give maximum sizes of arguments for setting tab stops. Type and
22 .\" name are examples of largest possible arguments that will be passed
23 .\" to .AP later. If args are omitted, default tab stops are used.
26 .\" Start box enclosure. From here until next .BE, everything will be
27 .\" enclosed in one large box.
30 .\" End of box enclosure.
33 .\" Begin code excerpt.
38 .\" .VS ?version? ?br?
39 .\" Begin vertical sidebar, for use in marking newly-changed parts
40 .\" of man pages. The first argument is ignored and used for recording
41 .\" the version when the .VS was added, so that the sidebars can be
42 .\" found and removed when they reach a certain age. If another argument
43 .\" is present, then a line break is forced before starting the sidebar.
46 .\" End of vertical sidebar.
49 .\" Begin an indented unfilled display.
52 .\" End of indented unfilled display.
55 .\" Start of list of standard options for a Tk widget. The manpage
56 .\" argument defines where to look up the standard options; if
57 .\" omitted, defaults to "options". The options follow on successive
58 .\" lines, in three columns separated by tabs.
61 .\" End of list of standard options for a Tk widget.
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.
70 .\" Print arg1 underlined, then print arg2 normally.
73 .\" Print arg1 in quotes, then arg2 normally (for trailing punctuation).
76 .\" Print an open parenthesis, arg1 in quotes, then arg2 normally
77 .\" (for trailing punctuation) and then a closing parenthesis.
79 .\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
83 .\" # Start an argument description
87 . ie !"\\$2"" .TP \\n()Cu
92 \&\\$1 \\fI\\$2\\fP (\\$3)
105 .\" # define tabbing values for .AP
108 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
111 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
112 .nr )C \\n()Bu+\\w'(in/out)'u+2n
114 .AS Tcl_Interp Tcl_CreateInterp in/out
115 .\" # BS - start boxed text
116 .\" # ^y = starting y location
124 .if n \l'\\n(.lu\(ul'
127 .\" # BE - end boxed text (draw box now)
132 .ie n \l'\\n(^lu\(ul'
134 .\" Draw four-sided box normally, but don't draw top of
135 .\" box if the box started on an earlier page.
137 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
140 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
147 .\" # VS - start vertical sidebar
148 .\" # ^Y = starting y location
149 .\" # ^v = 1 (for troff; for nroff this doesn't matter)
153 .ie n 'mc \s12\(br\s0
156 .\" # VE - end of vertical sidebar
164 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
171 .\" # Special macro to handle page bottom: finish off current
172 .\" # box/sidebar if in box/sidebar mode, then invoked standard
173 .\" # page bottom macro.
180 .\" Draw three-sided box if this is the box's first page,
181 .\" draw two sides but no top otherwise.
182 .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
183 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
186 .nr ^x \\n(^tu+1v-\\n(^Yu
187 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
200 .\" # DS - begin display
206 .\" # DE - end display
212 .\" # SO - start of list of standard options
214 'ie '\\$1'' .ds So \\fBoptions\\fR
215 'el .ds So \\fB\\$1\\fR
216 .SH "STANDARD OPTIONS"
222 .\" # SE - end of list of standard options
227 See the \\*(So manual entry for details on the standard options.
229 .\" # OP - start of full description for a single option
234 Command-Line Name: \\fB\\$1\\fR
235 Database Name: \\fB\\$2\\fR
236 Database Class: \\fB\\$3\\fR
240 .\" # CS - begin code excerpt
246 .\" # CE - end code excerpt
251 .\" # UL - underline word
255 .\" # QW - apply quotation marks to word
257 .ie '\\*(lq'"' ``\\$1''\\$2
258 .\"" fix emacs highlighting
259 .el \\*(lq\\$1\\*(rq\\$2
261 .\" # PQ - apply parens and quotation marks to word
263 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
264 .\"" fix emacs highlighting
265 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
267 .\" # QR - quoted range
269 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
270 .\"" fix emacs highlighting
271 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
273 .\" # MT - "empty" string
278 '\" Note: do not modify the .SH NAME line immediately below!
280 bind \- Arrange for X events to invoke Tcl scripts
282 \fBbind\fI tag\fR ?\fIsequence\fR? ?\fB+\fR??\fIscript\fR?
286 The \fBbind\fR command associates Tcl scripts with X events.
287 If all three arguments are specified, \fBbind\fR will
288 arrange for \fIscript\fR (a Tcl script) to be evaluated whenever
289 the event(s) given by \fIsequence\fR occur in the window(s)
290 identified by \fItag\fR.
291 If \fIscript\fR is prefixed with a
293 then it is appended to
294 any existing binding for \fIsequence\fR; otherwise \fIscript\fR replaces
295 any existing binding.
296 If \fIscript\fR is an empty string then the current binding for
297 \fIsequence\fR is destroyed, leaving \fIsequence\fR unbound.
298 In all of the cases where a \fIscript\fR argument is provided,
299 \fBbind\fR returns an empty string.
301 If \fIsequence\fR is specified without a \fIscript\fR, then the
302 script currently bound to \fIsequence\fR is returned, or
303 an empty string is returned if there is no binding for \fIsequence\fR.
304 If neither \fIsequence\fR nor \fIscript\fR is specified, then the
305 return value is a list whose elements are all the sequences
306 for which there exist bindings for \fItag\fR.
308 The \fItag\fR argument determines which window(s) the binding applies to.
309 If \fItag\fR begins with a dot, as in \fB.a.b.c\fR, then it must
310 be the path name for a window; otherwise it may be an arbitrary
312 Each window has an associated list of tags, and a binding applies
313 to a particular window if its tag is among those specified for
315 Although the \fBbindtags\fR command may be used to assign an
316 arbitrary set of binding tags to a window, the default binding
317 tags provide the following behavior:
319 If a tag is the name of an internal window the binding applies
322 If the tag is the name of a toplevel window the binding applies
323 to the toplevel window and all its internal windows.
325 If the tag is the name of a class of widgets, such as \fBButton\fR,
326 the binding applies to all widgets in that class;
328 If \fItag\fR has the value \fBall\fR,
329 the binding applies to all windows in the application.
332 The \fIsequence\fR argument specifies a sequence of one or more
333 event patterns, with optional white space between the patterns. Each
335 take one of three forms. In the simplest case it is a single
336 printing ASCII character, such as \fBa\fR or \fB[\fR. The character
337 may not be a space character or the character \fB<\fR. This form of
338 pattern matches a \fBKeyPress\fR event for the particular
339 character. The second form of pattern is longer but more general.
340 It has the following syntax:
342 \fB<\fImodifier\-modifier\-type\-detail\fB>\fR
344 The entire event pattern is surrounded by angle brackets.
345 Inside the angle brackets are zero or more modifiers, an event
346 type, and an extra piece of information (\fIdetail\fR) identifying
347 a particular button or keysym. Any of the fields may be omitted,
348 as long as at least one of \fItype\fR and \fIdetail\fR is present.
349 The fields must be separated by white space or dashes.
351 The third form of pattern is used to specify a user-defined, named virtual
352 event. It has the following syntax:
356 The entire virtual event pattern is surrounded by double angle brackets.
357 Inside the angle brackets is the user-defined name of the virtual event.
358 Modifiers, such as \fBShift\fR or \fBControl\fR, may not be combined with a
359 virtual event to modify it. Bindings on a virtual event may be created
360 before the virtual event is defined, and if the definition of a virtual
361 event changes dynamically, all windows bound to that virtual event will
362 respond immediately to the new definition.
364 Some widgets (e.g. \fBmenu\fR and \fBtext\fR) issue virtual events
365 when their internal state is updated in some ways. Please see the
366 manual page for each widget for details.
369 Modifiers consist of any of the following values:
372 \fBControl\fR \fBMod1\fR, \fBM1\fR, \fBCommand\fR
373 \fBAlt\fR \fBMod2\fR, \fBM2\fR, \fBOption\fR
374 \fBShift\fR \fBMod3\fR, \fBM3\fR
375 \fBLock\fR \fBMod4\fR, \fBM4\fR
376 \fBExtended\fR \fBMod5\fR, \fBM5\fR
377 \fBButton1\fR, \fBB1\fR \fBMeta\fR, \fBM\fR
378 \fBButton2\fR, \fBB2\fR \fBDouble\fR
379 \fBButton3\fR, \fBB3\fR \fBTriple\fR
380 \fBButton4\fR, \fBB4\fR \fBQuadruple\fR
381 \fBButton5\fR, \fBB5\fR
383 Where more than one value is listed, separated by commas, the values
385 Most of the modifiers have the obvious X meanings.
386 For example, \fBButton1\fR requires that
387 button 1 be depressed when the event occurs.
388 For a binding to match a given event, the modifiers in the event
389 must include all of those specified in the event pattern.
390 An event may also contain additional modifiers not specified in
392 For example, if button 1 is pressed while the shift and control keys
393 are down, the pattern \fB<Control\-Button\-1>\fR will match
394 the event, but \fB<Mod1\-Button\-1>\fR will not.
395 If no modifiers are specified, then any combination of modifiers may
396 be present in the event.
398 \fBMeta\fR and \fBM\fR refer to whichever of the
399 \fBM1\fR through \fBM5\fR modifiers is associated with the Meta
400 key(s) on the keyboard (keysyms \fBMeta_R\fR and \fBMeta_L\fR).
401 If there are no Meta keys, or if they are not associated with any
402 modifiers, then \fBMeta\fR and \fBM\fR will not match any events.
403 Similarly, the \fBAlt\fR modifier refers to whichever modifier
404 is associated with the alt key(s) on the keyboard (keysyms
405 \fBAlt_L\fR and \fBAlt_R\fR).
407 The \fBDouble\fR, \fBTriple\fR and \fBQuadruple\fR modifiers are a
408 convenience for specifying double mouse clicks and other repeated
409 events. They cause a particular event pattern to be repeated 2, 3 or 4
410 times, and also place a time and space requirement on the sequence: for a
411 sequence of events to match a \fBDouble\fR, \fBTriple\fR or \fBQuadruple\fR
412 pattern, all of the events must occur close together in time and without
413 substantial mouse motion in between. For example, \fB<Double\-Button\-1>\fR
414 is equivalent to \fB<Button\-1><Button\-1>\fR with the extra time and space
417 The \fBCommand\fR and \fBOption\fR modifiers are equivalents of \fBMod1\fR
418 resp. \fBMod2\fR, they correspond to Macintosh-specific modifier keys.
420 The \fBExtended\fR modifier is, at present, specific to Windows. It
421 appears on events that are associated with the keys on the
422 .QW "extended keyboard" .
423 On a US keyboard, the extended keys include the \fBAlt\fR
424 and \fBControl\fR keys at the right of the keyboard, the cursor keys
425 in the cluster to the left of the numeric pad, the \fBNumLock\fR key,
426 the \fBBreak\fR key, the \fBPrintScreen\fR key, and the \fB/\fR and
427 \fBEnter\fR keys in the numeric keypad.
430 The \fItype\fR field may be any of the standard X event types, with a
431 few extra abbreviations. The \fItype\fR field will also accept a
432 couple non-standard X event types that were added to better support
433 the Macintosh and Windows platforms. Below is a list of all the valid
434 types; where two names appear together, they are synonyms.
436 .ta \w'\fBButtonPress, Button\0\0\0\fR'u +\w'\fBKeyPress, Key\0\0\0\fR'u
437 \fBActivate\fR \fBDestroy\fR \fBMap\fR
438 \fBButtonPress\fR, \fBButton\fR \fBEnter\fR \fBMapRequest\fR
439 \fBButtonRelease\fR \fBExpose\fR \fBMotion\fR
440 \fBCirculate\fR \fBFocusIn\fR \fBMouseWheel\fR
441 \fBCirculateRequest\fR \fBFocusOut\fR \fBProperty\fR
442 \fBColormap\fR \fBGravity\fR \fBReparent\fR
443 \fBConfigure\fR \fBKeyPress\fR, \fBKey\fR \fBResizeRequest\fR
444 \fBConfigureRequest\fR \fBKeyRelease\fR \fBUnmap\fR
445 \fBCreate\fR \fBLeave\fR \fBVisibility\fR
448 Most of the above events have the same fields and behaviors as events
449 in the X Windowing system. You can find more detailed descriptions of
450 these events in any X window programming book. A couple of the events
451 are extensions to the X event system to support features unique to the
452 Macintosh and Windows platforms. We provide a little more detail on
453 these events here. These include:
454 .IP "\fBActivate\fR, \fBDeactivate\fR" 5
455 These two events are sent to every sub-window of a toplevel when they
456 change state. In addition to the focus Window, the Macintosh platform
457 and Windows platforms have a notion of an active window (which often
458 has but is not required to have the focus). On the Macintosh, widgets
459 in the active window have a different appearance than widgets in
460 deactive windows. The \fBActivate\fR event is sent to all the
461 sub-windows in a toplevel when it changes from being deactive to
462 active. Likewise, the \fBDeactive\fR event is sent when the window's
463 state changes from active to deactive. There are no useful percent
464 substitutions you would make when binding to these events.
465 .IP \fBMouseWheel\fR 5
466 Many contemporary mice support a mouse wheel, which is used
467 for scrolling documents without using the scrollbars. By rolling the
468 wheel, the system will generate \fBMouseWheel\fR events that the
469 application can use to scroll. Like \fBKey\fR events the event is
470 always routed to the window that currently has focus. When the event
471 is received you can use the \fB%D\fR substitution to get the
472 \fIdelta\fR field for the event, which is a integer value describing how
473 the mouse wheel has moved. The smallest value for which the
474 system will report is defined by the OS. The sign of the
475 value determines which direction your widget should scroll. Positive
476 values should scroll up and negative values should scroll down.
477 .IP "\fBKeyPress\fR, \fBKeyRelease\fR" 5
478 The \fBKeyPress\fR and \fBKeyRelease\fR events are generated
479 whenever a key is pressed or released. \fBKeyPress\fR and \fBKeyRelease\fR
480 events are sent to the window which currently has the keyboard focus.
481 .IP "\fBButtonPress\fR, \fBButtonRelease\fR, \fBMotion\fR" 5
482 The \fBButtonPress\fR and \fBButtonRelease\fR events
483 are generated when the user presses or releases a mouse button.
484 \fBMotion\fR events are generated whenever the pointer is moved.
485 \fBButtonPress\fR, \fBButtonRelease\fR, and \fBMotion\fR events are
486 normally sent to the window containing the pointer.
489 When a mouse button is pressed, the window containing the pointer
490 automatically obtains a temporary pointer grab.
491 Subsequent \fBButtonPress\fR, \fBButtonRelease\fR, and \fBMotion\fR
492 events will be sent to that window,
493 regardless of which window contains the pointer,
494 until all buttons have been released.
496 .IP \fBConfigure\fR 5
497 A \fBConfigure\fR event is sent to a window whenever its
498 size, position, or border width changes, and sometimes
499 when it has changed position in the stacking order.
500 .IP "\fBMap\fR, \fBUnmap\fR" 5
501 The \fBMap\fR and \fBUnmap\fR events are generated whenever the mapping
502 state of a window changes.
505 Windows are created in the unmapped state.
506 Top-level windows become mapped when they transition to the
507 \fBnormal\fR state, and are unmapped in the \fBwithdrawn\fR
508 and \fBiconic\fR states.
509 Other windows become mapped when they are placed under control
510 of a geometry manager (for example \fBpack\fR or \fBgrid\fR).
512 A window is \fIviewable\fR only if it and all of its ancestors are mapped.
513 Note that geometry managers typically do not map their children until
514 they have been mapped themselves, and unmap all children
515 when they become unmapped; hence in Tk \fBMap\fR and \fBUnmap\fR
516 events indicate whether or not a window is viewable.
518 .IP \fBVisibility\fR 5
519 A window is said to be \fIobscured\fR when another window
520 above it in the stacking order fully or partially overlaps it.
521 \fBVisibility\fR events are generated whenever a window's
522 obscurity state changes; the \fIstate\fR field (\fB%s\fR)
523 specifies the new state.
525 An \fBExpose\fR event is generated whenever all or part of a
526 window should be redrawn (for example, when a window is
527 first mapped or if it becomes unobscured).
528 It is normally not necessary for client applications to
529 handle \fBExpose\fR events, since Tk handles them internally.
531 A \fBDestroy\fR event is delivered to a window when
535 When the \fBDestroy\fR event is delivered
536 to a widget, it is in a
538 state: the widget still exists, but most operations on it will fail.
540 .IP "\fBFocusIn\fR, \fBFocusOut\fR" 5
541 The \fBFocusIn\fR and \fBFocusOut\fR events are generated
542 whenever the keyboard focus changes.
543 A \fBFocusOut\fR event is sent to the old focus window,
544 and a \fBFocusIn\fR event is sent to the new one.
548 if the old and new focus windows do not share a common parent,
549 .QW "virtual crossing"
550 focus events are sent to the intermediate windows in the hierarchy.
551 Thus a \fBFocusIn\fR event indicates
552 that the target window or one of its descendants has acquired the focus,
553 and a \fBFocusOut\fR event indicates that the focus
554 has been changed to a window outside the target window's hierarchy.
556 The keyboard focus may be changed explicitly by a call to \fBfocus\fR,
557 or implicitly by the window manager.
559 .IP "\fBEnter\fR, \fBLeave\fR" 5
560 An \fBEnter\fR event is sent to a window when the pointer
561 enters that window, and a \fBLeave\fR event is sent when
562 the pointer leaves it.
565 If there is a pointer grab in effect, \fBEnter\fR and \fBLeave\fR
566 events are only delivered to the window owning the grab.
568 In addition, when the pointer moves
569 between two windows, \fBEnter\fR and \fBLeave\fR
570 .QW "virtual crossing"
571 events are sent to intermediate windows
572 in the hierarchy in the same manner as for \fBFocusIn\fR and
573 \fBFocusOut\fR events.
576 A \fBProperty\fR event is sent to a window whenever an X property
577 belonging to that window is changed or deleted.
578 \fBProperty\fR events are not normally delivered to Tk applications as
579 they are handled by the Tk core.
581 A \fBColormap\fR event is generated whenever the colormap
582 associated with a window has been changed, installed, or uninstalled.
585 Widgets may be assigned a private colormap by
586 specifying a \fB\-colormap\fR option; the window manager
587 is responsible for installing and uninstalling colormaps
590 Note that Tk provides no useful details for this event type.
592 '\" The following events were added in TIP#47
593 .IP "\fBMapRequest\fR, \fBCirculateRequest\fR, \fBResizeRequest\fR, \fBConfigureRequest\fR, \fBCreate\fR" 5
594 These events are not normally delivered to Tk applications.
595 They are included for completeness, to make it possible to
596 write X11 window managers in Tk.
597 (These events are only delivered when a client has
598 selected \fBSubstructureRedirectMask\fR on a window;
599 the Tk core does not use this mask.)
600 .IP "\fBGravity\fR, \fBReparent\fR, \fBCirculate\fR" 5
601 The events \fBGravity\fR and \fBReparent\fR
602 are not normally delivered to Tk applications.
603 They are included for completeness.
606 A \fBCirculate\fR event indicates that the window has moved
607 to the top or to the bottom of the stacking order as
608 a result of an \fBXCirculateSubwindows\fR protocol request.
609 Note that the stacking order may be changed for other reasons
610 which do not generate a \fBCirculate\fR event, and that
611 Tk does not use \fBXCirculateSubwindows()\fR internally.
612 This event type is included only for completeness;
613 there is no reliable way to track changes to a window's
614 position in the stacking order.
618 The last part of a long event specification is \fIdetail\fR. In the
619 case of a \fBButtonPress\fR or \fBButtonRelease\fR event, it is the
620 number of a button (1\-5). If a button number is given, then only an
621 event on that particular button will match; if no button number is
622 given, then an event on any button will match. Note: giving a
623 specific button number is different than specifying a button modifier;
624 in the first case, it refers to a button being pressed or released,
625 while in the second it refers to some other button that is already
626 depressed when the matching event occurs. If a button
627 number is given then \fItype\fR may be omitted: if will default
628 to \fBButtonPress\fR. For example, the specifier \fB<1>\fR
629 is equivalent to \fB<ButtonPress\-1>\fR.
631 If the event type is \fBKeyPress\fR or \fBKeyRelease\fR, then
632 \fIdetail\fR may be specified in the form of an X keysym. Keysyms
633 are textual specifications for particular keys on the keyboard;
634 they include all the alphanumeric ASCII characters (e.g.
636 is the keysym for the ASCII character
638 plus descriptions for non-alphanumeric characters
639 .PQ comma "is the keysym for the comma character" ,
640 plus descriptions for all the non-ASCII keys on the keyboard (e.g.
642 is the keysym for the left shift key, and
644 is the keysym for the F1 function key, if it exists). The
645 complete list of keysyms is not presented here; it is
646 available in other X documentation and may vary from system to
648 If necessary, you can use the \fB%K\fR notation described below
649 to print out the keysym name for a particular key.
650 If a keysym \fIdetail\fR is given, then the
651 \fItype\fR field may be omitted; it will default to \fBKeyPress\fR.
652 For example, \fB<Control\-comma>\fR is equivalent to
653 \fB<Control\-KeyPress\-comma>\fR.
654 .SH "BINDING SCRIPTS AND SUBSTITUTIONS"
656 The \fIscript\fR argument to \fBbind\fR is a Tcl script,
657 which will be executed whenever the given event sequence occurs.
658 \fICommand\fR will be executed in the same interpreter that the
659 \fBbind\fR command was executed in, and it will run at global
660 level (only global variables will be accessible).
661 If \fIscript\fR contains
662 any \fB%\fR characters, then the script will not be
663 executed directly. Instead, a new script will be
664 generated by replacing each \fB%\fR, and the character following
665 it, with information from the current event. The replacement
666 depends on the character following the \fB%\fR, as defined in the
667 list below. Unless otherwise indicated, the
668 replacement string is the decimal value of the given field from
670 Some of the substitutions are only valid for
671 certain types of events; if they are used for other types of events
672 the value substituted is undefined.
674 Replaced with a single percent.
676 The number of the last client request processed by the server
677 (the \fIserial\fR field from the event). Valid for all event
680 The \fIabove\fR field from the event,
681 formatted as a hexadecimal number.
682 Valid only for \fBConfigure\fR events.
683 Indicates the sibling window immediately below the receiving window
684 in the stacking order, or \fB0\fR if the receiving window is at the
687 The number of the button that was pressed or released. Valid only
688 for \fBButtonPress\fR and \fBButtonRelease\fR events.
690 The \fIcount\fR field from the event. Valid only for \fBExpose\fR events.
691 Indicates that there are \fIcount\fR pending \fBExpose\fR events which have not
692 yet been delivered to the window.
694 The \fIdetail\fR or \fIuser_data\fR
695 field from the event. The \fB%d\fR is replaced by
696 a string identifying the detail. For \fBEnter\fR,
697 \fBLeave\fR, \fBFocusIn\fR, and \fBFocusOut\fR events,
698 the string will be one of the following:
702 \fBNotifyAncestor\fR \fBNotifyNonlinearVirtual\fR
703 \fBNotifyDetailNone\fR \fBNotifyPointer\fR
704 \fBNotifyInferior\fR \fBNotifyPointerRoot\fR
705 \fBNotifyNonlinear\fR \fBNotifyVirtual\fR
707 For \fBConfigureRequest\fR events, the string will be one of:
710 \fBAbove\fR \fBOpposite\fR
711 \fBBelow\fR \fBNone\fR
712 \fBBottomIf\fR \fBTopIf\fR
714 For virtual events, the string will be whatever value is stored in the
715 \fIuser_data\fR field when the event was created (typically with
716 \fBevent generate\fR), or the empty string if the field is NULL.
717 Virtual events corresponding to key sequence presses (see \fBevent
718 add\fR for details) set the \fIuser_data\fR to NULL.
719 For events other than these, the substituted string is undefined.
722 The \fIfocus\fR field from the event (\fB0\fR or \fB1\fR). Valid only
723 for \fBEnter\fR and \fBLeave\fR events. \fB1\fR if the receiving
724 window is the focus window or a descendant of the focus window,
727 The \fIheight\fR field from the event. Valid for the \fBConfigure\fR,
728 \fBConfigureRequest\fR, \fBCreate\fR, \fBResizeRequest\fR, and
730 Indicates the new or requested height of the window.
732 The \fIwindow\fR field from the event, represented as a hexadecimal
733 integer. Valid for all event types.
735 The \fIkeycode\fR field from the event. Valid only for \fBKeyPress\fR
736 and \fBKeyRelease\fR events.
738 The \fImode\fR field from the event. The substituted string is one of
739 \fBNotifyNormal\fR, \fBNotifyGrab\fR, \fBNotifyUngrab\fR, or
740 \fBNotifyWhileGrabbed\fR. Valid only for \fBEnter\fR,
741 \fBFocusIn\fR, \fBFocusOut\fR, and \fBLeave\fR events.
743 The \fIoverride_redirect\fR field from the event. Valid only for
744 \fBMap\fR, \fBReparent\fR, and \fBConfigure\fR events.
746 The \fIplace\fR field from the event, substituted as one of the
747 strings \fBPlaceOnTop\fR or \fBPlaceOnBottom\fR. Valid only
748 for \fBCirculate\fR and \fBCirculateRequest\fR events.
750 The \fIstate\fR field from the event. For \fBButtonPress\fR,
751 \fBButtonRelease\fR, \fBEnter\fR, \fBKeyPress\fR, \fBKeyRelease\fR,
752 \fBLeave\fR, and \fBMotion\fR events, a decimal string
753 is substituted. For \fBVisibility\fR, one of the strings
754 \fBVisibilityUnobscured\fR, \fBVisibilityPartiallyObscured\fR,
755 and \fBVisibilityFullyObscured\fR is substituted.
756 For \fBProperty\fR events, substituted with
757 either the string \fBNewValue\fR (indicating that the property
758 has been created or modified) or \fBDelete\fR (indicating that
759 the property has been removed).
761 The \fItime\fR field from the event.
762 This is the X server timestamp (typically the time since
763 the last server reset) in milliseconds, when the event occurred.
764 Valid for most events.
766 The \fIwidth\fR field from the event.
767 Indicates the new or requested width of the window.
769 \fBConfigure\fR, \fBConfigureRequest\fR, \fBCreate\fR,
770 \fBResizeRequest\fR, and \fBExpose\fR events.
771 .IP "\fB%x\fR, \fB%y\fR" 5
772 The \fIx\fR and \fIy\fR fields from the event.
773 For \fBButtonPress\fR, \fBButtonRelease\fR, \fBMotion\fR,
774 \fBKeyPress\fR, \fBKeyRelease\fR, and \fBMouseWheel\fR events,
775 \fB%x\fR and \fB%y\fR indicate the position of the mouse pointer
776 relative to the receiving window.
777 For \fBEnter\fR and \fBLeave\fR events, the position where the
778 mouse pointer crossed the window, relative to the receiving window.
779 For \fBConfigure\fR and \fBCreate\fR requests, the \fIx\fR and \fIy\fR
780 coordinates of the window relative to its parent window.
782 Substitutes the UNICODE character corresponding to the event, or
783 the empty string if the event does not correspond to a UNICODE character
784 (e.g. the shift key was pressed). \fBXmbLookupString\fR (or
785 \fBXLookupString\fR when input method support is turned off) does all
786 the work of translating from the event to a UNICODE character.
787 Valid only for \fBKeyPress\fR and \fBKeyRelease\fR events.
789 The \fIborder_width\fR field from the event. Valid only for
790 \fBConfigure\fR, \fBConfigureRequest\fR, and \fBCreate\fR events.
792 This reports the \fIdelta\fR value of a \fBMouseWheel\fR event. The
793 \fIdelta\fR value represents the rotation units the mouse wheel has
794 been moved. The sign of the value represents the direction the mouse
797 The \fIsend_event\fR field from the event. Valid for all event types.
798 \fB0\fR indicates that this is a
800 event, \fB1\fR indicates that it is a
802 event generated by \fBSendEvent\fR.
804 The keysym corresponding to the event, substituted as a textual
805 string. Valid only for \fBKeyPress\fR and \fBKeyRelease\fR events.
807 The number of script-based binding patterns matched so far for the
808 event. Valid for all event types.
810 The keysym corresponding to the event, substituted as a decimal
811 number. Valid only for \fBKeyPress\fR and \fBKeyRelease\fR events.
813 The name of the property being updated or deleted (which
814 may be converted to an XAtom using \fBwinfo atom\fR.) Valid
815 only for \fBProperty\fR events.
817 The \fIroot\fR window identifier from the event. Valid only for
818 events containing a \fIroot\fR field.
820 The \fIsubwindow\fR window identifier from the event,
821 formatted as a hexadecimal number.
822 Valid only for events containing a \fIsubwindow\fR field.
824 The \fItype\fR field from the event. Valid for all event types.
826 The path name of the window to which the event was reported (the
827 \fIwindow\fR field from the event). Valid for all event types.
828 .IP "\fB%X\fR, \fB%Y\fR" 5
829 The \fIx_root\fR and \fIy_root\fR fields from the event.
830 If a virtual-root window manager is being used then the substituted
831 values are the corresponding x-coordinate and y-coordinate in the virtual root.
833 \fBButtonPress\fR, \fBButtonRelease\fR, \fBKeyPress\fR, \fBKeyRelease\fR,
834 and \fBMotion\fR events.
835 Same meaning as \fB%x\fR and \fB%y\fR, except relative to the (virtual) root
838 The replacement string for a %-replacement is formatted as a proper
840 This means that spaces or special characters such as \fB$\fR and
841 \fB{\fR may be preceded by backslashes.
842 This guarantees that the string will be passed through the Tcl
843 parser when the binding script is evaluated.
844 Most replacements are numbers or well-defined strings such
845 as \fBAbove\fR; for these replacements no special formatting
847 The most common case where reformatting occurs is for the \fB%A\fR
848 substitution. For example, if \fIscript\fR is
852 and the character typed is an open square bracket, then the script
853 actually executed will be
857 This will cause the \fBinsert\fR to receive the original replacement
858 string (open square bracket) as its first argument.
859 If the extra backslash had not been added, Tcl would not have been
860 able to parse the script correctly.
861 .SH "MULTIPLE MATCHES"
863 It is possible for several bindings to match a given X event.
864 If the bindings are associated with different \fItag\fR's,
865 then each of the bindings will be executed, in order.
866 By default, a binding for the widget will be executed first, followed
867 by a class binding, a binding for its toplevel, and
868 an \fBall\fR binding.
869 The \fBbindtags\fR command may be used to change this order for
870 a particular window or to associate additional binding tags with
873 The \fBcontinue\fR and \fBbreak\fR commands may be used inside a
874 binding script to control the processing of matching scripts.
875 If \fBcontinue\fR is invoked, then the current binding script
876 is terminated but Tk will continue processing binding scripts
877 associated with other \fItag\fR's.
878 If the \fBbreak\fR command is invoked within a binding script,
879 then that script terminates and no other scripts will be invoked
882 If more than one binding matches a particular event and they
883 have the same \fItag\fR, then the most specific binding
884 is chosen and its script is evaluated.
885 The following tests are applied, in order, to determine which of
886 several matching sequences is more specific:
889 an event pattern that specifies a specific button or key is more specific
890 than one that does not;
892 a longer sequence (in terms of number
893 of events matched) is more specific than a shorter sequence;
895 if the modifiers specified in one pattern are a subset of the
896 modifiers in another pattern, then the pattern with more modifiers
899 a virtual event whose physical pattern matches the sequence is less
900 specific than the same physical pattern that is not associated with a
903 given a sequence that matches two or more virtual events, one
904 of the virtual events will be chosen, but the order is undefined.
907 If the matching sequences contain more than one event, then tests
908 (c)\-(e) are applied in order from the most recent event to the least recent
909 event in the sequences. If these tests fail to determine a winner, then the
910 most recently registered sequence is the winner.
912 If there are two (or more) virtual events that are both triggered by the
913 same sequence, and both of those virtual events are bound to the same window
914 tag, then only one of the virtual events will be triggered, and it will
917 event add <<Paste>> <Control\-y>
918 event add <<Paste>> <Button\-2>
919 event add <<Scroll>> <Button\-2>
920 \fBbind\fR Entry <<Paste>> {puts Paste}
921 \fBbind\fR Entry <<Scroll>> {puts Scroll}
923 If the user types Control\-y, the \fB<<Paste>>\fR binding
924 will be invoked, but if the user presses button 2 then one of
925 either the \fB<<Paste>>\fR or the \fB<<Scroll>>\fR bindings will
926 be invoked, but exactly which one gets invoked is undefined.
928 If an X event does not match any of the existing bindings, then the
930 An unbound event is not considered to be an error.
931 .SH "MULTI-EVENT SEQUENCES AND IGNORED EVENTS"
933 When a \fIsequence\fR specified in a \fBbind\fR command contains
934 more than one event pattern, then its script is executed whenever
935 the recent events (leading up to and including the current event)
936 match the given sequence. This means, for example, that if button 1 is
937 clicked repeatedly the sequence \fB<Double\-ButtonPress\-1>\fR will match
938 each button press but the first.
939 If extraneous events that would prevent a match occur in the middle
940 of an event sequence then the extraneous events are
941 ignored unless they are \fBKeyPress\fR or \fBButtonPress\fR events.
942 For example, \fB<Double\-ButtonPress\-1>\fR will match a sequence of
943 presses of button 1, even though there will be \fBButtonRelease\fR
944 events (and possibly \fBMotion\fR events) between the
945 \fBButtonPress\fR events.
946 Furthermore, a \fBKeyPress\fR event may be preceded by any number
947 of other \fBKeyPress\fR events for modifier keys without the
948 modifier keys preventing a match.
949 For example, the event sequence \fBaB\fR will match a press of the
950 \fBa\fR key, a release of the \fBa\fR key, a press of the \fBShift\fR
951 key, and a press of the \fBb\fR key: the press of \fBShift\fR is
952 ignored because it is a modifier key.
953 Finally, if several \fBMotion\fR events occur in a row, only
954 the last one is used for purposes of matching binding sequences.
957 If an error occurs in executing the script for a binding then the
958 \fBbgerror\fR mechanism is used to report the error.
959 The \fBbgerror\fR command will be executed at global level
960 (outside the context of any Tcl procedure).
963 Arrange for a string describing the motion of the mouse to be printed
964 out when the mouse is double-clicked:
966 \fBbind\fR . <Double\-1> {
967 puts "hi from (%x,%y)"
971 A little GUI that displays what the keysym name of the last key
974 set keysym "Press any key"
975 pack [label .l \-textvariable keysym \-padx 2m \-pady 1m]
977 set keysym "You pressed %K"
981 bgerror(n), bindtags(n), event(n), focus(n), grab(n), keysyms(n)
OSDN Git Service
