NAME

       bind - Arrange for X events to invoke Tcl scripts


SYNOPSIS

       bind tag

       bind tag sequence

       bind tag sequence script

       bind tag sequence +script
_________________________________________________________________


INTRODUCTION

       The bind command associates Tcl scripts with X events.  If
       all three arguments are specified, bind will  arrange  for
       script  (a  Tcl  script)  to  be  evaluated  whenever  the
       event(s) given by sequence occur in the window(s)  identi­
       fied  by tag.  If script is prefixed with a ``+'', then it
       is appended to any existing binding for sequence;   other­
       wise  script  replaces any existing binding.  If script is
       an empty string then the current binding for  sequence  is
       destroyed,  leaving sequence unbound.  In all of the cases
       where a script argument is provided, bind returns an empty
       string.

       If sequence is specified without a script, then the script
       currently bound to  sequence  is  returned,  or  an  empty
       string  is  returned  if there is no binding for sequence.
       If neither sequence nor  script  is  specified,  then  the
       return  value  is  a  list  whose  elements  are  all  the
       sequences for which there exist bindings for tag.

       The tag argument determines which  window(s)  the  binding
       applies  to.  If tag begins with a dot, as in .a.b.c, then
       it must be the path name for a window; otherwise it may be
       an  arbitrary  string.  Each window has an associated list
       of tags, and a binding applies to a particular  window  if
       its tag is among those specified for the window.  Although
       the bindtags command may be used to  assign  an  arbitrary
       set  of binding tags to a window, the default binding tags
       provide the following behavior:

              If a tag is the name  of  an  internal  window  the
              binding applies to that window.

              If  the  tag  is  the name of a toplevel window the
              binding applies to the toplevel window and all  its
              internal windows.

              If  the tag is the name of a class of widgets, such

              that class;

              If  tag  has  the value all, the binding applies to
              all windows in the application.


EVENT PATTERNS

       The sequence argument specifies a sequence of one or  more
       event patterns, with optional white space between the pat­
       terns.  Each event pattern may take one  of  three  forms. |
       In the simplest case it is a single printing ASCII charac­
       ter, such as a or [.  The character may  not  be  a  space
       character  or  the  character  <.   This  form  of pattern
       matches a KeyPress event  for  the  particular  character.
       The second form of pattern is longer but more general.  It
       has the following syntax:
              <modifier-modifier-type-detail>
       The entire event pattern is surrounded by angle  brackets.
       Inside  the  angle brackets are zero or more modifiers, an
       event type, and an extra  piece  of  information  (detail)
       identifying  a  particular  button  or keysym.  Any of the
       fields may be omitted, as long as at least one of type and
       detail  is present.  The fields must be separated by white
       space or dashes.                                           |

       The third form of pattern  is  used  to  specify  a  user- |
       defined,  named  virtual event.  It has the following syn­ |
       tax:                                                       |
              <<name>>                                            |
       The entire virtual event pattern is surrounded  by  double |
       angle  brackets.   Inside  the angle brackets is the user- |
       defined name of the virtual  event.   Modifiers,  such  as |
       Shift or Control, may not be combined with a virtual event |
       to modify it.  Bindings on a virtual event may be  created |
       before the virtual event is defined, and if the definition |
       of a virtual event changes dynamically, all windows  bound |
       to  that virtual event will respond immediately to the new |
       definition.


MODIFIERS

       Modifiers consist of any of the following values:

              Control                 Mod2, M2
              Shift                   Mod3, M3
              Lock                    Mod4, M4
              Button1, B1             Mod5, M5
              Button2, B2             Meta, M
              Button3, B3             Alt
              Button4, B4             Double
              Button5, B5             Triple
              Mod1, M1                Quadruple

       Where more than one value is listed, separated by  commas,

       obvious X meanings.  For example,  Button1  requires  that
       button  1 be depressed when the event occurs.  For a bind­
       ing to match a given event, the  modifiers  in  the  event
       must  include all of those specified in the event pattern.
       An event may also contain additional modifiers not  speci­
       fied  in the binding.  For example, if button 1 is pressed
       while the shift and control keys  are  down,  the  pattern
       <Control-Button-1>  will  match  the event, but <Mod1-But­
       ton-1> will not.  If no modifiers are specified, then  any
       combination of modifiers may be present in the event.

       Meta  and  M refer to whichever of the M1 through M5 modi­
       fiers is associated with the meta key(s) on  the  keyboard
       (keysyms  Meta_R  and Meta_L).  If there are no meta keys,
       or if they are not associated  with  any  modifiers,  then
       Meta  and M will not match any events.  Similarly, the Alt
       modifier refers to whichever modifier is  associated  with
       the  alt key(s) on the keyboard (keysyms Alt_L and Alt_R).

       The Double, Triple and Quadruple modifiers  are  a  conve­
       nience  for  specifying  double  mouse  clicks  and  other
       repeated events. They cause a particular event pattern  to
       be  repeated  2,  3  or 4 times, and also place a time and
       space requirement on  the  sequence:  for  a  sequence  of
       events to match a Double, Triple or Quadruple pattern, all
       of the events must occur close together in time and  with­
       out  substantial  mouse  motion  in between.  For example,
       <Double-Button-1> is  equivalent  to  <Button-1><Button-1>
       with the extra time and space requirement.


EVENT TYPES

       The  type  field may be any of the standard X event types,
       with a few extra abbreviations.  The type field will  also
       accept a couple non-standard X event types that were added
       to better support the  Macintosh  and  Windows  platforms.
       Below  is  a  list of all the valid types; where two names
       appear together, they are synonyms.

              Activate            Enter              Map
              ButtonPress, Button Expose             Motion
              ButtonRelease       FocusIn            MouseWheel   |
              Circulate           FocusOut           Property
              Colormap            Gravity            Reparent
              Configure           KeyPress, Key      Unmap
              Deactivate          KeyRelease         Visibility
              Destroy             Leave

       Most of the above events have the same fields  and  behav­ |
       iors  as  events  in the X Windowing system.  You can find |
       more detailed descriptions of these events in any X window |
       programming  book.   A couple of the events are extensions |

       Macintosh and Windows platforms.  We provide a little more |
       detail on these events here.  These include:               |

       Activate                                                          ||

       Deactivate                                                        ||
            These two events are sent to every  sub-window  of  a |
            toplevel  when they change state.  In addition to the |
            focus Window,  the  Macintosh  platform  and  Windows |
            platforms  have  a  notion of an active window (which |
            often has but is not required to have the focus).  On |
            the  Macintosh,  widgets  in the active window have a |
            different appearance than widgets  in  deactive  win­ |
            dows.  The Activate event is sent to all the sub-win­ |
            dows in a toplevel when it changes from  being  deac­ |
            tive to active.  Likewise, the Deactive event is sent |
            when the window's state changes from active to  deac­ |
            tive.   There are no useful percent substitutions you |
            would make when binding to these events.              |

       MouseWheel                                                        ||
            Some  mice  on  the  Windows platform support a mouse |
            wheel which is used for scrolling  documents  without |
            using the scrollbars.  By rolling the wheel, the sys­ |
            tem will generate MouseWheel events that the applica­ |
            tion can use to scroll.  Like Key events the event is |
            always routed to the window that currently has focus. |
            When the event is received you can use the %D substi­ |
            tution to get the delta field for the event which  is |
            a  integer  value  of motion that the mouse wheel has |
            moved.  The smallest value for which the system  will |
            report  is  defined  by  the  OS.  On Windows 95 & 98 |
            machines this value is at  least  120  before  it  is |
            reported.   However, higher resolution devices may be |
            available in the  future.   The  sign  of  the  value |
            determines which direction your widget should scroll. |
            Positive values should scroll up and negative  values |
            should scroll down.

       The last part of a long event specification is detail.  In
       the case of a ButtonPress or ButtonRelease  event,  it  is
       the  number  of  a  button  (1-5).   If a button number is
       given, then only an event on that particular  button  will
       match;  if no button number is given, then an event on any
       button will match.  Note:  giving a specific button number
       is  different  than  specifying  a button modifier; in the
       first case,  it  refers  to  a  button  being  pressed  or
       released, while in the second it refers to some other but­
       ton that is already  depressed  when  the  matching  event
       occurs.   If  a  button  number  is given then type may be
       omitted:  if will default to  ButtonPress.   For  example,
       the specifier <1> is equivalent to <ButtonPress-1>.

       may be specified in the form of an X keysym.  Keysyms  are
       textual  specifications  for  particular  keys on the key­
       board; they include all the alphanumeric ASCII  characters
       (e.g.  ``a'' is the keysym for the ASCII character ``a''),
       plus   descriptions   for   non-alphanumeric    characters
       (``comma''  is  the  keysym for the comma character), plus
       descriptions for all the non-ASCII keys  on  the  keyboard
       (``Shift_L''  is  the  keysm  for  the left shift key, and
       ``F1'' is the keysym  for  the  F1  function  key,  if  it
       exists).   The  complete  list of keysyms is not presented
       here;  it is available in other X  documentation  and  may
       vary from system to system.  If necessary, you can use the
       %K notation described below to print out the  keysym  name
       for  a  particular key.  If a keysym detail is given, then
       the type field may be omitted;  it will  default  to  Key­
       Press.   For  example,  <Control-comma>  is  equivalent to
       <Control-KeyPress-comma>.


BINDING SCRIPTS AND SUBSTITUTIONS

       The script argument to bind is a Tcl script, which will be
       executed  whenever  the given event sequence occurs.  Com­
       mand will be executed in the  same  interpreter  that  the
       bind  command  was  executed in, and it will run at global
       level (only global  variables  will  be  accessible).   If
       script contains any % characters, then the script will not
       be executed directly.  Instead, a new script will be  gen­
       erated  by  replacing  each %, and the character following
       it, with information from the current event.  The replace­
       ment  depends on the character following the %, as defined
       in  the  list  below.   Unless  otherwise  indicated,  the
       replacement string is the decimal value of the given field
       from the current event.  Some  of  the  substitutions  are
       only  valid for certain types of events;  if they are used
       for other types of events the value substituted  is  unde­
       fined.

       %%   Replaced with a single percent.

       %#   The  number  of  the last client request processed by
            the server (the serial field from the event).   Valid
            for all event types.

       %a   The  above  field from the event, formatted as a hex­
            adecimal number.  Valid only for Configure events.

       %b   The  number  of  the  button  that  was  pressed   or
            released.   Valid  only for ButtonPress and ButtonRe­
            lease events.

       %c   The count field  from  the  event.   Valid  only  for
            Expose events.

            by a  string  identifying  the  detail.   For  Enter,
            Leave,  FocusIn, and FocusOut events, the string will
            be one of the following:

                   NotifyAncestor          NotifyNonlinearVirtual
                   NotifyDetailNone        NotifyPointer
                   NotifyInferior          NotifyPointerRoot
                   NotifyNonlinear         NotifyVirtual

            For events other than these, the  substituted  string
            is undefined.

       %f   The  focus field from the event (0 or 1).  Valid only
            for Enter and Leave events.

       %h   The height field from the event.  Valid for the  Con­ |
            figure and Expose events.

       %k   The  keycode  field  from  the event.  Valid only for
            KeyPress and KeyRelease events.

       %m   The mode  field  from  the  event.   The  substituted
            string  is one of NotifyNormal, NotifyGrab, NotifyUn­
            grab, or NotifyWhileGrabbed.  Valid only  for  Enter, |
            FocusIn, FocusOut, and Leave events.

       %o   The  override_redirect  field  from the event.  Valid
            only for Map, Reparent, and Configure events.

       %p   The place field from the event, substituted as one of
            the  strings PlaceOnTop or PlaceOnBottom.  Valid only
            for Circulate events.

       %s   The state field from  the  event.   For  ButtonPress,
            ButtonRelease,  Enter,  KeyPress,  KeyRelease, Leave,
            and Motion events, a decimal string  is  substituted.
            For  Visibility,  one  of the strings VisibilityUnob­
            scured, VisibilityPartiallyObscured, and  Visibility­
            FullyObscured is substituted.

       %t   The time field from the event.  Valid only for events
            that contain a time field.

       %w   The width field from the event.  Valid only for  Con­ |
            figure and Expose events.

       %x   The  x  field  from the event.  Valid only for events
            containing an x field.

       %y   The y field from the event.  Valid  only  for  events
            containing a y field.

       %A   Substitutes  the ASCII character corresponding to the

            respond to an ASCII character (e.g. the shift key was
            pressed).  XLookupString does all the work of  trans­
            lating  from  the event to an ASCII character.  Valid
            only for KeyPress and KeyRelease events.

       %B   The border_width field from the  event.   Valid  only
            for Configure events.                                 |

       %D                                                                ||
            This reports the delta value of a  MouseWheel  event. |
            The  delta  value  represents  the rotation units the |
            mouse wheel has been moved.  On Windows 95 & 98  sys­ |
            tems the smallest value for the delta is 120.  Future |
            systems may support higher resolution values for  the |
            delta.   The  sign of the value represents the direc­ |
            tion the mouse wheel was scrolled.

       %E   The send_event field from the event.  Valid  for  all
            event types.

       %K   The keysym corresponding to the event, substituted as
            a textual string.  Valid only for KeyPress and KeyRe­
            lease events.

       %N   The keysym corresponding to the event, substituted as
            a decimal number.  Valid only for KeyPress and KeyRe­
            lease events.

       %R   The  root  window  identifier  from the event.  Valid
            only for events containing a root field.

       %S   The subwindow window identifier from the event,  for­
            matted  as  a  hexadecimal  number.   Valid  only for
            events containing a subwindow field.

       %T   The type field from the event.  Valid for  all  event
            types.

       %W   The  path  name  of the window to which the event was
            reported (the window field from  the  event).   Valid
            for all event types.

       %X   The  x_root  field from the event.  If a virtual-root
            window manager is being  used  then  the  substituted
            value  is  the corresponding x-coordinate in the vir­
            tual root.  Valid  only  for  ButtonPress,  ButtonRe­
            lease, KeyPress, KeyRelease, and Motion events.

       %Y   The  y_root  field from the event.  If a virtual-root
            window manager is being  used  then  the  substituted
            value  is  the corresponding y-coordinate in the vir­
            tual root.  Valid  only  for  ButtonPress,  ButtonRe­
            lease, KeyPress, KeyRelease, and Motion events.

       a proper Tcl list element.  This means  that  it  will  be
       surrounded  with  braces if it contains spaces, or special
       characters such as $ and { may be preceded by backslashes.
       This guarantees that the string will be passed through the
       Tcl parser when the binding  script  is  evaluated.   Most
       replacements  are  numbers or well-defined strings such as
       Above;  for these replacements no  special  formatting  is
       ever  necessary.   The most common case where reformatting
       occurs is for the %A substitution.  For example, if script
       is
              insert %A
       and  the  character  typed is an open square bracket, then
       the script actually executed will be
              insert \[
       This  will  cause  the  insert  to  receive  the  original
       replacement  string  (open  square  bracket)  as its first
       argument.  If the extra backslash hadn't been  added,  Tcl
       would not have been able to parse the script correctly.


MULTIPLE MATCHES

       It  is  possible  for  several bindings to match a given X
       event.  If the  bindings  are  associated  with  different
       tag's,  then  each  of  the  bindings will be executed, in
       order.  By default, a binding for the widget will be  exe­
       cuted  first,  followed  by a class binding, a binding for
       its toplevel, and an all binding.   The  bindtags  command
       may  be  used to change this order for a particular window
       or to associate additional binding tags with the window.

       The continue and break commands may be used inside a bind­
       ing  script to control the processing of matching scripts.
       If continue is invoked, then the current binding script is
       terminated but Tk will continue processing binding scripts
       associated with other tag's.   If  the  break  command  is
       invoked  within  a binding script, then that script termi­
       nates and no other scripts will be invoked for the  event. |

       If  more  than  one binding matches a particular event and |
       they have the same tag, then the most specific binding  is |
       chosen  and  its script is evaluated.  The following tests |
       are applied, in  order,  to  determine  which  of  several |
       matching  sequences is more specific: (a) an event pattern |
       that specifies a specific button or key is  more  specific |
       than  one that doesn't; (b) a longer sequence (in terms of |
       number of events matched) is more specific than a  shorter |
       sequence;  (c)  if  the modifiers specified in one pattern |
       are a subset of the modifiers in another pattern, then the |
       pattern  with more modifiers is more specific.  (d) a vir­ |
       tual event whose physical pattern matches the sequence  is |
       less  specific  than the same physical pattern that is not |
       associated with a virtual event.   (e)  given  a  sequence |
       that  matches  two  or  more  virtual  events,  one of the |


       If  the  matching  sequences  contain more than one event, |
       then tests (c)-(e) are applied  in  order  from  the  most |
       recent  event  to the least recent event in the sequences. |
       If these tests fail to determine a winner, then  the  most |
       recently registered sequence is the winner.                |

       If  there  are  two (or more) virtual events that are both |
       triggered by the same sequence, and both of those  virtual |
       events  are bound to the same window tag, then only one of |
       the virtual events will  be  triggered,  and  it  will  be |
       picked at random:                                          |
              event add <<Paste>> <Control-y>                     |
              event add <<Paste>> <Button-2>                      |
              event add <<Scroll>> <Button-2>                     |
              bind Entry <<Paste>> {puts Paste}                   |
              bind Entry <<Scroll>> {puts Scroll}                 |
       If the user types Control-y, the <<Paste>> binding will be |
       invoked, but if the user presses  button  2  then  one  of |
       either  the  <<Paste>>  or the <<Scroll>> bindings will be |
       invoked, but exactly which one gets invoked is  undefined.

       If an X event does not match any of the existing bindings,
       then the event is ignored.  An unbound event is  not  con­
       sidered to be an error.


MULTI-EVENT SEQUENCES AND IGNORED EVENTS

       When  a sequence specified in a bind command contains more
       than one event pattern, then its script is executed  when­
       ever  the  recent  events (leading up to and including the
       current event) match the given sequence.  This means,  for
       example,  that  if  button  1  is  clicked  repeatedly the
       sequence <Double-ButtonPress-1>  will  match  each  button
       press but the first.  If extraneous events that would pre­
       vent a match occur in the middle of an event sequence then
       the extraneous events are ignored unless they are KeyPress
       or  ButtonPress  events.   For  example,   <Double-Button­
       Press-1>  will  match  a  sequence of presses of button 1,
       even though there will be ButtonRelease events (and possi­
       bly  Motion  events) between the ButtonPress events.  Fur­
       thermore, a KeyPress event may be preceded by  any  number
       of  other  KeyPress  events  for modifier keys without the
       modifier keys preventing a match.  For example, the  event
       sequence  aB will match a press of the a key, a release of
       the a key, a press of the Shift key, and a press of the  b
       key:   the press of Shift is ignored because it is a modi­
       fier key.  Finally, if several Motion events  occur  in  a
       row,  only  the  last one is used for purposes of matching
       binding sequences.

       If an error occurs in executing the script for  a  binding
       then  the  bgerror  mechanism is used to report the error.
       The bgerror command will be executed at global level (out­
       side the context of any Tcl procedure).


SEE ALSO

       bgerror, keysyms


KEYWORDS

       form, manual


Man(1) output converted with man2html