tk/doc/Grab.3

   1 '\"
   2 '\" Copyright (c) 1998-2000 by Scriptics Corporation.
   3 '\" All rights reserved.
   4 '\"
   5 '\" RCS: @(#) $Id$
   6 '\"
   7 .so man.macros
   8 .TH Tk_Grab 3 "" Tk "Tk Library Procedures"
   9 .BS
  10 .SH NAME
  11 Tk_Grab, Tk_Ungrab \- manipulate grab state in an application
  12 .SH SYNOPSIS
  13 .nf
  14 \fB#include <tk.h>\fR
  15 .sp
  16 int
  17 \fBTk_Grab\fR(\fIinterp, tkwin, grabGlobal\fR)
  18 .sp
  19 void
  20 \fBTk_Ungrab\fR(\fItkwin\fR)
  21
  22 .SH ARGUMENTS
  23 .AP Tcl_Interp *interp in
  24 Interpreter to use for error reporting
  25 .AP Tk_Window tkwin in
  26 Window on whose behalf the pointer is to be grabbed or released
  27 .AP int grabGlobal in
  28 Boolean indicating whether the grab is global or application local
  29 .BE
  30
  31 .SH DESCRIPTION
  32 .PP
  33 These functions are used to set or release a global or
  34 application local grab.  When a grab is set on a particular window
  35 in a Tk application, mouse and keyboard events can only be received by
  36 that window and its descendants.  Mouse and keyboard events for
  37 windows outside the tree rooted at \fItkwin\fR will be redirected to
  38 \fItkwin\fR.  If the grab is global, then all mouse and keyboard
  39 events for windows outside the tree rooted at \fItkwin\fR (even those
  40 intended for windows in other applications) will be redirected to
  41 \fItkwin\fR.  If the grab is application local, only mouse and
  42 keyboard events intended for a windows within the same application
  43 (but outside the tree rooted at \fItkwin\fR) will be redirected.
  44
  45 .PP
  46 \fBTk_Grab\fR sets a grab on a particular window.  \fITkwin\fR
  47 specifies the window on whose behalf the pointer is to be grabbed.
  48 \fIGrabGlobal\fR indicates whether the grab should be global or
  49 application local; if it is non-zero, it means the grab should be
  50 global.  Normally, \fBTk_Grab\fR returns TCL_OK; if an error occurs
  51 and the grab cannot be set, TCL_ERROR is returned and an error message
  52 is left if \fIinterp\fR's result.  Once this call completes
  53 successfully, no window outside the tree rooted at \fItkwin\fR will
  54 receive pointer- or keyboard-related events until the next call to
  55 Tk_Ungrab.  If a previous grab was in effect within the application,
  56 then it is replaced with a new one.
  57
  58 .PP
  59 \fBTcl_Ungrab\fR releases a grab on the mouse pointer and keyboard, if
  60 there is one set on the window given by \fItkwin\fR.  Once a grab is
  61 released, pointer and keyboard events will start being delivered to
  62 other windows again.
  63
  64 .SH KEYWORDS
  65 grab, window