Backport of documentation fixes

FossilOrigin-Name: 2c695c7927060a39a4165a3edc998914ebfa1b80

1 files changed, 221 insertions, 45 deletions

diff --git a/doc/bind.n b/doc/bind.n
index 1238641..cb101a4 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.7.2.1 2004/02/16 23:20:02 wolfsuit Exp $
+'\" RCS: @(#) $Id: bind.n,v 1.7.2.2 2004/10/28 10:19:29 dkf Exp $
 '\" 
 .so man.macros
 .TH bind n 8.0 Tk "Tk Built-In Commands"
@@ -15,16 +15,10 @@
 .SH NAME
 bind \- Arrange for X events to invoke Tcl scripts
 .SH SYNOPSIS
-\fBbind\fI tag\fR
-.sp
-\fBbind\fI tag sequence\fR
-.sp
-\fBbind\fI tag sequence script\fR
-.sp
-\fBbind\fI tag sequence \fB+\fIscript\fR
+\fBbind\fI tag\fR ?\fIsequence\fR? ?\fB+\fR??\fIscript\fR?
 .BE
 
-.SH INTRODUCTION
+.SH "INTRODUCTION"
 .PP
 The \fBbind\fR command associates Tcl scripts with X events.
 If all three arguments are specified, \fBbind\fR will
@@ -56,19 +50,18 @@ the window.
 Although the \fBbindtags\fR command may be used to assign an
 arbitrary set of binding tags to a window, the default binding
 tags provide the following behavior:
-.IP
+.IP \(bu 3
 If a tag is the name of an internal window the binding applies
 to that window.
-.IP
+.IP \(bu 3
 If the tag is the name of a toplevel window the binding applies
 to the toplevel window and all its internal windows.
-.IP
+.IP \(bu 3
 If the tag is the name of a class of widgets, such as \fBButton\fR,
 the binding applies to all widgets in that class;
-.IP
+.IP \(bu 3
 If \fItag\fR has the value \fBall\fR,
 the binding applies to all windows in the application.
-
 .SH "EVENT PATTERNS"
 .PP
 The \fIsequence\fR argument specifies a sequence of one or more
@@ -105,6 +98,10 @@ virtual event to modify it.  Bindings on a virtual event may be created
 before the virtual event is defined, and if the definition of a virtual
 event changes dynamically, all windows bound to that virtual event will
 respond immediately to the new definition.  
+.PP
+Some widgets (e.g. \fBmenu\fR and \fBtext\fR) issue virtual events
+when their internal state is updated in some ways.  Please see the
+manual page for each widget for details.
 .VE
 .SH "MODIFIERS"
 .PP
@@ -137,9 +134,9 @@ If no modifiers are specified, then any combination of modifiers may
 be present in the event.
 .PP
 \fBMeta\fR and \fBM\fR refer to whichever of the
-\fBM1\fR through \fBM5\fR modifiers is associated with the meta
+\fBM1\fR through \fBM5\fR modifiers is associated with the Meta
 key(s) on the keyboard (keysyms \fBMeta_R\fR and \fBMeta_L\fR).
-If there are no meta keys, or if they are not associated with any
+If there are no Meta keys, or if they are not associated with any
 modifiers, then \fBMeta\fR and \fBM\fR will not match any events.
 Similarly, the \fBAlt\fR modifier refers to whichever modifier
 is associated with the alt key(s) on the keyboard (keysyms
@@ -163,7 +160,7 @@ couple non-standard X event types that were added to better support
 the Macintosh and Windows platforms.  Below is a list of all the valid
 types; where two names appear together, they are synonyms.
 .DS
-.ta 5c 10c
+.ta \w'ButtonPress, Button\0\0\0'u +\w'KeyPress, Key\0\0\0'u
 \fBActivate	Destroy	Map
 ButtonPress, Button	Enter	MapRequest
 ButtonRelease	Expose	Motion
@@ -175,7 +172,6 @@ ConfigureRequest	KeyRelease	Unmap
 Create	Leave	Visibility
 Deactivate\fR
 .DE
-.PP
 .VS
 Most of the above events have the same fields and behaviors as events
 in the X Windowing system.  You can find more detailed descriptions of
@@ -183,8 +179,7 @@ these events in any X window programming book.  A couple of the events
 are extensions to the X event system to support features unique to the
 Macintosh and Windows platforms.  We provide a little more detail on
 these events here.  These include:
-.IP \fBActivate\fR 5
-.IP \fBDeactivate\fR 5
+.IP "\fBActivate\fR, \fBDeactivate\fR" 5
 These two events are sent to every sub-window of a toplevel when they
 change state.  In addition to the focus Window, the Macintosh platform
 and Windows platforms have a notion of an active window (which often
@@ -200,11 +195,12 @@ Some mice on the Windows platform support a mouse wheel which is used
 for scrolling documents without using the scrollbars.  By rolling the
 wheel, the system will generate \fBMouseWheel\fR events that the
 application can use to scroll.  On Windows, the event is
-always routed to the window that currently has focus. On Mac OS X,
+always routed to the window that currently has focus (like \fBKey\fR
+events.) On Mac OS X,
 the event is routed to the window under the pointer.  When the event
 is received you can use the \fB%D\fR substitution to get the
-\fIdelta\fR field for the event which is a integer value of motion
-that the mouse wheel has moved.  The smallest value for which the
+\fIdelta\fR field for the event, which is a integer value describing how
+the mouse wheel has moved.  The smallest value for which the
 system will report is defined by the OS.  On Windows 95 & 98 machines
 this value is at least 120 before it is reported.  However, higher
 resolution devices may be available in the future.  On Mac OS X, the value is
@@ -212,6 +208,144 @@ not scaled by 120, but a value of 1 corresponds to roughly one text line.
 The sign of the value determines which direction your widget should scroll.  
 Positive values should scroll up and negative values should scroll down.
 .VE
+.IP "\fBKeyPress\fP, \fBKeyRelease\fP" 5
+The \fBKeyPress\fP and \fBKeyRelease\fP events are generated
+whenever a key is pressed or released.  \fBKeyPress\fP and \fBKeyRelease\fP
+events are sent to the window which currently has the keyboard focus.
+.IP "\fBButtonPress\fP, \fBButtonRelease\fP, \fBMotion\fP" 5
+The \fBButtonPress\fP and \fBButtonRelease\fP events
+are generated when the user presses or releases a mouse button.
+\fBMotion\fP events are generated whenever the pointer is moved.
+\fBButtonPress\fP, \fBButtonRelease\fP, and \fBMotion\fP events are 
+normally sent to the window containing the pointer.
+.RS
+.PP
+When a mouse button is pressed, the window containing the pointer
+automatically obtains a temporary pointer grab.
+Subsequent \fBButtonPress\fP, \fBButtonRelease\fP, and \fBMotion\fP 
+events will be sent to that window,
+regardless of which window contains the pointer,
+until all buttons have been released.
+.RE
+.IP \fBConfigure\fP 5
+A \fBConfigure\fP event is sent to a window whenever its
+size, position, or border width changes, and sometimes
+when it has changed position in the stacking order.
+.IP "\fBMap\fP, \fBUnmap\fP" 5
+The \fBMap\fP and \fBUnmap\fP events are generated whenever the mapping
+state of a window changes.
+.RS
+.PP
+Windows are created in the unmapped state.
+Top-level windows become mapped when they transition to the
+\fBnormal\fP state, and are unmapped in the \fBwithdrawn\fP
+and \fBiconic\fP states.
+Other windows become mapped when they are placed under control
+of a geometry manager (for example \fBpack\fP or \fBgrid\fP).
+.PP
+A window is \fIviewable\fP only if it and all of its ancestors are mapped.
+Note that geometry managers typically do not map their children until 
+they have been mapped themselves, and unmap all children
+when they become unmapped; hence in Tk \fBMap\fP and \fBUnmap\fP
+events indicate whether or not a window is viewable.
+.RE
+.IP \fBVisibility\fP 5
+A window is said to be \fIobscured\fP when another window
+above it in the stacking order fully or partially overlaps it.
+\fBVisibility\fP events are generated whenever a window's
+obscurity state changes; the \fIstate\fP field (\fB%s\fP)
+specifies the new state.
+.IP \fBExpose\fP 5
+An \fBExpose\fP event is generated whenever all or part of a
+window should be redrawn (for example, when a window is
+first mapped or if it becomes unobscured).
+It is normally not necessary for client applications to 
+handle \fBExpose\fP events, since Tk handles them internally.
+.IP \fBDestroy\fP 5
+A \fBDestroy\fP event is delivered to a window when 
+it is destroyed.
+.RS
+.PP
+When the \fBDestroy\fP event is delivered
+to a widget, it is in a ``half-dead'' state: the widget still exists,
+but most operations on it will fail.
+.RE
+.IP "\fBFocusIn\fP, \fBFocusOut\fP" 5
+The \fBFocusIn\fP and \fBFocusOut\fP events are generated
+whenever the keyboard focus changes.
+A \fBFocusOut\fP event is sent to the old focus window,
+and a \fBFocusIn\fP event is sent to the new one.
+.RS
+.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.
+Thus a \fBFocusIn\fP event indicates
+that the target window or one of its descendants has acquired the focus,
+and a \fBFocusOut\fP event indicates that the focus 
+has been changed to a window outside the target window's hierarchy.
+.PP
+The keyboard focus may be changed explicitly by a call to \fBfocus\fP,
+or implicitly by the window manager.  
+.RE
+.IP "\fBEnter\fP, \fBLeave\fP" 5
+An \fBEnter\fP event is sent to a window when the pointer
+enters that window, and a \fBLeave\fP event is sent when
+the pointer leaves it.  
+.RS
+.PP
+If there is a pointer grab in effect, \fBEnter\fP and \fBLeave\fP
+events are only delivered to the window owning the grab.
+.PP
+In addition, when the pointer moves
+between two windows, \fBEnter\fP and \fBLeave\fP
+``virtual crossing'' events are sent to intermediate windows
+in the hierarchy in the same manner as for \fBFocusIn\fP and
+\fBFocusOut\fP events.
+.RE
+.IP \fBProperty\fP
+A \fBProperty\fP event is sent to a window whenever an X property
+belonging to that window is changed or deleted.
+\fBProperty\fP events are not normally delivered to Tk applications as
+they are handled by the Tk core.
+.IP \fBColormap\fP
+A \fBColormap\fP event is generated whenever the colormap
+associated with a window has been changed, installed, or uninstalled.
+.RS
+.PP
+Widgets may be assigned a private colormap by
+specifying a \fB-colormap\fP option; the window manager
+is responsible for installing and uninstalling colormaps
+as necessary.
+.PP
+Note that Tk provides no useful details for this event type.
+.RE
+'\" The following events were added in TIP#47
+.IP "\fBMapRequest\fP, \fBCirculateRequest\fP, \fBResizeRequest\fP, \fBConfigureRequest\fP, \fBCreate\fP" 5
+These events are not normally delivered to Tk applications.
+They are included for completeness, to make it possible to
+write X11 window managers in Tk.
+(These events are only delivered when a client has
+selected \fBSubstructureRedirectMask\fP on a window;
+the Tk core does not use this mask.)
+.IP "\fBGravity\fP, \fBReparent\fP, \fBCirculate\fP" 5
+The events \fBGravity\fP and \fBReparent\fP
+are not normally delivered to Tk applications.
+They are included for completeness.
+.RS
+.PP
+A \fBCirculate\fP event indicates that the window has moved
+to the top or to the bottom of the stacking order as
+a result of an \fBXCirculateSubwindows\fP protocol request.
+Note that the stacking order may be changed for other reasons
+which do not generate a \fBCirculate\fP event, and that
+Tk does not use \fBXCirculateSubwindows()\fP internally.
+This event type is included only for completeness;
+there is no reliable way to track changes to a window's
+position in the stacking order.
+.RE
+.SH "EVENT DETAILS"
 .PP
 The last part of a long event specification is \fIdetail\fR.  In the
 case of a \fBButtonPress\fR or \fBButtonRelease\fR event, it is the
@@ -233,7 +367,7 @@ 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 keysm for the left shift key, and
+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
 complete list of keysyms is not presented here;  it is
 available in other X documentation and may vary from system to
@@ -244,7 +378,6 @@ If a keysym \fIdetail\fR is given, then the
 \fItype\fR field may be omitted;  it will default to \fBKeyPress\fR.
 For example, \fB<Control-comma>\fR is equivalent to
 \fB<Control-KeyPress-comma>\fR.
-
 .SH "BINDING SCRIPTS AND SUBSTITUTIONS"
 .PP
 The \fIscript\fR argument to \fBbind\fR is a Tcl script,
@@ -274,11 +407,16 @@ types.
 The \fIabove\fR field from the event,
 formatted as a hexadecimal number.
 Valid only for \fBConfigure\fR events.
+Indicates the sibling window immediately below the receiving window
+in the stacking order, or \fB0\fP if the receiving window is at the
+bottom.
 .IP \fB%b\fR 5
 The number of the button that was pressed or released.  Valid only
 for \fBButtonPress\fR and \fBButtonRelease\fR events.
 .IP \fB%c\fR 5
 The \fIcount\fR field from the event.  Valid only for \fBExpose\fR events.
+Indicates that there are \fIcount\fP pending \fBExpose\fP events which have not
+yet been delivered to the window.
 .IP \fB%d\fR 5
 The \fIdetail\fR field from the event.  The \fB%d\fR is replaced by
 a string identifying the detail.  For \fBEnter\fR,
@@ -303,16 +441,19 @@ For events other than these, the substituted string is undefined.
 .RE
 .IP \fB%f\fR 5
 The \fIfocus\fR field from the event (\fB0\fR or \fB1\fR).  Valid only
-for \fBEnter\fR and \fBLeave\fR events.
+for \fBEnter\fR and \fBLeave\fR events.  \fB1\fP if the receiving 
+window is the focus window or a descendant of the focus window, 
+\fB0\fP otherwise.
 .IP \fB%h\fR 5
 .VS
 The \fIheight\fR field from the event.  Valid for the \fBConfigure\fR,
 \fBConfigureRequest\fR, \fBCreate\fR, \fBResizeRequest\fR, and
 \fBExpose\fR events.
+Indicates the new or requested height of the window.
 .VE
 .IP \fB%i\fR 5
 The \fIwindow\fR field from the event, represented as a hexadecimal
-integer.
+integer.  Valid for all event types.
 .IP \fB%k\fR 5
 The \fIkeycode\fR field from the event.  Valid only for \fBKeyPress\fR
 and \fBKeyRelease\fR events.
@@ -337,21 +478,33 @@ The \fIstate\fR field from the event.  For \fBButtonPress\fR,
 is substituted.  For \fBVisibility\fR, one of the strings
 \fBVisibilityUnobscured\fR, \fBVisibilityPartiallyObscured\fR,
 and \fBVisibilityFullyObscured\fR is substituted.
+For \fBProperty\fP events, substituted with
+either the string \fBNewValue\fP (indicating that the property
+has been created or modified) or \fBDelete\fP (indicating that
+the property has been removed).
 .IP \fB%t\fR 5
-The \fItime\fR field from the event.  Valid only for events that
-contain a \fItime\fR field.
+The \fItime\fR field from the event.
+This is the X server timestamp (typically the time since
+the last server reset) in milliseconds, when the event occurred.
+Valid for most events.  
 .IP \fB%w\fR 5
-The \fIwidth\fR field from the event.  Valid only for
+The \fIwidth\fR field from the event.
+Indicates the new or requested width of the window.
+Valid only for
 .VS
 \fBConfigure\fR, \fBConfigureRequest\fR, \fBCreate\fR,
 \fBResizeRequest\fR, and \fBExpose\fR events.
 .VE
-.IP \fB%x\fR 5
-The \fIx\fR field from the event.  Valid only for events containing
-an \fIx\fR field.
-.IP \fB%y\fR 5
-The \fIy\fR field from the event.  Valid only for events containing
-a \fIy\fR field.
+.IP "\fB%x\fR, \fB%y\fR" 5
+The \fIx\fR and \fIy\fR fields from the event.
+For \fBButtonPress\fP, \fBButtonRelease\fP, \fBMotion\fP, 
+\fBKeyPress\fP, \fBKeyRelease\fP, and \fBMouseWheel\fP events,
+\fB%x\fP and \fB%y\fP indicate the position of the mouse pointer
+relative to the receiving window.
+For \fBEnter\fP and \fBLeave\fP events, the position where the 
+mouse pointer crossed the window, relative to the receiving window.
+For \fBConfigure\fP and \fBCreate\fP requests, the \fIx\fP and \fIy\fP
+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
@@ -362,8 +515,8 @@ Valid only for \fBKeyPress\fR and \fBKeyRelease\fR events.
 .IP \fB%B\fR 5
 The \fIborder_width\fR field from the event.  Valid only for
 \fBConfigure\fR, \fBConfigureRequest\fR, and \fBCreate\fR events.
-.VS
 .IP \fB%D\fR 5
+.VS
 This reports the \fIdelta\fR value of a \fBMouseWheel\fR event.  The
 \fIdelta\fR value represents the rotation units the mouse wheel has
 been moved.  On Windows 95 & 98 systems the smallest value for the
@@ -373,12 +526,18 @@ wheel was scrolled.
 .VE
 .IP \fB%E\fR 5
 The \fIsend_event\fR field from the event.  Valid for all event types.
+\fB0\fP indicates that this is a ``normal'' event, \fB1\fP indicates
+that it is a ``synthetic'' event generated by \fBSendEvent\fP.
 .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.
 .IP \fB%N\fR 5
 The keysym corresponding to the event, substituted as a decimal
 number.  Valid only for \fBKeyPress\fR and \fBKeyRelease\fR events.
+.IP \fB%P\fR 5
+The name of the property being updated or deleted (which
+may be converted to an XAtom using \fBwinfo atom\fR.) Valid
+only for \fBProperty\fP events.
 .IP \fB%R\fR 5
 The \fIroot\fR window identifier from the event.  Valid only for
 events containing a \fIroot\fR field.
@@ -398,6 +557,7 @@ value is the corresponding x-coordinate in the virtual root.
 Valid only for
 \fBButtonPress\fR, \fBButtonRelease\fR, \fBKeyPress\fR, \fBKeyRelease\fR,
 and \fBMotion\fR events.
+Same meaning as \fB%x\fP, except relative to the (virtual) root window.
 .IP \fB%Y\fR 5
 The \fIy_root\fR field from the event.
 If a virtual-root window manager is being used then the substituted
@@ -405,6 +565,7 @@ value is the corresponding y-coordinate in the virtual root.
 Valid only for
 \fBButtonPress\fR, \fBButtonRelease\fR, \fBKeyPress\fR, \fBKeyRelease\fR,
 and \fBMotion\fR events.
+Same meaning as \fB%y\fP, except relative to the (virtual) root window.
 .LP
 The replacement string for a %-replacement is formatted as a proper
 Tcl list element.
@@ -430,7 +591,6 @@ 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
 able to parse the script correctly.
-
 .SH "MULTIPLE MATCHES"
 .PP
 It is possible for several bindings to match a given X event.
@@ -483,8 +643,8 @@ be picked at random:
 event add <<Paste>> <Control-y>
 event add <<Paste>> <Button-2>
 event add <<Scroll>> <Button-2>
-bind Entry <<Paste>> {puts Paste}
-bind Entry <<Scroll>> {puts Scroll}
+\fBbind\fR Entry <<Paste>> {puts Paste}
+\fBbind\fR Entry <<Scroll>> {puts Scroll}
 .CE
 If the user types Control-y, the \fB<<Paste>>\fR binding
 will be invoked, but if the user presses button 2 then one of
@@ -494,7 +654,6 @@ be invoked, but exactly which one gets invoked is undefined.
 If an X event does not match any of the existing bindings, then the
 event is ignored.
 An unbound event is not considered to be an error.
-
 .SH "MULTI-EVENT SEQUENCES AND IGNORED EVENTS"
 .PP
 When a \fIsequence\fR specified in a \fBbind\fR command contains
@@ -519,16 +678,33 @@ key, and a press of the \fBb\fR key:  the press of \fBShift\fR is
 ignored because it is a modifier key.
 Finally, if several \fBMotion\fR events occur in a row, only
 the last one is used for purposes of matching binding sequences.
-
-.SH ERRORS
+.SH "ERRORS"
 .PP
 If an error occurs in executing the script for a binding then the
 \fBbgerror\fR mechanism is used to report the error.
 The \fBbgerror\fR command will be executed at global level
 (outside the context of any Tcl procedure).
+.SH "EXAMPLES"
+Arrange for a string describing the motion of the mouse to be printed
+out when the mouse is double-clicked:
+.CS
+\fBbind\fR . <Double-1> {
+    puts "hi from (%x,%y)"
+}
+.CE
+.PP
+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]
+\fBbind\fR . <Key> {
+    set keysym "You pressed %K"
+}
+.CE
 
 .SH "SEE ALSO"
-bgerror, keysyms
+bgerror(n), bindtags(n), event(n), focus(n), grab(n), keysyms(n)
 
 .SH KEYWORDS
-form, manual
+binding, event