ref: 5edeca01b0622463a65c126ebcc29314013fd928
dir: /man/9/bind/
.TH BIND 9
.SH NAME
bind \- Arrange for events to invoke Tk scripts
.SH SYNOPSIS
\f5bind\fI tag sequence script\fR
.sp
\f5bind\fI tag sequence \f5+\fIscript\fR
.SH DESCRIPTION
The \f5bind\fR command associates Tk scripts with window events.
If all three arguments are specified, \f5bind\fR will
arrange for \fIscript\fR (a Tk script) to be evaluated whenever
the event(s) given by \fIsequence\fR occur in the window(s)
identified by \fItag\fR.
If \fIscript\fR is prefixed with a ``+'', then it is appended to
any existing binding for \fIsequence\fR; otherwise \fIscript\fR replaces
any existing binding.
If \fIscript\fR is an empty string then the current binding for
\fIsequence\fR is destroyed, leaving \fIsequence\fR unbound.
In all of the cases where a \fIscript\fR argument is provided,
\f5bind\fR returns an empty string.
If \fIscript\fR is prefixed with a ``-'', then any existing binding for
\fIsequence\fR, whose script is exactly the same as \fIscript\fR, is removed.
The \fItag\fR argument gives the pathname of the window
to which \fIsequence\fR is bound.
.SS Event Patterns
The \fIsequence\fR 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 \f5a\fR or \f5[\fR. The character
may not be a space character or the character \f5<\fR. This form of
pattern matches a \f5KeyPress\fR event for the particular
character. The second form of pattern is longer but more general.
It has the following syntax:
.IP
.EX
\f5<\fIevent\f5-\fIevent\f5-\fR...\f5-\fIevent\f5>\fR
.EE
.PP
The following events are accepted:
.TP
.BR Key \ or\ Keypress
This represents the press of the character in the following
.IR event .
If there is no following event, this represents the press of
any key. The key letter may be escaped with a backslash
.RB ( \e )
to prevent any character (e.g.
.BR > )
from being treated specially.
.TP
.B Configure
This event occurs whenever the widget is configured
such that its requested size changes.
.TP
.B Control
This represents the press of the character in the following
.I
event
with the Control key pressed. The character may be quoted
as for
.BR Key .
.TP
.BR 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.
.TP
.B ButtonRelease
Like
.BR ButtonPress ,
but represents the release of any button.
.TP
.B Motion
Mouse movement.
.TP
.B Double
Any events in the sequence representing button presses must
be double-clicked for the sequence to match.
.TP
.B Map
The event that a toplevel widget is mapped onto the screen.
.TP
.B Unmap
The event that a toplevel widget is unmapped from the screen.
.TP
.B Enter
The event of the mouse entering the widget from outside.
.TP
.B Leave
The event of the mouse leaving the boundaries of the widget.
.TP
.B FocusIn
The event of the widget getting the keyboard focus.
.TP
.B FocusOut
The event of the widget losing the keyboard focus.
.TP
.B Destroy
The event of the widget being destroyed.
See
.IR destroy (9)
for details of widget destruction.
.RE
.PP
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
.B Motion
events may be combined with button presses (possibly doubled).
.SS Binding Scripts and Substitutions
The \fIscript\fR argument to \f5bind\fR is a Tk script,
which will be executed whenever the given event sequence occurs.
If \fIscript\fR contains
any \f5%\fR characters, then the script will not be
executed directly. Instead, a new script will be
generated by replacing each \f5%\fR, and the character following
it, with information from the current event. The replacement
depends on the character following the \f5%\fR, 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.
.IP \f5%%\fR 5
Replaced with a single percent.
.IP \f5%b\fR 5
The number of the button that was pressed or released. Valid only
for \f5ButtonPress\fR and \f5ButtonRelease\fR events.
.IP \f5%h\fR 5
For
.B Configure
events, this is
the old requested height of the widget.
.IP \f5%s\fR 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.
.IP \f5%w\fR 5
For
.B Configure
events, this is the old requested width of the widget.
.IP \f5%x\fR 5
The x coordinate from the event, relative to the origin
of the toplevel window. Valid only for
.BR Enter ,
.BR Leave ,
and mouse events.
.IP \f5%y\fR 5
The y coordinate from the event, relative to the origin
of the toplevel window. Valid only for
.BR Enter ,
.BR Leave ,
and mouse events.
.IP \f5%A\fR 5
The ASCII character corresponding to a \f5Key\fP event.
.IP \f5%K\fR 5
The pressed character for the event, as four hexadecimal digits.
Valid only for \f5Key\fP events.
.IP \f5%W\fR 5
The path name of the window to which the event was reported (the
\fIwindow\fR field from the event). Valid for all event types.
.IP \f5%X\fR 5
Same as
.B %x
except that the screen coordinate system is used.
.IP \f5%Y\fR 5
Same as
.B %y
except that the screen coordinate system is used.
.LP
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 \f5$\fR and
\f5{\fR may be preceded by backslashes.
This guarantees that the string will be passed through the Tk
parser when the binding script is evaluated.
.SH 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
.B %A
substitution does not work correctly when a quoted character
is re-interpreted by Tk.
.LP
The length of binding scripts is limited to
128 characters.