BIND(9)                                                   BIND(9)

     NAME
          bind - Arrange for events to invoke Tk scripts

     SYNOPSIS
          bind tag sequence script

          bind tag sequence +script

     INTRODUCTION
          The bind command associates Tk scripts with window events.
          If all three arguments are specified, bind will arrange for
          script (a Tk script) to be evaluated whenever the event(s)
          given by sequence occur in the window(s) identified by tag.
          If script is prefixed with a ``+'', then it is appended to
          any existing binding for sequence;  otherwise 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
          script is prefixed with a ``-'', then any existing binding
          for sequence, whose script is exactly the same as script, is
          removed.  The tag argument gives the pathname of the window
          to which sequence is bound.

     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 two 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:
               <event-event-...-event>
          The following events are accepted:

          Key or Keypress
               This represents the press of the character in the fol-
               lowing event. If there is no following event, this rep-
               resents the press of any key. The key letter may be
               escaped with a backslash (\) to prevent any character
               (e.g.  >) from being treated specially.

          Configure
               This event occurs whenever the widget is configured
               such that its requested size changes.

          Control
               This represents the press of the character in the

     BIND(9)                                                   BIND(9)

               following event with the Control key pressed. The char-
               acter may be quoted as for Key.

          ButtonPress or Button
               This represents the pressed state of the mouse button
               given by the following event, which should be 1, 2, or
               3. If there is no following event, this represents the
               press of any button.  If the mouse is moved with a but-
               ton pressed, the Button event is delivered in combina-
               tion with a Motion event so long as the button remains
               pressed.

          ButtonRelease
               Like ButtonPress, but represents the release of any
               button.

          Motion
               Mouse movement.

          Double
               Any events in the sequence representing button presses
               must be double-clicked for the sequence to match.

          Map  The event that a toplevel widget is mapped onto the
               screen.

          Unmap
               The event that a toplevel widget is unmapped from the
               screen.

          Enter
               The event of the mouse entering the widget from out-
               side.

          Leave
               The event of the mouse leaving the boundaries of the
               widget.

          FocusIn
               The event of the widget getting the keyboard focus.

          FocusOut
               The event of the widget losing the keyboard focus.
          The event sequence can contain any combination of the above
          events. They are treated independently, and if any of the
          events occur, the sequence matches. You cannot combine key
          presses of more than one key. Events will not be combined on
          delivery, except that Motion events may be combined with
          button presses (possibly doubled).

          Destroy
          The event of the widget being destroyed.  See destroy(9) for

     BIND(9)                                                   BIND(9)

          details of widget destruction.

     BINDING SCRIPTS AND SUBSTITUTIONS
          The script argument to bind is a Tk script, which will be
          executed whenever the given event sequence occurs.  If
          script contains any % characters, then the script will not
          be executed directly.  Instead, a new script will be gener-
          ated by replacing each %, and the character following it,
          with information from the current event.  The replacement
          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 cur-
          rent 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 undefined.

          %%   Replaced with a single percent.

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

          %h   For Configure events, this is the old requested height
               of the widget.

          %s   For mouse events, this is the logical OR of the mouse
               buttons; for keyboard events, it is the decimal value
               of the pressed character.

          %w   For Configure events, this is the old requested width
               of the widget.

          %x   The x coordinate from the event, relative to the origin
               of the toplevel window. Valid only for Enter, Leave,
               and mouse events.

          %y   The y coordinate from the event, relative to the origin
               of the toplevel window. Valid only for Enter, Leave,
               and mouse events.

          %A   The ASCII character corresponding to a Key event.

          %K   The pressed character for the event, as four hexadeci-
               mal digits.  Valid only for Key events.

          %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   Same as %x except that the screen coordinate system is
               used.

     BIND(9)                                                   BIND(9)

          %Y   Same as %y except that the screen coordinate system is
               used.

          The replacement string for a %-replacement is formatted as a
          proper Tk list element.  This means that it will be sur-
          rounded with braces if it contains spaces, or special char-
          acters such as $ and { may be preceded by backslashes.  This
          guarantees that the string will be passed through the Tk
          parser when the binding script is evaluated.

     BUGS
          The above scheme is not ideal, and will probably be fixed in
          the future.  Quoting is a mess - in particular, the quoting
          provided for the %A substitution does not work correctly
          when a quoted character is re-interpreted by Tk.

          The length of binding scripts is limited to 128 characters.