Tidy up and expand examples.

1 files changed, 38 insertions, 9 deletions

diff --git a/doc/event.n b/doc/event.n
index 8e23025..01b1208 100644
--- a/doc/event.n
+++ b/doc/event.n
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: event.n,v 1.21 2008/09/23 13:36:39 dkf Exp $
+'\" RCS: @(#) $Id: event.n,v 1.22 2009/03/10 11:13:53 dkf Exp $
 '\" 
 .so man.macros
 .TH event n 8.3 Tk "Tk Built-In Commands"
@@ -376,24 +376,29 @@ Redo one undone action.
 .TP
 \fB<<Undo>>\fR
 Undo the last action.
-.SH "VIRTUAL EVENT EXAMPLES"
+.SH EXAMPLES
+.SS "MAPPING KEYS TO VIRTUAL EVENTS"
 .PP
 In order for a virtual event binding to trigger, two things must
 happen.  First, the virtual event must be defined with the
 \fBevent add\fR command.  Second, a binding must be created for
 the virtual event with the \fBbind\fR command.
 Consider the following virtual event definitions:
+.PP
 .CS
-event add <<Paste>> <Control-y>
-event add <<Paste>> <Button-2>
-event add <<Save>> <Control-X><Control-S>
-event add <<Save>> <Shift-F12>
+\fBevent add\fR <<Paste>> <Control-y>
+\fBevent add\fR <<Paste>> <Button-2>
+\fBevent add\fR <<Save>> <Control-X><Control-S>
+\fBevent add\fR <<Save>> <Shift-F12>
 .CE
+.PP
 In the \fBbind\fR command, a virtual event can be bound like any other
 builtin event type as follows:
+.PP
 .CS
 bind Entry <<Paste>> {%W insert [selection get]}
 .CE
+.PP
 The double angle brackets are used to specify that a virtual event is being
 bound.  If the user types Control-y or presses button 2, or if
 a \fB<<Paste>>\fR virtual event is synthesized with \fBevent generate\fR,
@@ -402,11 +407,13 @@ then the \fB<<Paste>>\fR binding will be invoked.
 If a virtual binding has the exact same sequence as a separate
 physical binding, then the physical binding will take precedence.
 Consider the following example:
+.PP
 .CS
-event add <<Paste>> <Control-y> <Meta-Control-y>
+\fBevent add\fR <<Paste>> <Control-y> <Meta-Control-y>
 bind Entry <Control-y> {puts Control-y}
 bind Entry <<Paste>> {puts Paste}
 .CE
+.PP
 When the user types Control-y the \fB<Control-y>\fR binding
 will be invoked, because a physical event is considered
 more specific than a virtual event, all other things being equal.
@@ -424,15 +431,37 @@ ungeneratable.
 When a definition of a virtual event changes at run time, all windows
 will respond immediately to the new definition.
 Starting from the preceding example, if the following code is executed:
+.PP
 .CS
-bind <Entry> <Control-y> {}
-event add <<Paste>> <Key-F6>
+bind Entry <Control-y> {}
+\fBevent add\fR <<Paste>> <Key-F6>
 .CE
+.PP
 the behavior will change such in two ways.  First, the shadowed
 \fB<<Paste>>\fR binding will emerge.
 Typing Control-y will no longer invoke the \fB<Control-y>\fR binding, 
 but instead invoke the virtual event \fB<<Paste>>\fR.  Second,
 pressing the F6 key will now also invoke the \fB<<Paste>>\fR binding.
+.SS "MOVING THE MOUSE POINTER"
+.PP
+Sometimes it is useful to be able to really move the mouse pointer. For
+example, if you have some software that is capable of demonstrating directly
+to the user how to use the program. To do this, you need to
+.QW warp
+the mouse around by using \fBevent generate\fR, like this:
+.PP
+.CS
+for {set xy 0} {$xy < 200} {incr xy} {
+    \fBevent generate\fR . <Motion> -x $xy -y $xy -warp 1
+    update
+    after 50
+}
+.CE
+.PP
+Note that it is usually considered bad style to move the mouse pointer for the
+user because it removes control from them. Therefore this technique should be
+used with caution. Also note that it is not guaranteed to function on all
+platforms.
 .SH "SEE ALSO"
 bind(n)
 .SH KEYWORDS