ref: 866d74c0c4bb50e85e9e8bb95140c10d409e53be
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.