20060303-partial

1 files changed, 194 insertions, 0 deletions

diff --git a/man/9/bind b/man/9/bind
new file mode 100644
index 00000000..103e61a3
--- /dev/null
+++ b/man/9/bind
@@ -0,0 +1,194 @@
+.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 INTRODUCTION
+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.
+.SH "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:
+.RS
+.EX
+\f5<\fIevent\f5-\fIevent\f5-\fR...\f5-\fIevent\f5>\fR
+.EE
+.RE
+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.
+.RE
+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).
+.TP
+.B Destroy
+The event of the widget being destroyed.
+See
+.IR destroy  (9)
+for details of widget destruction.
+
+.SH "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.
+