BIND(9)BIND(9)NAMEbind - Arrange for events to invoke Tk scripts
SYNOPSISbind tag sequence script
bind tag sequence +script
DESCRIPTION
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; oth‐
erwise 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 pro‐
vided, 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 pat‐
terns, with optional white space between the patterns. Each event pat‐
tern 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 pat‐
tern 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 spe‐
cially.
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 but‐
ton 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 aretreated 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 com‐
bined 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.
%% 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 wid‐
get.
%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 wid‐
get.
%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 hexadecimal 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.
%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 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.
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.
BIND(9)