Added example and warning about global grabs

FossilOrigin-Name: c759e94d2ccf82d4d1cf36b3dfc5f315d91bf148

1 files changed, 16 insertions, 2 deletions

diff --git a/doc/grab.n b/doc/grab.n
index 887ae66..a47c13d 100644
--- a/doc/grab.n
+++ b/doc/grab.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: grab.n,v 1.2 1998/09/14 18:22:56 stanton Exp $
+'\" RCS: @(#) $Id: grab.n,v 1.3 2004/06/21 21:19:41 dkf Exp $
 '\" 
 .so man.macros
 .TH grab n "" Tk "Tk Built-In Commands"
@@ -102,7 +102,11 @@ does nothing.  Returns an empty string.
 Returns \fBnone\fR if no grab is currently set on \fIwindow\fR,
 \fBlocal\fR if a local grab is set on \fIwindow\fR, and
 \fBglobal\fR if a global grab is set.
-
+.SH WARNING
+It is very easy to use global grabs to render a display completely
+unusable (e.g. by setting a grab on a widget which does not respond to
+events and not providing any mechanism for releasing the grab).  Take
+\fIextreme\fR care when using them!
 .SH BUGS
 .PP
 It took an incredibly complex and gross implementation to produce
@@ -117,6 +121,16 @@ If a single process is managing several different Tk applications,
 only one of those applications can have a local grab for a given
 display at any given time.  If the applications are in different
 processes, this restriction doesn't exist.
+.SH EXAMPLE
+Set a grab so that only one button may be clicked out of a group.  The
+other buttons are unresponsive to the mouse until the middle button is
+clicked.
+.CS
+pack [button .b1 \-text "Click me! #1" \-command {destroy .b1}]
+pack [button .b2 \-text "Click me! #2" \-command {destroy .b2}]
+pack [button .b3 \-text "Click me! #3" \-command {destroy .b3}]
+grab .b2
+.CE
 
 .SH KEYWORDS
 grab, keyboard events, pointer events, window