Added examples and did some doc L&F improvements.

2 files changed, 80 insertions, 81 deletions

diff --git a/ChangeLog b/ChangeLog
index 7c49bd5..1216b3a 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2004-04-23  Donal K. Fellows  <donal.k.fellows@man.ac.uk>
+
+	* doc/bind.n: Added examples (in line with the parallel programme
+	for adding examples to Tcl manual pages) and made assorted minor
+	alterations to improve the overall look.
+
 2004-04-21  Donal K. Fellows  <donal.k.fellows@man.ac.uk>
 
 	* tests/textDisp.test: Get rid of windows that are no longer
diff --git a/doc/bind.n b/doc/bind.n
index 18444b4..c92bd41 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.10 2004/01/09 22:26:24 pspjuth Exp $
+'\" RCS: @(#) $Id: bind.n,v 1.11 2004/04/23 13:47:46 dkf Exp $
 '\" 
 .so man.macros
 .TH bind n 8.0 Tk "Tk Built-In Commands"
@@ -24,7 +24,7 @@ bind \- Arrange for X events to invoke Tcl scripts
 \fBbind\fI tag sequence \fB+\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,16 +56,16 @@ 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.
 
@@ -91,8 +91,8 @@ type, and an extra piece of information (\fIdetail\fR) identifying
 a particular button or keysym.  Any of the fields may be omitted,
 as long as at least one of \fItype\fR and \fIdetail\fR is present.
 The fields must be separated by white space or dashes.
-.VS
 .PP
+.VS
 The third form of pattern is used to specify a user-defined, named virtual
 event.  It has the following syntax:
 .CS
@@ -105,8 +105,13 @@ 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.  
+
+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"
+
+.SS "MODIFIERS"
 .PP
 Modifiers consist of any of the following values:
 .DS
@@ -155,7 +160,7 @@ substantial mouse motion in between.  For example, \fB<Double-Button-1>\fR
 is equivalent to \fB<Button-1><Button-1>\fR with the extra time and space
 requirement.
 
-.SH "EVENT TYPES"
+.SS "EVENT TYPES"
 .PP
 The \fItype\fR field may be any of the standard X event types, with a
 few extra abbreviations.  The \fItype\fR field will also accept a
@@ -163,7 +168,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,15 +180,13 @@ ConfigureRequest	KeyRelease	Unmap
 Create	Leave	Visibility
 Deactivate\fR
 .DE
-.PP
 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
 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
@@ -208,82 +211,68 @@ 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.
-
-.IP \fBKeyPress\fP
-.IP \fBKeyRelease\fP
-\fBKeyPress\fP and \fBKeyRelease\fP events are generated
+.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
-.IP \fBButtonRelease\fP
-.IP \fBMotion\fP
-\fBButtonPress\fP and \fBButtonRelease\fP events
+.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.
-.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
+.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
-.IP \fBUnmap\fP
-\fBMap\fP and \fBUnmap\fP events are generated whenever the mapping
+.IP "\fBMap\fP, \fBUnmap\fP" 5
+The \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
+.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
-\fBExpose\fP events are generated whenever all or part of a
+.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
+.IP \fBDestroy\fP 5
 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
+.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.
-.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
@@ -292,64 +281,50 @@ 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
+.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.  
-.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
+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.
-
+\fBProperty\fP events are not normally delivered to Tk applications as
+they are handled by the Tk core.
 .IP \fBColormap\fP
-\fBColormap\fP events are generated whenever the colormap
+A \fBColormap\fP event is 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
+Note that Tk provides no useful details for this event type.
+'\" 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
-.IP \fBReparent\fP
-.IP \fBCirculate\fP
-\fBGravity\fP,
-and
-\fBReparent\fP
+.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.
-.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.
@@ -360,7 +335,7 @@ 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"
+.SS "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
@@ -511,8 +486,7 @@ Valid only for
 \fBConfigure\fR, \fBConfigureRequest\fR, \fBCreate\fR,
 \fBResizeRequest\fR, and \fBExpose\fR events.
 .VE
-.IP \fB%x\fR 5
-.IP \fB%y\fR 5
+.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,
@@ -532,8 +506,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
@@ -698,15 +672,34 @@ 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
+bind . <Double-1> {
+    puts "hi from (%x,%y)"
+}
+.CE
+
+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]
+bind . <Key> {
+    set keysym "You pressed %K"
+}
+.CE
+
 .SH "SEE ALSO"
-bgerror, keysyms, grab, focus, bindtags, event
+bgerror(n), keysyms(n), grab(n), focus(n), bindtags(n), event(n)
 
 .SH KEYWORDS
 binding, event