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
       window(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
       bindtags 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
       patterns, with optional white space between the patterns.  Each event
       pattern 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 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 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 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 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
       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-Button-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 modifiers 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 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
       Double 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.


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
       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 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
       specified 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 necessary, 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
       parameters. 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.

       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
            VisibilityUnobscured, VisibilityPartiallyObscured, and
            VisibilityFullyObscured 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.

       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,
            ButtonRelease, 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,
            ButtonRelease, 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
       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
       pattern, then the pattern with more modifiers is more specific.  (d) a
       virtual 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 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
       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>>"  (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
       undefined.

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



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
       repeatedly 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
       bgerror mechanism is used to report the error.


SEE ALSO
       bindtags, tkerror



STk                                   3.2                              bind(n)
