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 following
event.
If there is no following event, this represents 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 following
event
with the Control key pressed. The character 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 button pressed, the
Button event is delivered in combination 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 outside.
- 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.
- Destroy
- The event of the widget being destroyed.
See
destroy(9)
for details of widget destruction.
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).
- 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
generated 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 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 undefined.
- %% 5
- Replaced with a single percent.
- %b 5
- The number of the button that was pressed or released. Valid only
for ButtonPress and ButtonRelease events.
- %h 5
- For
Configure
events, this is
the old requested height of the widget.
- %s 5
- 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 5
- For
Configure
events, this is the old requested width of the widget.
- %x 5
- The x coordinate from the event, relative to the origin
of the toplevel window. Valid only for
Enter,
Leave,
and mouse events.
- %y 5
- The y coordinate from the event, relative to the origin
of the toplevel window. Valid only for
Enter,
Leave,
and mouse events.
- %A 5
- The ASCII character corresponding to a Key event.
- %K 5
- The pressed character for the event, as four hexadecimal digits.
Valid only for Key events.
- %W 5
- The path name of the window to which the event was reported (the
window field from the event). Valid for all event types.
- %X 5
- Same as
%x
except that the screen coordinate system is used.
- %Y 5
- 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 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 Tk
parser when the binding script is evaluated.