1bind(n)                      Tk Built-In Commands                      bind(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       bind - Arrange for X events to invoke Tcl scripts
9

SYNOPSIS

11       bind tag ?sequence? ?+??script?
12______________________________________________________________________________
13

INTRODUCTION

15       The  bind  command  associates Tcl scripts with X events.  If all three
16       arguments are specified, bind will arrange for  script  (a  Tcl  script
17       called  the  “binding  script”)  to  be evaluated whenever the event(s)
18       given by sequence occur in the window(s) identified by tag.  If  script
19       is prefixed with a “+”, then it is appended to any existing binding for
20       sequence;  otherwise script replaces any existing binding.   If  script
21       is  an empty string then the current binding for sequence is destroyed,
22       leaving sequence unbound.  In all of the cases where a script  argument
23       is provided, bind returns an empty string.
24
25       If  sequence  is  specified without a script, then the script currently
26       bound to sequence is returned, or an empty string is returned if  there
27       is  no  binding for sequence.  If neither sequence nor script is speci‐
28       fied, then the return value is  a  list  whose  elements  are  all  the
29       sequences for which there exist bindings for tag.
30
31       The tag argument determines which window(s) the binding applies to.  If
32       tag begins with a dot, as in .a.b.c, then it must be the path name  for
33       a  window; otherwise it may be an arbitrary string.  Each window has an
34       associated list of tags, and a binding applies to a  particular  window
35       if its tag is among those specified for the window.  Although the bind‐
36       tags command may be used to assign an arbitrary set of binding tags  to
37       a window, the default binding tags provide the following behavior:
38
39       ·  If  a  tag  is the name of an internal window the binding applies to
40          that window.
41
42       ·  If the tag is the name of a toplevel window the binding  applies  to
43          the toplevel window and all its internal windows.
44
45       ·  If  the  tag  is the name of a class of widgets, such as Button, the
46          binding applies to all widgets in that class;
47
48       ·  If tag has the value all, the binding applies to all windows in  the
49          application.
50

EVENT PATTERNS

52       The  sequence  argument  specifies a sequence of one or more event pat‐
53       terns, with optional white space between the patterns.  Each event pat‐
54       tern  may take one of three forms.  In the simplest case it is a single
55       printing ASCII character, such as a or [.  The character may not  be  a
56       space  character  or  the  character <.  This form of pattern matches a
57       KeyPress event for the particular character.  The second form  of  pat‐
58       tern is longer but more general.  It has the following syntax:
59              <modifier-modifier-type-detail>
60       The  entire  event pattern is surrounded by angle brackets.  Inside the
61       angle brackets are zero or more modifiers, an event type, and an  extra
62       piece  of  information  (detail)  identifying  a  particular  button or
63       keysym.  Any of the fields may be omitted, as long as at least  one  of
64       type  and  detail  is  present.   The fields must be separated by white
65       space or dashes.
66
67       The third form of pattern is used to specify a user-defined, named vir‐
68       tual event.  It has the following syntax:
69              <<name>>
70       The  entire  virtual event pattern is surrounded by double angle brack‐
71       ets.  Inside the angle brackets is the user-defined name of the virtual
72       event.  Modifiers, such as Shift or Control, may not be combined with a
73       virtual event to modify it.  Bindings on a virtual event may be created
74       before the virtual event is defined, and if the definition of a virtual
75       event changes dynamically, all windows bound to that virtual event will
76       respond immediately to the new definition.
77
78       Some  widgets  (e.g.  menu  and  text)  issue virtual events when their
79       internal state is updated in some ways.  Please see the manual page for
80       each widget for details.
81
82   MODIFIERS
83       Modifiers consist of any of the following values:
84
85              Control                 Mod1, M1, Command
86              Alt                     Mod2, M2, Option
87              Shift                   Mod3, M3
88              Lock                    Mod4, M4
89              Extended                Mod5, M5
90              Button1, B1             Meta, M
91              Button2, B2             Double
92              Button3, B3             Triple
93              Button4, B4             Quadruple
94              Button5, B5
95
96       Where  more  than  one value is listed, separated by commas, the values
97       are equivalent.  Most of the modifiers have  the  obvious  X  meanings.
98       For example, Button1 requires that button 1 be depressed when the event
99       occurs.  For a binding to match a given event,  the  modifiers  in  the
100       event  must  include  all  of those specified in the event pattern.  An
101       event may also contain additional modifiers not specified in the  bind‐
102       ing.   For  example, if button 1 is pressed while the shift and control
103       keys are down, the pattern <Control-Button-1> will match the event, but
104       <Mod1-Button-1> will not.  If no modifiers are specified, then any com‐
105       bination of modifiers may be present in the event.
106
107       Meta and M refer to whichever of the M1 through M5 modifiers is associ‐
108       ated  with the Meta key(s) on the keyboard (keysyms Meta_R and Meta_L).
109       If there are no Meta keys, or if they are not associated with any modi‐
110       fiers,  then  Meta and M will not match any events.  Similarly, the Alt
111       modifier refers to whichever modifier is associated with the alt key(s)
112       on the keyboard (keysyms Alt_L and Alt_R).
113
114       The Double, Triple and Quadruple modifiers are a convenience for speci‐
115       fying double mouse clicks and other repeated events. They cause a  par‐
116       ticular  event pattern to be repeated 2, 3 or 4 times, and also place a
117       time and space requirement on the sequence: for a sequence of events to
118       match  a  Double,  Triple  or Quadruple pattern, all of the events must
119       occur close together in time and without substantial  mouse  motion  in
120       between.    For  example,  <Double-Button-1>  is  equivalent  to  <But‐
121       ton-1><Button-1> with the extra time and space requirement.
122
123       The Command and Option modifiers are equivalents of  Mod1  resp.  Mod2,
124       they correspond to Macintosh-specific modifier keys.
125
126       The  Extended modifier is, at present, specific to Windows.  It appears
127       on events that are associated with the keys on the “extended keyboard”.
128       On a US keyboard, the extended keys include the Alt and Control keys at
129       the right of the keyboard, the cursor keys in the cluster to  the  left
130       of  the  numeric  pad,  the NumLock key, the Break key, the PrintScreen
131       key, and the / and Enter keys in the numeric keypad.
132
133   EVENT TYPES
134       The type field may be any of the standard X event  types,  with  a  few
135       extra  abbreviations.   The  type  field will also accept a couple non-
136       standard X event types that were added to better support the  Macintosh
137       and  Windows  platforms.  Below is a list of all the valid types; where
138       two names appear together, they are synonyms.
139
140              Activate              Destroy         Map
141              ButtonPress, Button   Enter           MapRequest
142              ButtonRelease         Expose          Motion
143              Circulate             FocusIn         MouseWheel
144              CirculateRequest      FocusOut        Property
145              Colormap              Gravity         Reparent
146              Configure             KeyPress, Key   ResizeRequest
147              ConfigureRequest      KeyRelease      Unmap
148              Create                Leave           Visibility
149              Deactivate
150
151       Most of the above events have the same fields and behaviors  as  events
152       in  the X Windowing system.  You can find more detailed descriptions of
153       these events in any X window programming book.  A couple of the  events
154       are  extensions to the X event system to support features unique to the
155       Macintosh and Windows platforms.  We provide a little  more  detail  on
156       these events here.  These include:
157
158       Activate, Deactivate
159            These  two  events are sent to every sub-window of a toplevel when
160            they change state.  In addition to the focus Window, the Macintosh
161            platform  and  Windows platforms have a notion of an active window
162            (which often has but is not required to have the focus).   On  the
163            Macintosh,  widgets  in the active window have a different appear‐
164            ance than widgets in deactive windows.  The Activate event is sent
165            to  all  the  sub-windows in a toplevel when it changes from being
166            deactive to active.  Likewise, the Deactive event is sent when the
167            window's state changes from active to deactive.  There are no use‐
168            ful percent substitutions you would make  when  binding  to  these
169            events.
170
171       MouseWheel
172            Many  contemporary  mice  support a mouse wheel, which is used for
173            scrolling documents without using the scrollbars.  By rolling  the
174            wheel,  the system will generate MouseWheel events that the appli‐
175            cation can use to scroll.  Like Key events  the  event  is  always
176            routed  to  the window that currently has focus. When the event is
177            received you can use the %D substitution to get  the  delta  field
178            for  the  event, which is a integer value describing how the mouse
179            wheel has moved.  The smallest value for  which  the  system  will
180            report  is  defined  by  the  OS. The sign of the value determines
181            which direction your widget should scroll.  Positive values should
182            scroll up and negative values should scroll down.
183
184       KeyPress, KeyRelease
185            The KeyPress and KeyRelease events are generated whenever a key is
186            pressed or released.  KeyPress and KeyRelease events are  sent  to
187            the window which currently has the keyboard focus.
188
189       ButtonPress, ButtonRelease, Motion
190            The  ButtonPress  and  ButtonRelease events are generated when the
191            user presses or releases a mouse button.  Motion events are gener‐
192            ated  whenever  the pointer is moved.  ButtonPress, ButtonRelease,
193            and Motion events are normally sent to the window  containing  the
194            pointer.
195
196            When  a mouse button is pressed, the window containing the pointer
197            automatically obtains a temporary pointer grab.   Subsequent  But‐
198            tonPress,  ButtonRelease,  and  Motion events will be sent to that
199            window, regardless of which window contains the pointer, until all
200            buttons have been released.
201
202       Configure
203            A Configure event is sent to a window whenever its size, position,
204            or border width changes, and sometimes when it has  changed  posi‐
205            tion in the stacking order.
206
207       Map, Unmap
208            The  Map and Unmap events are generated whenever the mapping state
209            of a window changes.
210
211            Windows are created in  the  unmapped  state.   Top-level  windows
212            become  mapped  when  they transition to the normal state, and are
213            unmapped in the withdrawn and iconic states.  Other windows become
214            mapped  when  they  are placed under control of a geometry manager
215            (for example pack or grid).
216
217            A window is viewable only if it  and  all  of  its  ancestors  are
218            mapped.   Note  that  geometry managers typically do not map their
219            children until they have been mapped  themselves,  and  unmap  all
220            children  when  they  become  unmapped;  hence in Tk Map and Unmap
221            events indicate whether or not a window is viewable.
222
223       Visibility
224            A window is said to be obscured when another window  above  it  in
225            the  stacking  order  fully  or partially overlaps it.  Visibility
226            events are generated whenever a window's obscurity state  changes;
227            the state field (%s) specifies the new state.
228
229       Expose
230            An  Expose  event  is  generated  whenever all or part of a window
231            should be redrawn (for example, when a window is first  mapped  or
232            if  it  becomes  unobscured).   It  is  normally not necessary for
233            client applications to handle Expose events, since Tk handles them
234            internally.
235
236       Destroy
237            A Destroy event is delivered to a window when it is destroyed.
238
239            When the Destroy event is delivered to a widget, it is in a “half-
240            dead” state: the widget still exists, but most  operations  on  it
241            will fail.
242
243       FocusIn, FocusOut
244            The  FocusIn  and  FocusOut events are generated whenever the key‐
245            board focus changes.  A FocusOut event is sent to  the  old  focus
246            window, and a FocusIn event is sent to the new one.
247
248            In  addition, if the old and new focus windows do not share a com‐
249            mon parent, “virtual crossing” focus events are sent to the inter‐
250            mediate  windows in the hierarchy.  Thus a FocusIn event indicates
251            that the target window or one of its descendants has acquired  the
252            focus,  and  a  FocusOut  event  indicates that the focus has been
253            changed to a window outside the target window's hierarchy.
254
255            The keyboard focus may be changed explicitly by a call  to  focus,
256            or implicitly by the window manager.
257
258       Enter, Leave
259            An  Enter  event  is sent to a window when the pointer enters that
260            window, and a Leave event is sent when the pointer leaves it.
261
262            If there is a pointer grab in effect, Enter and Leave  events  are
263            only delivered to the window owning the grab.
264
265            In addition, when the pointer moves between two windows, Enter and
266            Leave “virtual crossing” events are sent to  intermediate  windows
267            in  the  hierarchy  in the same manner as for FocusIn and FocusOut
268            events.
269
270       Property
271            A Property event is sent  to  a  window  whenever  an  X  property
272            belonging  to  that window is changed or deleted.  Property events
273            are not normally delivered to Tk applications as they are  handled
274            by the Tk core.
275
276       Colormap
277            A  Colormap  event  is  generated whenever the colormap associated
278            with a window has been changed, installed, or uninstalled.
279
280            Widgets may be assigned a private colormap by specifying  a  -col‐
281            ormap option; the window manager is responsible for installing and
282            uninstalling colormaps as necessary.
283
284            Note that Tk provides no useful details for this event type.
285
286       MapRequest, CirculateRequest, ResizeRequest, ConfigureRequest, Create
287            These events are not normally delivered to Tk applications.   They
288            are  included  for  completeness, to make it possible to write X11
289            window managers in Tk.  (These events are only  delivered  when  a
290            client  has  selected SubstructureRedirectMask on a window; the Tk
291            core does not use this mask.)
292
293       Gravity, Reparent, Circulate
294            The events Gravity and Reparent are not normally delivered  to  Tk
295            applications.  They are included for completeness.
296
297            A  Circulate  event indicates that the window has moved to the top
298            or to the bottom of the stacking order as a result of  an  XCircu‐
299            lateSubwindows protocol request.  Note that the stacking order may
300            be changed for other reasons which do  not  generate  a  Circulate
301            event, and that Tk does not use XCirculateSubwindows() internally.
302            This event type is included only for  completeness;  there  is  no
303            reliable way to track changes to a window's position in the stack‐
304            ing order.
305
306   EVENT DETAILS
307       The last part of a long event specification is detail.  In the case  of
308       a  ButtonPress  or  ButtonRelease  event,  it is the number of a button
309       (1-5).  If a button number is given, then only an event on that partic‐
310       ular button will match;  if no button number is given, then an event on
311       any button will match.  Note:  giving a specific button number is  dif‐
312       ferent  than specifying a button modifier; in the first case, it refers
313       to a button being pressed or released, while in the second it refers to
314       some  other  button  that  is already depressed when the matching event
315       occurs.  If a button number is given then type may be omitted:  if will
316       default  to  ButtonPress.  For example, the specifier <1> is equivalent
317       to <ButtonPress-1>.
318
319       If the event type is KeyPress or KeyRelease, then detail may be  speci‐
320       fied  in  the  form of an X keysym.  Keysyms are textual specifications
321       for particular keys on the keyboard; they include all the  alphanumeric
322       ASCII characters (e.g.  “a” is the keysym for the ASCII character “a”),
323       plus descriptions for non-alphanumeric characters (“comma”is the keysym
324       for  the comma character), plus descriptions for all the non-ASCII keys
325       on the keyboard (e.g.  “Shift_L” is the keysym for the left shift  key,
326       and  “F1”  is  the  keysym for the F1 function key, if it exists).  The
327       complete list of keysyms is not presented here;   it  is  available  in
328       other  X  documentation  and may vary from system to system.  If neces‐
329       sary, you can use the %K notation described  below  to  print  out  the
330       keysym  name  for  a particular key.  If a keysym detail is given, then
331       the type field may be omitted;  it will default to KeyPress.  For exam‐
332       ple, <Control-comma> is equivalent to <Control-KeyPress-comma>.
333

BINDING SCRIPTS AND SUBSTITUTIONS

335       The  script  argument  to  bind  is  a  Tcl script, called the “binding
336       script”, which will be  executed  whenever  the  given  event  sequence
337       occurs.  Command will be executed in the same interpreter that the bind
338       command was executed in, and it will run at global level  (only  global
339       variables  will  be  accessible).  If script contains any % characters,
340       then the script will not be executed directly.  Instead, a  new  script
341       will  be generated by replacing each %, and the character following it,
342       with information from the current event.  The  replacement  depends  on
343       the  character  following  the %, as defined in the list below.  Unless
344       otherwise indicated, the replacement string is the decimal value of the
345       given field from the current event.  Some of the substitutions are only
346       valid for certain types of events;  if they are used for other types of
347       events the value substituted is undefined.
348
349       %%   Replaced with a single percent.
350
351       %#   The number of the last client request processed by the server (the
352            serial field from the event).  Valid for all event types.
353
354       %a   The above field from the event, formatted as a hexadecimal number.
355            Valid  only  for  Configure  events.  Indicates the sibling window
356            immediately below the receiving window in the stacking order, or 0
357            if the receiving window is at the bottom.
358
359       %b   The number of the button that was pressed or released.  Valid only
360            for ButtonPress and ButtonRelease events.
361
362       %c   The count field from the event.  Valid  only  for  Expose  events.
363            Indicates  that  there  are count pending Expose events which have
364            not yet been delivered to the window.
365
366       %d   The detail or user_data field from the event.  The %d is  replaced
367            by  a  string  identifying the detail.  For Enter, Leave, FocusIn,
368            and FocusOut events, the string will be one of the following:
369
370                   NotifyAncestor          NotifyNonlinearVirtual
371                   NotifyDetailNone        NotifyPointer
372                   NotifyInferior          NotifyPointerRoot
373                   NotifyNonlinear         NotifyVirtual
374
375            For ConfigureRequest events, the string will be one of:
376
377                   Above                   Opposite
378                   Below                   None
379                   BottomIf                TopIf
380
381            For virtual events, the string will be whatever value is stored in
382            the  user_data  field  when  the event was created (typically with
383            event generate), or the empty string if the field is  NULL.   Vir‐
384            tual  events  corresponding to key sequence presses (see event add
385            for details) set the user_data to NULL.   For  events  other  than
386            these, the substituted string is undefined.
387
388       %f   The focus field from the event (0 or 1).  Valid only for Enter and
389            Leave events.  1 if the receiving window is the focus window or  a
390            descendant of the focus window, 0 otherwise.
391
392       %h   The height field from the event.  Valid for the Configure, Config‐
393            ureRequest, Create, ResizeRequest, and Expose  events.   Indicates
394            the new or requested height of the window.
395
396       %i   The  window  field  from  the  event, represented as a hexadecimal
397            integer.  Valid for all event types.
398
399       %k   The keycode field from the event.  Valid  only  for  KeyPress  and
400            KeyRelease events.
401
402       %m   The  mode  field from the event.  The substituted string is one of
403            NotifyNormal,  NotifyGrab,  NotifyUngrab,  or  NotifyWhileGrabbed.
404            Valid only for Enter, FocusIn, FocusOut, and Leave events.
405
406       %o   The  override_redirect  field from the event.  Valid only for Map,
407            Reparent, and Configure events.
408
409       %p   The place field from the event, substituted as one of the  strings
410            PlaceOnTop  or PlaceOnBottom.  Valid only for Circulate and Circu‐
411            lateRequest events.
412
413       %s   The state field from the event.  For  ButtonPress,  ButtonRelease,
414            Enter,  KeyPress,  KeyRelease, Leave, and Motion events, a decimal
415            string is substituted.  For Visibility, one of the  strings  Visi‐
416            bilityUnobscured,  VisibilityPartiallyObscured, and VisibilityFul‐
417            lyObscured is substituted.  For Property events, substituted  with
418            either  the string NewValue (indicating that the property has been
419            created or modified) or Delete (indicating that the  property  has
420            been removed).
421
422       %t   The  time  field  from  the event.  This is the X server timestamp
423            (typically the time since the last server reset) in  milliseconds,
424            when the event occurred.  Valid for most events.
425
426       %w   The  width  field  from the event.  Indicates the new or requested
427            width of the window.  Valid only for Configure,  ConfigureRequest,
428            Create, ResizeRequest, and Expose events.
429
430       %x, %y
431            The  x  and  y  fields from the event.  For ButtonPress, ButtonRe‐
432            lease, Motion, KeyPress, KeyRelease, and MouseWheel events, %x and
433            %y  indicate  the  position  of  the mouse pointer relative to the
434            receiving window.  For Enter and Leave events, the position  where
435            the  mouse  pointer  crossed the window, relative to the receiving
436            window.  For Configure and Create requests, the x  and  y  coordi‐
437            nates of the window relative to its parent window.
438
439       %A   Substitutes  the  UNICODE character corresponding to the event, or
440            the empty string if the event does not  correspond  to  a  UNICODE
441            character  (e.g.  the  shift key was pressed). XmbLookupString (or
442            XLookupString when input method support is turned  off)  does  all
443            the  work  of  translating  from the event to a UNICODE character.
444            Valid only for KeyPress and KeyRelease events.
445
446       %B   The border_width field from the event.  Valid only for  Configure,
447            ConfigureRequest, and Create events.
448
449       %D   This  reports  the  delta  value of a MouseWheel event.  The delta
450            value represents the rotation  units  the  mouse  wheel  has  been
451            moved.  The  sign  of the value represents the direction the mouse
452            wheel was scrolled.
453
454       %E   The send_event field from the event.  Valid for all  event  types.
455            0  indicates that this is a “normal” event, 1 indicates that it is
456            a “synthetic” event generated by SendEvent.
457
458       %K   The keysym corresponding to the event, substituted  as  a  textual
459            string.  Valid only for KeyPress and KeyRelease events.
460
461       %M   The number of script-based binding patterns matched so far for the
462            event.  Valid for all event types.
463
464       %N   The keysym corresponding to the event, substituted  as  a  decimal
465            number.  Valid only for KeyPress and KeyRelease events.
466
467       %P   The  name  of  the property being updated or deleted (which may be
468            converted to an XAtom using winfo atom.) Valid only  for  Property
469            events.
470
471       %R   The  root window identifier from the event.  Valid only for events
472            containing a root field.
473
474       %S   The subwindow window identifier from the  event,  formatted  as  a
475            hexadecimal  number.  Valid only for events containing a subwindow
476            field.
477
478       %T   The type field from the event.  Valid for all event types.
479
480       %W   The path name of the window to which the event was  reported  (the
481            window field from the event).  Valid for all event types.
482
483       %X, %Y
484            The  x_root  and  y_root fields from the event.  If a virtual-root
485            window manager is being used then the substituted values  are  the
486            corresponding  x-coordinate  and y-coordinate in the virtual root.
487            Valid only for ButtonPress, ButtonRelease,  KeyPress,  KeyRelease,
488            and  Motion events.  Same meaning as %x and %y, except relative to
489            the (virtual) root window.
490
491       The replacement string for a %-replacement is formatted as a proper Tcl
492       list  element.   This means that spaces or special characters such as $
493       and { may be preceded by backslashes.  This guarantees that the  string
494       will be passed through the Tcl parser when the binding script is evalu‐
495       ated.  Most replacements are numbers or well-defined  strings  such  as
496       Above;  for these replacements no special formatting is ever necessary.
497       The most common case where reformatting occurs is for the %A  substitu‐
498       tion.  For example, if script is
499              insert %A
500       and  the  character  typed  is  an open square bracket, then the script
501       actually executed will be
502              insert \[
503       This will cause the insert to receive the original  replacement  string
504       (open  square  bracket)  as its first argument.  If the extra backslash
505       had not been added, Tcl would not have been able to  parse  the  script
506       correctly.
507

MULTIPLE MATCHES

509       It  is  possible for several bindings to match a given X event.  If the
510       bindings are associated with different tag's, then each of the bindings
511       will  be executed, in order.  By default, a binding for the widget will
512       be executed first, followed by a  class  binding,  a  binding  for  its
513       toplevel,  and  an  all  binding.   The bindtags command may be used to
514       change this order for a particular window or  to  associate  additional
515       binding tags with the window.
516
517       The  continue and break commands may be used inside a binding script to
518       control the processing of matching scripts.   If  continue  is  invoked
519       within  a binding script, then this binding script, including all other
520       “+” appended scripts, is terminated but  Tk  will  continue  processing
521       binding  scripts  associated with other tag's.  If the break command is
522       invoked within a binding script, then that  script  terminates  and  no
523       other scripts will be invoked for the event.
524
525       Within  a script called from the binding script, return -code ok may be
526       used to continue processing (including “+” appended scripts), or return
527       -code break may be used to stop processing all other binding scripts.
528
529       If  more  than one binding matches a particular event and they have the
530       same tag, then the most specific binding is chosen and  its  script  is
531       evaluated.   The  following  tests  are applied, in order, to determine
532       which of several matching sequences is more specific:
533
534              (a)    an event pattern that specifies a specific button or  key
535                     is more specific than one that does not;
536
537              (b)    a  longer sequence (in terms of number of events matched)
538                     is more specific than a shorter sequence;
539
540              (c)    if the modifiers specified in one pattern are a subset of
541                     the  modifiers  in another pattern, then the pattern with
542                     more modifiers is more specific.
543
544              (d)    a  virtual  event  whose  physical  pattern  matches  the
545                     sequence  is less specific than the same physical pattern
546                     that is not associated with a virtual event.
547
548              (e)    given a sequence that matches two or more virtual events,
549                     one  of  the virtual events will be chosen, but the order
550                     is undefined.
551
552       If the matching sequences contain  more  than  one  event,  then  tests
553       (c)-(e)  are  applied  in order from the most recent event to the least
554       recent event in the sequences.  If these tests fail to determine a win‐
555       ner, then the most recently registered sequence is the winner.
556
557       If  there  are  two (or more) virtual events that are both triggered by
558       the same sequence, and both of those virtual events are  bound  to  the
559       same window tag, then only one of the virtual events will be triggered,
560       and it will be picked at random:
561              event add <<Paste>> <Control-y>
562              event add <<Paste>> <Button-2>
563              event add <<Scroll>> <Button-2>
564              bind Entry <<Paste>> {puts Paste}
565              bind Entry <<Scroll>> {puts Scroll}
566       If the user types Control-y, the <<Paste>> binding will be invoked, but
567       if  the  user  presses button 2 then one of either the <<Paste>> or the
568       <<Scroll>> bindings will be invoked, but exactly which one gets invoked
569       is undefined.
570
571       If  an  X  event  does not match any of the existing bindings, then the
572       event is ignored.  An unbound event is not considered to be an error.
573

MULTI-EVENT SEQUENCES AND IGNORED EVENTS

575       When a sequence specified in a bind  command  contains  more  than  one
576       event  pattern,  then its script is executed whenever the recent events
577       (leading up to  and  including  the  current  event)  match  the  given
578       sequence.  This means, for example, that if button 1 is clicked repeat‐
579       edly the sequence <Double-ButtonPress-1> will match each  button  press
580       but  the  first.  If extraneous events that would prevent a match occur
581       in the middle of an event  sequence  then  the  extraneous  events  are
582       ignored  unless  they are KeyPress or ButtonPress events.  For example,
583       <Double-ButtonPress-1> will match a sequence of presses  of  button  1,
584       even  though  there  will  be ButtonRelease events (and possibly Motion
585       events) between the ButtonPress events.  Furthermore, a KeyPress  event
586       may  be  preceded  by  any number of other KeyPress events for modifier
587       keys without the modifier keys preventing a match.   For  example,  the
588       event  sequence  aB will match a press of the a key, a release of the a
589       key, a press of the Shift key, and a press of the b key:  the press  of
590       Shift  is  ignored  because  it is a modifier key.  Finally, if several
591       Motion events occur in a row, only the last one is used for purposes of
592       matching binding sequences.
593

ERRORS

595       If an error occurs in executing the script for a binding then the bger‐
596       ror mechanism is used to report the error.  The bgerror command will be
597       executed at global level (outside the context of any Tcl procedure).
598

EXAMPLES

600       Arrange  for  a string describing the motion of the mouse to be printed
601       out when the mouse is double-clicked:
602              bind . <Double-1> {
603                  puts "hi from (%x,%y)"
604              }
605
606       A little GUI that displays what the keysym name of the last key pressed
607       is:
608              set keysym "Press any key"
609              pack [label .l -textvariable keysym -padx 2m -pady 1m]
610              bind . <Key> {
611                  set keysym "You pressed %K"
612              }
613

SEE ALSO

615       bgerror(n), bindtags(n), event(n), focus(n), grab(n), keysyms(n)
616

KEYWORDS

618       binding, event
619
620
621
622Tk                                    8.0                              bind(n)
Impressum