This document is a Mac OS X manual page. Manual pages are a command-line technology for providing documentation. You can view these manual pages locally using the man(1) command. These manual pages come from many different sources, and thus, have a variety of writing styles.

For more information about the manual page format, see the manual page for manpages(5).

Tk_Grab(3)                                  Tk Library Procedures                                 Tk_Grab(3)



____________________________________________________________________________________________________________

NAME
       Tk_Grab, Tk_Ungrab - manipulate grab state in an application

SYNOPSIS
       #include <tk.h>

       int
       Tk_Grab(interp, tkwin, grabGlobal)

       void
       Tk_Ungrab(tkwin)


ARGUMENTS
       Tcl_Interp   *interp            (in)      Interpreter to use for error reporting

       Tk_Window    tkwin              (in)      Window  on  whose  behalf  the  pointer is to be grabbed or
                                                 released

       int          grabGlobal         (in)      Boolean indicating whether the grab is global  or  applica-tion application
                                                 tion local
____________________________________________________________________________________________________________


DESCRIPTION
       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  win-dow window
       dow and its descendants.  Mouse and keyboard events for windows outside the tree rooted at tkwin will
       be redirected to tkwin.  If the grab is global, then all mouse and keyboard events for  windows  out-side outside
       side  the  tree rooted at tkwin (even those intended for windows in other applications) will be redi-rected redirected
       rected to tkwin.  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 tkwin) will be redirected.


       Tk_Grab  sets  a grab on a particular window.  Tkwin specifies the window on whose behalf the pointer
       is to be grabbed.  GrabGlobal indicates whether the grab should be global or application local; if it
       is  non-zero,  it  means  the  grab  should be global.  Normally, Tk_Grab returns TCL_OK; if an error
       occurs and the grab cannot be set, TCL_ERROR is returned and an error message  is  left  if  interp's
       result.   Once  this  call  completes  successfully,  no window outside the tree rooted at tkwin 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.


       Tcl_Ungrab releases a grab on the mouse pointer and keyboard, if there is one set on the window given
       by tkwin.  Once a grab is released, pointer and keyboard events will start being delivered  to  other
       windows again.


KEYWORDS
       grab, window



Tk                                                                                                Tk_Grab(3)