* doc/bind.n: Added more information on event types and details

[FRQ #523593 "bind(n) manpage needs more detail"]

2 files changed, 192 insertions, 14 deletions

diff --git a/ChangeLog b/ChangeLog
index 539ae71..8bcae92 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2003-08-19  Joe English  <jenglish@users.sourceforge.net>
+	* doc/bind.n: Added more information on event types and details
+	[FRQ #523593 "bind(n) manpage needs more detail"]
+
 2003-08-18  Mo DeJong  <mdejong@users.sourceforge.net>
 
 	* win/configure: Regen.
diff --git a/doc/bind.n b/doc/bind.n
index 5704ba7..2bc4673 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 2002/09/30 09:35:39 dkf Exp $
+'\" RCS: @(#) $Id: bind.n,v 1.8 2003/08/19 19:08:08 jenglish Exp $
 '\" 
 .so man.macros
 .TH bind n 8.0 Tk "Tk Built-In Commands"
@@ -176,7 +176,6 @@ 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
 these events in any X window programming book.  A couple of the events
@@ -209,7 +208,161 @@ this value is at least 120 before it is reported.  However, higher
 resolution devices may be available in the future.  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
+.IP \fBKeyRelease\fP
+\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
+.IP \fBButtonRelease\fP
+.IP \fBMotion\fP
+\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.
+.br
+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.
+
+
+.IP \fBConfigure\fP
+\fBConfigure\fP events are 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
+.IP \fBUnmap\fP
+\fBMap\fP and \fBUnmap\fP events are generated whenever the mapping
+state of a window changes.
+.br
+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).
+.br
+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.
+
+.IP \fBVisibility\fP
+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
+\fBExpose\fP events are 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
+A \fBDestroy\fP event is delivered to a window when 
+it is destroyed.
+.br
+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.
+
+.IP \fBFocusIn\fP
+.IP \fBFocusOut\fP
+\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.
+.br
+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.
+.br
+The keyboard focus may be changed explicitly by a call to \fBfocus\fP,
+or implicitly by the window manager.  
+
+.IP \fBEnter\fP
+.IP \fBLeave\fP
+.br
+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.  
+.br
+If there is a pointer grab in effect, \fBEnter\fP and \fBLeave\fP
+events are only delivered to the window owning the grab.
+.br 
+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.
+
+.IP \fBProperty\fP
+\fBProperty\fP events are 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.
+.br
+Note that Tk provides no useful details for this event type.
+
+.IP \fBColormap\fP
+\fBColormap\fP events are generated whenever the colormap
+associated with a window has been changed, installed, or uninstalled.
+.br
+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.
+.br
+Note that Tk provides no useful details for this event type.
+
+.\" Added in wm-enablers patch:
+.IP \fBMapRequest\fP
+.IP \fBCirculateRequest\fP
+.IP \fBResizeRequest\fP
+.IP \fBConfigureRequest\fP
+.IP \fBCreate\fP
+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
+.IP \fBReparent\fP
+.IP \fBCirculate\fP
+\fBGravity\fP,
+and
+\fBReparent\fP
+are not normally delivered to Tk applications.
+They are included for completeness.
+.br
+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 a \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.
+
+.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
@@ -272,11 +425,16 @@ types.
 The \fIabove\fR field from the event,
 formatted as a hexadecimal number.
 Valid only for \fBConfigure\fR events.
+Inidicates 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,
@@ -301,16 +459,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.
+Inidicates 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.
@@ -336,20 +497,29 @@ is substituted.  For \fBVisibility\fR, one of the strings
 \fBVisibilityUnobscured\fR, \fBVisibilityPartiallyObscured\fR,
 and \fBVisibilityFullyObscured\fR is substituted.
 .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.
+Inidicates 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.
+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
+cooredinates 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
@@ -371,6 +541,8 @@ 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.
@@ -396,6 +568,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
@@ -403,6 +576,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.
@@ -526,7 +700,7 @@ The \fBbgerror\fR command will be executed at global level
 (outside the context of any Tcl procedure).
 
 .SH "SEE ALSO"
-bgerror, keysyms
+bgerror, keysyms, grab, focus, bindtags, event
 
 .SH KEYWORDS
-form, manual
+binding, event