1bind(n) Tk Built-In Commands bind(n)
2______________________________________________________________________________
6
8 bind - Arrange for X events to invoke Tcl scripts
9
11 bind tag ?sequence? ?+??script?
12_________________________________________________________________
13
16 The bind command associates Tcl scripts with X events. If all three
17 arguments are specified, bind will arrange for script (a Tcl script) to
18 be evaluated whenever the event(s) given by sequence occur in the win‐
19 dow(s) identified by tag. If script is prefixed with a ``+'', then it
20 is appended to any existing binding for sequence; otherwise script
21 replaces any existing binding. If script is an empty string then the
22 current binding for sequence is destroyed, leaving sequence unbound.
23 In all of the cases where a script argument is provided, bind returns
24 an empty string.
25 If sequence is specified without a script, then the script currently
27 bound to sequence is returned, or an empty string is returned if there
28 is no binding for sequence. If neither sequence nor script is speci‐
29 fied, then the return value is a list whose elements are all the
30 sequences for which there exist bindings for tag.
31 The tag argument determines which window(s) the binding applies to. If
33 tag begins with a dot, as in .a.b.c, then it must be the path name for
34 a window; otherwise it may be an arbitrary string. Each window has an
35 associated list of tags, and a binding applies to a particular window
36 if its tag is among those specified for the window. Although the bind‐
37 tags command may be used to assign an arbitrary set of binding tags to
38 a window, the default binding tags provide the following behavior:
39 · If a tag is the name of an internal window the binding applies to
41 that window.
42 · If the tag is the name of a toplevel window the binding applies to
44 the toplevel window and all its internal windows.
45 · If the tag is the name of a class of widgets, such as Button, the
47 binding applies to all widgets in that class;
48 · If tag has the value all, the binding applies to all windows in the
50 application.
51
53 The sequence argument specifies a sequence of one or more event pat‐
54 terns, with optional white space between the patterns. Each event pat‐ │
55 tern may take one of three forms. In the simplest case it is a single
56 printing ASCII character, such as a or [. The character may not be a
57 space character or the character <. This form of pattern matches a
58 KeyPress event for the particular character. The second form of pat‐
59 tern is longer but more general. It has the following syntax:
60 <modifier-modifier-type-detail>
61 The entire event pattern is surrounded by angle brackets. Inside the
62 angle brackets are zero or more modifiers, an event type, and an extra
63 piece of information (detail) identifying a particular button or
64 keysym. Any of the fields may be omitted, as long as at least one of
65 type and detail is present. The fields must be separated by white
66 space or dashes. │
67 The third form of pattern is used to specify a user-defined, named vir‐ │
69 tual event. It has the following syntax: │
70 <<name>> │
71 The entire virtual event pattern is surrounded by double angle brack‐ │
72 ets. Inside the angle brackets is the user-defined name of the virtual │
73 event. Modifiers, such as Shift or Control, may not be combined with a │
74 virtual event to modify it. Bindings on a virtual event may be created │
75 before the virtual event is defined, and if the definition of a virtual │
76 event changes dynamically, all windows bound to that virtual event will │
77 respond immediately to the new definition. │
78 Some widgets (e.g. menu and text) issue virtual events when their │
80 internal state is updated in some ways. Please see the manual page for │
81 each widget for details.
82
84 Modifiers consist of any of the following values: Con‐
85 trol Mod2, M2 Shift Mod3, M3
86 Lock Mod4, M4 Button1, B1 Mod5, M5 But‐
87 ton2, B2 Meta, M Button3, B3 Alt Button4,
88 B4 Double Button5, B5 Triple Mod1,
89 M1 Quadruple Where more than one value is listed, sepa‐
90 rated by commas, the values are equivalent. Most of the modifiers have
91 the obvious X meanings. For example, Button1 requires that button 1 be
92 depressed when the event occurs. For a binding to match a given event,
93 the modifiers in the event must include all of those specified in the
94 event pattern. An event may also contain additional modifiers not
95 specified in the binding. For example, if button 1 is pressed while
96 the shift and control keys are down, the pattern <Control-Button-1>
97 will match the event, but <Mod1-Button-1> will not. If no modifiers
98 are specified, then any combination of modifiers may be present in the
99 event.
100 Meta and M refer to whichever of the M1 through M5 modifiers is associ‐
102 ated with the Meta key(s) on the keyboard (keysyms Meta_R and Meta_L).
103 If there are no Meta keys, or if they are not associated with any modi‐
104 fiers, then Meta and M will not match any events. Similarly, the Alt
105 modifier refers to whichever modifier is associated with the alt key(s)
106 on the keyboard (keysyms Alt_L and Alt_R).
107 The Double, Triple and Quadruple modifiers are a convenience for speci‐
109 fying double mouse clicks and other repeated events. They cause a par‐
110 ticular event pattern to be repeated 2, 3 or 4 times, and also place a
111 time and space requirement on the sequence: for a sequence of events to
112 match a Double, Triple or Quadruple pattern, all of the events must
113 occur close together in time and without substantial mouse motion in
114 between. For example, <Double-Button-1> is equivalent to <But‐
115 ton-1><Button-1> with the extra time and space requirement.
116
119 The type field may be any of the standard X event types, with a few
120 extra abbreviations. The type field will also accept a couple non-
121 standard X event types that were added to better support the Macintosh
122 and Windows platforms. Below is a list of all the valid types; where
123 two names appear together, they are synonyms. Acti‐
124 vate Destroy Map ButtonPress, But‐
125 ton Enter MapRequest ButtonRe‐
126 lease Expose Motion Circu‐
127 late FocusIn MouseWheel CirculateRequest Focu‐
128 sOut Property Colormap Gravity Reparent
129 Configure KeyPress, KeyResizeRequest Configur‐
130 eRequest KeyRelease Unmap Cre‐
131 ate Leave Visibility Deactivate Most of the │
132 above events have the same fields and behaviors as events in the X Win‐ │
133 dowing system. You can find more detailed descriptions of these events │
134 in any X window programming book. A couple of the events are exten‐ │
135 sions to the X event system to support features unique to the Macintosh │
136 and Windows platforms. We provide a little more detail on these events │
137 here. These include: │
138 Activate, Deactivate │
140 These two events are sent to every sub-window of a toplevel when │
141 they change state. In addition to the focus Window, the Macintosh │
142 platform and Windows platforms have a notion of an active window │
143 (which often has but is not required to have the focus). On the │
144 Macintosh, widgets in the active window have a different appear‐ │
145 ance than widgets in deactive windows. The Activate event is sent │
146 to all the sub-windows in a toplevel when it changes from being │
147 deactive to active. Likewise, the Deactive event is sent when the │
148 window's state changes from active to deactive. There are no use‐ │
149 ful percent substitutions you would make when binding to these │
150 events. │
151 MouseWheel │
153 Some mice on the Windows platform support a mouse wheel which is │
154 used for scrolling documents without using the scrollbars. By │
155 rolling the wheel, the system will generate MouseWheel events that │
156 the application can use to scroll. On Windows, the event is │
157 always routed to the window that currently has focus (like Key │
158 events.) On Mac OS X, the event is routed to the window under the │
159 pointer. When the event is received you can use the %D substitu‐ │
160 tion to get the delta field for the event, which is a integer │
161 value describing how the mouse wheel has moved. The smallest │
162 value for which the system will report is defined by the OS. On │
163 Windows 95 & 98 machines this value is at least 120 before it is │
164 reported. However, higher resolution devices may be available in │
165 the future. On Mac OS X, the value is not scaled by 120, but a │
166 value of 1 corresponds to roughly one text line. The sign of the │
167 value determines which direction your widget should scroll. Posi‐ │
168 tive values should scroll up and negative values should scroll │
169 down.
170 KeyPress, KeyRelease
172 The KeyPress and KeyRelease events are generated whenever a key is
173 pressed or released. KeyPress and KeyRelease events are sent to
174 the window which currently has the keyboard focus.
175 ButtonPress, ButtonRelease, Motion
177 The ButtonPress and ButtonRelease events are generated when the
178 user presses or releases a mouse button. Motion events are gener‐
179 ated whenever the pointer is moved. ButtonPress, ButtonRelease,
180 and Motion events are normally sent to the window containing the
181 pointer.
182 When a mouse button is pressed, the window containing the pointer
184 automatically obtains a temporary pointer grab. Subsequent But‐
185 tonPress, ButtonRelease, and Motion events will be sent to that
186 window, regardless of which window contains the pointer, until all
187 buttons have been released.
188 Configure
190 A Configure event is sent to a window whenever its size, position,
191 or border width changes, and sometimes when it has changed posi‐
192 tion in the stacking order.
193 Map, Unmap
195 The Map and Unmap events are generated whenever the mapping state
196 of a window changes.
197 Windows are created in the unmapped state. Top-level windows
199 become mapped when they transition to the normal state, and are
200 unmapped in the withdrawn and iconic states. Other windows become
201 mapped when they are placed under control of a geometry manager
202 (for example pack or grid).
203 A window is viewable only if it and all of its ancestors are
205 mapped. Note that geometry managers typically do not map their
206 children until they have been mapped themselves, and unmap all
207 children when they become unmapped; hence in Tk Map and Unmap
208 events indicate whether or not a window is viewable.
209 Visibility
211 A window is said to be obscured when another window above it in
212 the stacking order fully or partially overlaps it. Visibility
213 events are generated whenever a window's obscurity state changes;
214 the state field (%s) specifies the new state.
215 Expose
217 An Expose event is generated whenever all or part of a window
218 should be redrawn (for example, when a window is first mapped or
219 if it becomes unobscured). It is normally not necessary for
220 client applications to handle Expose events, since Tk handles them
221 internally.
222 Destroy
224 A Destroy event is delivered to a window when it is destroyed.
225 When the Destroy event is delivered to a widget, it is in a
227 ``half-dead'' state: the widget still exists, but most operations
228 on it will fail.
229 FocusIn, FocusOut
231 The FocusIn and FocusOut events are generated whenever the key‐
232 board focus changes. A FocusOut event is sent to the old focus
233 window, and a FocusIn event is sent to the new one.
234 In addition, if the old and new focus windows do not share a com‐
236 mon parent, ``virtual crossing'' focus events are sent to the
237 intermediate windows in the hierarchy. Thus a FocusIn event indi‐
238 cates that the target window or one of its descendants has
239 acquired the focus, and a FocusOut event indicates that the focus
240 has been changed to a window outside the target window's hierar‐
241 chy.
242 The keyboard focus may be changed explicitly by a call to focus,
244 or implicitly by the window manager.
245 Enter, Leave
247 An Enter event is sent to a window when the pointer enters that
248 window, and a Leave event is sent when the pointer leaves it.
249 If there is a pointer grab in effect, Enter and Leave events are
251 only delivered to the window owning the grab.
252 In addition, when the pointer moves between two windows, Enter and
254 Leave ``virtual crossing'' events are sent to intermediate windows
255 in the hierarchy in the same manner as for FocusIn and FocusOut
256 events.
257 Property
259 A Property event is sent to a window whenever an X property
260 belonging to that window is changed or deleted. Property events
261 are not normally delivered to Tk applications as they are handled
262 by the Tk core.
263 Colormap
265 A Colormap event is generated whenever the colormap associated
266 with a window has been changed, installed, or uninstalled.
267 Widgets may be assigned a private colormap by specifying a -col‐
269 ormap option; the window manager is responsible for installing and
270 uninstalling colormaps as necessary.
271 Note that Tk provides no useful details for this event type.
273 MapRequest, CirculateRequest, ResizeRequest, ConfigureRequest, Create
275 These events are not normally delivered to Tk applications. They
276 are included for completeness, to make it possible to write X11
277 window managers in Tk. (These events are only delivered when a
278 client has selected SubstructureRedirectMask on a window; the Tk
279 core does not use this mask.)
280 Gravity, Reparent, Circulate
282 The events Gravity and Reparent are not normally delivered to Tk
283 applications. They are included for completeness.
284 A Circulate event indicates that the window has moved to the top
286 or to the bottom of the stacking order as a result of an XCircu‐
287 lateSubwindows protocol request. Note that the stacking order may
288 be changed for other reasons which do not generate a Circulate
289 event, and that Tk does not use XCirculateSubwindows() internally.
290 This event type is included only for completeness; there is no
291 reliable way to track changes to a window's position in the stack‐
292 ing order.
293
295 The last part of a long event specification is detail. In the case of
296 a ButtonPress or ButtonRelease event, it is the number of a button
297 (1-5). If a button number is given, then only an event on that partic‐
298 ular button will match; if no button number is given, then an event on
299 any button will match. Note: giving a specific button number is dif‐
300 ferent than specifying a button modifier; in the first case, it refers
301 to a button being pressed or released, while in the second it refers to
302 some other button that is already depressed when the matching event
303 occurs. If a button number is given then type may be omitted: if will
304 default to ButtonPress. For example, the specifier <1> is equivalent
305 to <ButtonPress-1>.
306 If the event type is KeyPress or KeyRelease, then detail may be speci‐
308 fied in the form of an X keysym. Keysyms are textual specifications
309 for particular keys on the keyboard; they include all the alphanumeric
310 ASCII characters (e.g. ``a'' is the keysym for the ASCII character
311 ``a''), plus descriptions for non-alphanumeric characters (``comma'' is
312 the keysym for the comma character), plus descriptions for all the non-
313 ASCII keys on the keyboard (``Shift_L'' is the keysym for the left
314 shift key, and ``F1'' is the keysym for the F1 function key, if it
315 exists). The complete list of keysyms is not presented here; it is
316 available in other X documentation and may vary from system to system.
317 If necessary, you can use the %K notation described below to print out
318 the keysym name for a particular key. If a keysym detail is given,
319 then the type field may be omitted; it will default to KeyPress. For
320 example, <Control-comma> is equivalent to <Control-KeyPress-comma>.
321
323 The script argument to bind is a Tcl script, which will be executed
324 whenever the given event sequence occurs. Command will be executed in
325 the same interpreter that the bind command was executed in, and it will
326 run at global level (only global variables will be accessible). If
327 script contains any % characters, then the script will not be executed
328 directly. Instead, a new script will be generated by replacing each %,
329 and the character following it, with information from the current
330 event. The replacement depends on the character following the %, as
331 defined in the list below. Unless otherwise indicated, the replacement
332 string is the decimal value of the given field from the current event.
333 Some of the substitutions are only valid for certain types of events;
334 if they are used for other types of events the value substituted is
335 undefined.
336 %% Replaced with a single percent.
338 %# The number of the last client request processed by the server (the
340 serial field from the event). Valid for all event types.
341 %a The above field from the event, formatted as a hexadecimal number.
343 Valid only for Configure events. Indicates the sibling window
344 immediately below the receiving window in the stacking order, or 0
345 if the receiving window is at the bottom.
346 %b The number of the button that was pressed or released. Valid only
348 for ButtonPress and ButtonRelease events.
349 %c The count field from the event. Valid only for Expose events.
351 Indicates that there are count pending Expose events which have
352 not yet been delivered to the window.
353 %d The detail field from the event. The %d is replaced by a string
355 identifying the detail. For Enter, Leave, FocusIn, and FocusOut
356 events, the string will be one of the following:
357 NotifyAncestor NotifyNonlinearVirtual NotifyDetail‐
358 None NotifyPointer NotifyInferior NotifyPointer‐
359 Root NotifyNonlinear NotifyVirtual For ConfigureRequest
360 events, the string will be one of: Above Oppo‐
361 site Below None BottomIf TopIf
362 For events other than these, the substituted string is undefined.
363 %f The focus field from the event (0 or 1). Valid only for Enter and
365 Leave events. 1 if the receiving window is the focus window or a
366 descendant of the focus window, 0 otherwise.
367 %h The height field from the event. Valid for the Configure, Config‐ │
369 ureRequest, Create, ResizeRequest, and Expose events. Indicates │
370 the new or requested height of the window.
371 %i The window field from the event, represented as a hexadecimal
373 integer. Valid for all event types.
374 %k The keycode field from the event. Valid only for KeyPress and
376 KeyRelease events.
377 %m The mode field from the event. The substituted string is one of
379 NotifyNormal, NotifyGrab, NotifyUngrab, or NotifyWhileGrabbed. │
380 Valid only for Enter, FocusIn, FocusOut, and Leave events.
381 %o The override_redirect field from the event. Valid only for Map,
383 Reparent, and Configure events.
384 %p The place field from the event, substituted as one of the strings
386 PlaceOnTop or PlaceOnBottom. Valid only for Circulate and Circu‐
387 lateRequest events.
388 %s The state field from the event. For ButtonPress, ButtonRelease,
390 Enter, KeyPress, KeyRelease, Leave, and Motion events, a decimal
391 string is substituted. For Visibility, one of the strings Visi‐
392 bilityUnobscured, VisibilityPartiallyObscured, and VisibilityFul‐
393 lyObscured is substituted. For Property events, substituted with
394 either the string NewValue (indicating that the property has been
395 created or modified) or Delete (indicating that the property has
396 been removed).
397 %t The time field from the event. This is the X server timestamp
399 (typically the time since the last server reset) in milliseconds,
400 when the event occurred. Valid for most events.
401 %w The width field from the event. Indicates the new or requested
403 width of the window. Valid only for Configure, ConfigureRequest, │
404 Create, ResizeRequest, and Expose events.
405 %x, %y
407 The x and y fields from the event. For ButtonPress, ButtonRe‐
408 lease, Motion, KeyPress, KeyRelease, and MouseWheel events, %x and
409 %y indicate the position of the mouse pointer relative to the
410 receiving window. For Enter and Leave events, the position where
411 the mouse pointer crossed the window, relative to the receiving
412 window. For Configure and Create requests, the x and y coordi‐
413 nates of the window relative to its parent window.
414 %A Substitutes the UNICODE character corresponding to the event, or
416 the empty string if the event doesn't correspond to a UNICODE
417 character (e.g. the shift key was pressed). XmbLookupString (or
418 XLookupString when input method support is turned off) does all
419 the work of translating from the event to a UNICODE character.
420 Valid only for KeyPress and KeyRelease events.
421 %B The border_width field from the event. Valid only for Configure,
423 ConfigureRequest, and Create events.
424 %D This reports the delta value of a MouseWheel event. The delta │
426 value represents the rotation units the mouse wheel has been │
427 moved. On Windows 95 & 98 systems the smallest value for the │
428 delta is 120. Future systems may support higher resolution values │
429 for the delta. The sign of the value represents the direction the │
430 mouse wheel was scrolled.
431 %E The send_event field from the event. Valid for all event types.
433 0 indicates that this is a ``normal'' event, 1 indicates that it
434 is a ``synthetic'' event generated by SendEvent.
435 %K The keysym corresponding to the event, substituted as a textual
437 string. Valid only for KeyPress and KeyRelease events.
438 %N The keysym corresponding to the event, substituted as a decimal
440 number. Valid only for KeyPress and KeyRelease events.
441 %P The name of the property being updated or deleted (which may be
443 converted to an XAtom using winfo atom.) Valid only for Property
444 events.
445 %R The root window identifier from the event. Valid only for events
447 containing a root field.
448 %S The subwindow window identifier from the event, formatted as a
450 hexadecimal number. Valid only for events containing a subwindow
451 field.
452 %T The type field from the event. Valid for all event types.
454 %W The path name of the window to which the event was reported (the
456 window field from the event). Valid for all event types.
457 %X The x_root field from the event. If a virtual-root window manager
459 is being used then the substituted value is the corresponding x-
460 coordinate in the virtual root. Valid only for ButtonPress, But‐
461 tonRelease, KeyPress, KeyRelease, and Motion events. Same meaning
462 as %x, except relative to the (virtual) root window.
463 %Y The y_root field from the event. If a virtual-root window manager
465 is being used then the substituted value is the corresponding y-
466 coordinate in the virtual root. Valid only for ButtonPress, But‐
467 tonRelease, KeyPress, KeyRelease, and Motion events. Same meaning
468 as %y, except relative to the (virtual) root window.
469 The replacement string for a %-replacement is formatted as a proper Tcl
471 list element. This means that it will be surrounded with braces if it
472 contains spaces, or special characters such as $ and { may be preceded
473 by backslashes. This guarantees that the string will be passed through
474 the Tcl parser when the binding script is evaluated. Most replacements
475 are numbers or well-defined strings such as Above; for these replace‐
476 ments no special formatting is ever necessary. The most common case
477 where reformatting occurs is for the %A substitution. For example, if
478 script is
479 insert %A
480 and the character typed is an open square bracket, then the script
481 actually executed will be
482 insert \[
483 This will cause the insert to receive the original replacement string
484 (open square bracket) as its first argument. If the extra backslash
485 hadn't been added, Tcl would not have been able to parse the script
486 correctly.
487
489 It is possible for several bindings to match a given X event. If the
490 bindings are associated with different tag's, then each of the bindings
491 will be executed, in order. By default, a binding for the widget will
492 be executed first, followed by a class binding, a binding for its
493 toplevel, and an all binding. The bindtags command may be used to
494 change this order for a particular window or to associate additional
495 binding tags with the window.
496 The continue and break commands may be used inside a binding script to
498 control the processing of matching scripts. If continue is invoked,
499 then the current binding script is terminated but Tk will continue pro‐
500 cessing binding scripts associated with other tag's. If the break com‐
501 mand is invoked within a binding script, then that script terminates
502 and no other scripts will be invoked for the event.
503 If more than one binding matches a particular event and they have the
505 same tag, then the most specific binding is chosen and its script is
506 evaluated. The following tests are applied, in order, to determine
507 which of several matching sequences is more specific: (a) an event pat‐
508 tern that specifies a specific button or key is more specific than one
509 that doesn't; (b) a longer sequence (in terms of number of events
510 matched) is more specific than a shorter sequence; (c) if the modifiers
511 specified in one pattern are a subset of the modifiers in another pat‐
512 tern, then the pattern with more modifiers is more specific. (d) a
513 virtual event whose physical pattern matches the sequence is less spe‐
514 cific than the same physical pattern that is not associated with a vir‐
515 tual event. (e) given a sequence that matches two or more virtual
516 events, one of the virtual events will be chosen, but the order is
517 undefined.
518 If the matching sequences contain more than one event, then tests
520 (c)-(e) are applied in order from the most recent event to the least
521 recent event in the sequences. If these tests fail to determine a win‐
522 ner, then the most recently registered sequence is the winner.
523 If there are two (or more) virtual events that are both triggered by
525 the same sequence, and both of those virtual events are bound to the
526 same window tag, then only one of the virtual events will be triggered,
527 and it will be picked at random:
528 event add <<Paste>> <Control-y>
529 event add <<Paste>> <Button-2>
530 event add <<Scroll>> <Button-2>
531 bind Entry <<Paste>> {puts Paste}
532 bind Entry <<Scroll>> {puts Scroll}
533 If the user types Control-y, the <<Paste>> binding will be invoked, but
534 if the user presses button 2 then one of either the <<Paste>> or the
535 <<Scroll>> bindings will be invoked, but exactly which one gets invoked
536 is undefined.
537 If an X event does not match any of the existing bindings, then the
539 event is ignored. An unbound event is not considered to be an error.
540
542 When a sequence specified in a bind command contains more than one
543 event pattern, then its script is executed whenever the recent events
544 (leading up to and including the current event) match the given
545 sequence. This means, for example, that if button 1 is clicked repeat‐
546 edly the sequence <Double-ButtonPress-1> will match each button press
547 but the first. If extraneous events that would prevent a match occur
548 in the middle of an event sequence then the extraneous events are
549 ignored unless they are KeyPress or ButtonPress events. For example,
550 <Double-ButtonPress-1> will match a sequence of presses of button 1,
551 even though there will be ButtonRelease events (and possibly Motion
552 events) between the ButtonPress events. Furthermore, a KeyPress event
553 may be preceded by any number of other KeyPress events for modifier
554 keys without the modifier keys preventing a match. For example, the
555 event sequence aB will match a press of the a key, a release of the a
556 key, a press of the Shift key, and a press of the b key: the press of
557 Shift is ignored because it is a modifier key. Finally, if several
558 Motion events occur in a row, only the last one is used for purposes of
559 matching binding sequences.
560
562 If an error occurs in executing the script for a binding then the bger‐
563 ror mechanism is used to report the error. The bgerror command will be
564 executed at global level (outside the context of any Tcl procedure).
565
567 Arrange for a string describing the motion of the mouse to be printed
568 out when the mouse is double-clicked:
569 bind . <Double-1> {
570 puts "hi from (%x,%y)"
571 }
572 A little GUI that displays what the keysym name of the last key pressed
574 is:
575 set keysym "Press any key"
576 pack [label .l -textvariable keysym -padx 2m -pady 1m]
577 bind . <Key> {
578 set keysym "You pressed %K"
579 }
580
583 bgerror(n), bindtags(n), event(n), focus(n), grab(n), keysyms(n)
584
587 binding, event
588Tk 8.0 bind(n)