From 8419030e7f65bf9a2669a578217772e8cf95ebf9 Mon Sep 17 00:00:00 2001
From: ericm <ericm>
Date: Tue, 25 Apr 2000 02:12:14 +0000
Subject: * unix/mkLinks: * doc/Grab.3: Man page for Tk_Grab and Tk_Ungrab
 [Bug: 1868, 1889]

---
 ChangeLog    |  3 +++
 doc/Grab.3   | 65 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 unix/mkLinks |  8 ++++++++
 3 files changed, 76 insertions(+)
 create mode 100644 doc/Grab.3

diff --git a/ChangeLog b/ChangeLog
index d863979..f357ee2 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,6 +1,9 @@
 2000-04-24  Eric Melski  <ericm@scriptics.com>
 
 	* unix/mkLinks: 
+	* doc/Grab.3: Man page for Tk_Grab and Tk_Ungrab [Bug: 1868, 1889]
+
+	* unix/mkLinks: 
 	* doc/MainWin.3: Added entry for Tk_GetNumMainWindows [Bug: 1865].
 
 	* unix/mkLinks: 
diff --git a/doc/Grab.3 b/doc/Grab.3
new file mode 100644
index 0000000..02ae55f
--- /dev/null
+++ b/doc/Grab.3
@@ -0,0 +1,65 @@
+'\"
+'\" Copyright (c) 1998-2000 by Scriptics Corporation.
+'\" All rights reserved.
+'\" 
+'\" RCS: @(#) $Id: Grab.3,v 1.1 2000/04/25 02:12:15 ericm Exp $
+'\" 
+.so man.macros
+.TH Tk_Grab 3 "" Tk "Tk Library Procedures"
+.BS
+.SH NAME
+Tk_Grab, Tk_Ungrab \- manipulate grab state in an application
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+int
+\fBTk_Grab\fR(\fIinterp, tkwin, grabGlobal\fR)
+.sp
+void
+\fBTk_Ungrab\fR(\fItkwin\fR)
+
+.SH ARGUMENTS
+.AP Tcl_Interp *interp in
+Interpreter to use for error reporting
+.AP Tk_Window tkwin in
+Window on whose behalf the pointer is to be grabbed or released
+.AP int grabGlobal in
+Boolean indicating whether the grab is global or application local
+.BE
+
+.SH DESCRIPTION
+.PP
+These functions are used to set or release a global or
+application local grab.  When a grab is set on a particular window
+in a Tk application, mouse and keyboard events can only be received by
+that window and its descendants.  Mouse and keyboard events for
+windows outside the tree rooted at \fItkwin\fR will be redirected to
+\fItkwin\fR.  If the grab is global, then all mouse and keyboard
+events for windows outside the tree rooted at \fItkwin\fR (even those
+intended for windows in other applications) will be redirected to
+\fItkwin\fR.  If the grab is application local, only mouse and
+keyboard events intended for a windows within the same application
+(but outside the tree rooted at \fItkwin\fR) will be redirected.
+
+.PP
+\fBTk_Grab\fR sets a grab on a particular window.  \fITkwin\fR
+specifies the window on whose behalf the pointer is to be grabbed.
+\fIGrabGlobal\fR indicates whether the grab should be global or
+application local; if it is non-zero, it means the grab should be
+global.  Normally, \fBTk_Grab\fR returns TCL_OK; if an error occurs
+and the grab cannot be set, TCL_ERROR is returned and an error message
+is left if \fIinterp\fR's result.  Once this call completes
+successfully, no window outside the tree rooted at \fItkwin\fR will
+receive pointer- or keyboard-related events until the next call to
+Tk_Ungrab.  If a previous grab was in effect within the application,
+then it is replaced with a new one.
+
+.PP
+\fBTcl_Ungrab\fR releases a grab on the mouse pointer and keyboard, if
+there is one set on the window given by \fItkwin\fR.  Once a grab is
+released, pointer and keyboard events will start being delivered to
+other windows again.
+
+.SH KEYWORDS
+grab, window
diff --git a/unix/mkLinks b/unix/mkLinks
index eba719a..203b872 100644
--- a/unix/mkLinks
+++ b/unix/mkLinks
@@ -63,6 +63,14 @@ if test -r GetFont.3; then
     rm -f Tk_AllocFontFromObj.3
     ln GetFont.3 Tk_AllocFontFromObj.3
 fi
+if test -r Grab.3; then
+    rm -f Tk_Grab.3
+    ln Grab.3 Tk_Grab.3
+fi
+if test -r Grab.3; then
+    rm -f Tk_Ungrab.3
+    ln Grab.3 Tk_Ungrab.3
+fi
 if test -r WindowId.3; then
     rm -f Tk_Attributes.3
     ln WindowId.3 Tk_Attributes.3
-- 
cgit v0.12