diff options
Diffstat (limited to 'doc/bind.n')
| -rw-r--r-- | doc/bind.n | 78 |
1 files changed, 48 insertions, 30 deletions
@@ -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 |