


bind(n)                Tk Built-In Commands               bind(n)


NAME
       bind - Arrange for X events to invoke STk scripts

SYNOPSIS
       (bind tag)

       (bind tag sequence)

       (bind tag sequence script)


INTRODUCTION
       The  bind procedure associates STk scripts with X events.  If all three
       arguments are specified, bind will arrange for script (a STk script) to
       be  evaluated whenever the event(s) given by sequence occur in the win-
       dow(s) identified by tag.  If is specified for  a  given  sequence,  it
       replaces  the  previous 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 list.

       If sequence is specified without a script, then  the  script  currently
       bound to sequence is returned, or an empty list 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 bind-
       tags  procedure  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  as  Button,
              the binding applies to all widgets in 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  pat-
       terns, with optional white space between the patterns.  Each event pat-
       tern may take one of three forms.  In the simplest case it is a  single
       printing  ASCII  character, such as a or [.  The character may not be a
       space character or the character <.  This form  of  pattern  matches  a



STk                            3.2                              1





bind(n)                Tk Built-In Commands               bind(n)


       KeyPress  event  for the particular character.  The second form of pat-
       tern is longer but more general.  It has the following  syntax:  <modi-
       fier-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 sep-
       arated by white space or dashes.

       The third form of pattern is used to specify a user-defined, named vir-
       tual  event.   It has the following syntax: <<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 vir-
       tual event is defined, and if the definition of a virtual event changes
       dynamically, all windows bound to that virtual event will respond imme-
       diately to the new definition.

MODIFIERS
       Modifiers   consist   of   any   of   the   following   values:    Con-
       trol                   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  Where
       more  than  one  value  is  listed, separated by commas, the values are
       equivalent.  Most of the modifiers have the obvious  X  meanings.   For
       example,  Button1  requires  that  button 1 be depressed when the event
       occurs.  For a binding 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 specified in the  bind-
       ing.   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-Button-1> will not.  If no modifiers are specified, then any com-
       bination of modifiers may be present in the event.

       Meta and M refer to whichever of the M1 through M5 modifiers is associ-
       ated  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 modi-
       fiers,  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 and Triple modifiers are a convenience for specifying double
       mouse clicks and other repeated events. They cause a  particular  event
       pattern  to  be  repeated 2 or 3 times, and also place a time and space
       requirement on the sequence:  for a sequence of events to match a  Dou-
       ble  or  Triple pattern, all of the events must occur close together in
       time and without substantial mouse motion  in  between.   For  example,
       <Double-Button-1>  is equivalent to <Button-1><Button-1> with the extra
       time and space requirement.






STk                            3.2                              2





bind(n)                Tk Built-In Commands               bind(n)


EVENT TYPES
       The type field may be any of the standard X event  types,  with  a  few
       extra  abbreviations.   Below  is a list of all the val%id types; where
       two  names  appear   together,   they   are   synonyms.    ButtonPress,
       Button Expose             Map
       ButtonRelease       FocusIn            Motion
       Circulate           FocusOut           Property
       Colormap            Gravity            Reparent
       Configure           KeyPress,                           Key       Unmap
       Destroy             KeyRelease         Visibility
       Enter               Leave              Activate Deactivate

       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 partic-
       ular button will match;  if no button number is given, then an event on
       any  button will match.  Note:  giving a specific button number is dif-
       ferent 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 button 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>.

       If  the event type is KeyPress or KeyRelease, then detail may be speci-
       fied in the form of an X keysym.  Keysyms  are  textual  specifications
       for  particular keys on the keyboard; 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  neces-
       sary,  you  can  use the |K| closure parameter 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 KeyPress.  For
       example, <Control-comma> is equivalent to <Control-KeyPress-comma>.


BINDING SCRIPTS AND SUBSTITUTIONS
       The script argument to bind must be a closure, which will  be  executed
       whenever  the given event sequence occurs. The closure can have parame-
       ters. Those parameters are one character symbols (with convention which
       are  described below). Parameter list will be evaluated just before the
       script is fired. Note that some parameters are only valid  for  certain
       types  of  events; if they are used for other types of events the value
       substituted is undefined.


       %    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.



STk                            3.2                              3





bind(n)                Tk Built-In Commands               bind(n)


       a    The above field from the event, formatted as a hexadecimal number.
            Valid only for Configure events.

       b    The number of the button that was pressed or released.  Valid only
            for ButtonPress and ButtonRelease events.

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

       d    The  detail  field  from the event.  The d is replaced 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 (#f or #t).  Valid only for Enter
            and Leave events.

       h    The height field from the event.  Valid  only  for  Configure  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,  NotifyUngrab,  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  Visi-
            bilityUnobscured,  VisibilityPartiallyObscured, and VisibilityFul-
            lyObscured 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 Configure 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.




STk                            3.2                              4





bind(n)                Tk Built-In Commands               bind(n)


       A    Substitutes the ASCII character corresponding to the event, or the
            empty string if the event doesn't correspond to an ASCII character
            (e.g. the shift key was pressed).  XLookupString does all the work
            of  translating  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.

       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 KeyRelease events.

       N    The keysym corresponding to the event, substituted  as  a  decimal
            number.  Valid only for KeyPress and KeyRelease 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,  formatted  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 virtual root.  Valid only for ButtonPress, But-
            tonRelease, 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 virtual root.  Valid only for ButtonPress,  But-
            tonRelease, KeyPress, KeyRelease, and Motion events.


       The following example show how to display a message each time the l1 or
       l2 label is entered: (pack (label '.l1 :text "One")) (pack (label  '.l2
       :text "Two")) (let ((mess (lambda (|W| x y)
                     (format #t "Entering ~S x=~a y=~a0 |W| x y))))
         (bind .l1 "<Enter>" mess)
         (bind  .l2  "<Enter>" mess)) Note the usage of the "|" convention for
       the symbol parameters which must be in left in upper-case.


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  executed  first,  followed  by  a  class binding, a binding for its



STk                            3.2                              5





bind(n)                Tk Built-In Commands               bind(n)


       toplevel, and an all binding.  The bindtags procedure may  be  used  to
       change  this  order  for a particular window or to associate additional
       binding tags with the window.

       If the binding procedure result is the  symbol  break,  then  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)  a  longer
       sequence (in terms of number of events matched) is more specific than a
       shorter sequence; (b) an event pattern that specifies a specific button
       or  key  is  more  specific than one that doesn't; (c) if the modifiers
       specified in one pattern are a subset of the modifiers in another  pat-
       tern,  then  the  pattern  with more modifiers is more specific.  (d) a
       virtual event whose physical pattern matches the sequence is less  spe-
       cific than the same physical pattern that is not associated with a vir-
       tual event.  (e) given a sequence that  matches  two  or  more  virtual
       events,  one  of  the  virtual  events will be chosen, but the order is
       undefined.

       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 win-
       ner, 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>>"  (lambda () (display "Paste0)))
       (bind  "Entry" "<<Scroll>>" (lambda () (display "Scroll0))) 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  unde-
       fined.

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


       The following example illustrates how to use the break symbol to  break
       a  binding  chain.   (pack  (entry  '.e)) (bind .e "<KeyPress>" (lambda
       (|A|)
                               (unless (string->number |A|) 'break))) Bindings
       for  the entry .e are executed before those for its class (i.e. Entry).
       This allows us to filter the characters which are effectively passed to
       the  .e  widget.  The  test in this binding closure breaks the chain of
       bindings if the typed character is not a digit. Otherwise, the  follow-
       ing  binding,  the one for the Entry class, is executed and inserts the
       character typed (a digit).  Consequently, the simple  previous  binding
       makes .e a controlled entry which only accepts integer numbers.



STk                            3.2                              6





bind(n)                Tk Built-In Commands               bind(n)


MULTI-EVENT SEQUENCES AND IGNORED EVENTS
       When  a  sequence  specified in a bind procedure contains more than one
       event pattern, then its script is executed whenever 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 repeat-
       edly  the  sequence <Double-ButtonPress-1> will match each button press
       but the first.  If extraneous events that would prevent 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-ButtonPress-1>  will  match  a sequence of presses of button 1,
       even though there will be ButtonRelease  events  (and  possibly  Motion
       events)  between the ButtonPress events.  Furthermore, 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 modifier  key.   Finally,  if  several
       Motion events occur in a row, only the last one is used for purposes of
       matching binding sequences.


ERRORS
       If an error occurs in executing the script for a binding then the bger-
       ror mechanism is used to report the error.


SEE ALSO
       bindtags, tkerror





























STk                            3.2                              7


