summaryrefslogtreecommitdiffstats
path: root/doc/bind.n
diff options
context:
space:
mode:
Diffstat (limited to 'doc/bind.n')
-rw-r--r--doc/bind.n78
1 files changed, 48 insertions, 30 deletions
diff --git a/doc/bind.n b/doc/bind.n
index 31cdb9d..97223c7 100644
--- a/doc/bind.n
+++ b/doc/bind.n
@@ -6,7 +6,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: bind.n,v 1.24 2007/10/26 20:13:23 dgp Exp $
+'\" RCS: @(#) $Id: bind.n,v 1.25 2007/10/29 16:04:13 dkf Exp $
'\"
.so man.macros
.TH bind n 8.0 Tk "Tk Built-In Commands"
@@ -25,7 +25,9 @@ If all three arguments are specified, \fBbind\fR will
arrange for \fIscript\fR (a Tcl 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
+If \fIscript\fR is prefixed with a
+.QW + ,
+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
@@ -151,8 +153,9 @@ requirement.
.PP
.VS 8.5
The \fBExtended\fR modifier is, at present, specific to Windows. It
-appears on events that are associated with the keys on the "extended
-keyboard." On a US keyboard, the extended keys include the \fBAlt\fR
+appears on events that are associated with the keys on the
+.QW "extended keyboard" .
+On a US keyboard, the extended keys include the \fBAlt\fR
and \fBControl\fR keys at the right of the keyboard, the cursor keys
in the cluster to the left of the numeric pad, the \fBNumLock\fR key,
the \fBBreak\fR key, the \fBPrintScreen\fR key, and the \fB/\fR and
@@ -268,8 +271,9 @@ it is destroyed.
.RS
.PP
When the \fBDestroy\fR event is delivered
-to a widget, it is in a ``half-dead'' state: the widget still exists,
-but most operations on it will fail.
+to a widget, it is in a
+.QW half-dead
+state: the widget still exists, but most operations on it will fail.
.RE
.IP "\fBFocusIn\fR, \fBFocusOut\fR" 5
The \fBFocusIn\fR and \fBFocusOut\fR events are generated
@@ -280,8 +284,8 @@ and a \fBFocusIn\fR event is sent to the new one.
.PP
In addition,
if the old and new focus windows do not share a common parent,
-``virtual crossing'' focus events are sent to the intermediate
-windows in the hierarchy.
+.QW "virtual crossing"
+focus events are sent to the intermediate windows in the hierarchy.
Thus a \fBFocusIn\fR event indicates
that the target window or one of its descendants has acquired the focus,
and a \fBFocusOut\fR event indicates that the focus
@@ -301,7 +305,8 @@ events are only delivered to the window owning the grab.
.PP
In addition, when the pointer moves
between two windows, \fBEnter\fR and \fBLeave\fR
-``virtual crossing'' events are sent to intermediate windows
+.QW "virtual crossing"
+events are sent to intermediate windows
in the hierarchy in the same manner as for \fBFocusIn\fR and
\fBFocusOut\fR events.
.RE
@@ -316,7 +321,7 @@ associated with a window has been changed, installed, or uninstalled.
.RS
.PP
Widgets may be assigned a private colormap by
-specifying a \fB-colormap\fR option; the window manager
+specifying a \fB\-colormap\fR option; the window manager
is responsible for installing and uninstalling colormaps
as necessary.
.PP
@@ -364,12 +369,17 @@ is equivalent to \fB<ButtonPress-1>\fR.
If the event type is \fBKeyPress\fR or \fBKeyRelease\fR, then
\fIdetail\fR may be specified in the form of an X keysym. Keysyms
are textual specifications for particular keys on the keyboard;
-they include all the alphanumeric ASCII characters (e.g. ``a'' is
-the keysym for the ASCII character ``a''), plus descriptions for
-non-alphanumeric characters (``comma'' is the keysym for the comma
-character), plus descriptions for all the non-ASCII keys on the
-keyboard (``Shift_L'' is the keysym for the left shift key, and
-``F1'' is the keysym for the F1 function key, if it exists). The
+they include all the alphanumeric ASCII characters (e.g.
+.QW a
+is the keysym for the ASCII character
+.QW a ),
+plus descriptions for non-alphanumeric characters
+.PQ comma "is the keysym for the comma character" ,
+plus descriptions for all the non-ASCII keys on the keyboard (e.g.
+.QW Shift_L
+is the keysym for the left shift key, and
+.QW F1
+is the keysym for the F1 function key, if it exists). The
complete list of keysyms is not presented here; it is
available in other X documentation and may vary from system to
system.
@@ -513,7 +523,7 @@ For \fBConfigure\fR and \fBCreate\fR requests, the \fIx\fR and \fIy\fR
coordinates of the window relative to its parent window.
.IP \fB%A\fR 5
Substitutes the UNICODE character corresponding to the event, or
-the empty string if the event doesn't correspond to a UNICODE character
+the empty string if the event does not correspond to a UNICODE character
(e.g. the shift key was pressed). \fBXmbLookupString\fR (or
\fBXLookupString\fR when input method support is turned off) does all
the work of translating from the event to a UNICODE character.
@@ -530,8 +540,11 @@ the delta. The sign of the value represents the direction the mouse
wheel was scrolled.
.IP \fB%E\fR 5
The \fIsend_event\fR field from the event. Valid for all event types.
-\fB0\fR indicates that this is a ``normal'' event, \fB1\fR indicates
-that it is a ``synthetic'' event generated by \fBSendEvent\fR.
+\fB0\fR indicates that this is a
+.QW normal
+event, \fB1\fR indicates that it is a
+.QW synthetic
+event generated by \fBSendEvent\fR.
.IP \fB%K\fR 5
The keysym corresponding to the event, substituted as a textual
string. Valid only for \fBKeyPress\fR and \fBKeyRelease\fR events.
@@ -586,7 +599,7 @@ actually executed will be
.CE
This will cause the \fBinsert\fR to receive the original replacement
string (open square bracket) as its first argument.
-If the extra backslash hadn't been added, Tcl would not have been
+If the extra backslash had not been added, Tcl would not have been
able to parse the script correctly.
.SH "MULTIPLE MATCHES"
.PP
@@ -614,21 +627,28 @@ have the same \fItag\fR, then the most specific binding
is chosen and its script is evaluated.
The following tests are applied, in order, to determine which of
several matching sequences is more specific:
-(a) an event pattern that specifies a specific button or key is more specific
-than one that doesn't;
-(b) a longer sequence (in terms of number
+.RS
+.IP (a)
+an event pattern that specifies a specific button or key is more specific
+than one that does not;
+.IP (b)
+a longer sequence (in terms of number
of events matched) is more specific than a shorter sequence;
-(c) if the modifiers specified in one pattern are a subset of the
+.IP (c)
+if the modifiers specified in one pattern are a subset of the
modifiers in another pattern, then the pattern with more modifiers
is more specific.
-(d) a virtual event whose physical pattern matches the sequence is less
+.IP (d)
+a virtual event whose physical pattern matches the sequence is less
specific than the same physical pattern that is not associated with a
virtual event.
-(e) given a sequence that matches two or more virtual events, one
+.IP (e)
+given a sequence that matches two or more virtual events, one
of the virtual events will be chosen, but the order is undefined.
+.RE
.PP
If the matching sequences contain more than one event, then tests
-(c)-(e) are applied in order from the most recent event to the least recent
+(c)\-(e) are applied in order from the most recent event to the least recent
event in the sequences. If these tests fail to determine a winner, then the
most recently registered sequence is the winner.
.PP
@@ -694,14 +714,12 @@ A little GUI that displays what the keysym name of the last key
pressed is:
.CS
set keysym "Press any key"
-pack [label .l -textvariable keysym -padx 2m -pady 1m]
+pack [label .l \-textvariable keysym \-padx 2m \-pady 1m]
\fBbind\fR . <Key> {
set keysym "You pressed %K"
}
.CE
-
.SH "SEE ALSO"
bgerror(n), bindtags(n), event(n), focus(n), grab(n), keysyms(n)
-
.SH KEYWORDS
binding, event