128 lines
6.3 KiB
HTML
128 lines
6.3 KiB
HTML
<HTML><HEAD><TITLE>Built-In Commands - grab manual page</TITLE></HEAD><BODY>
|
|
<DL>
|
|
<DD><A HREF="grab.htm#M2" NAME="L548">NAME</A>
|
|
<DL><DD>grab - Confine pointer and keyboard events to a window sub-tree</DL>
|
|
<DD><A HREF="grab.htm#M3" NAME="L549">SYNOPSIS</A>
|
|
<DL>
|
|
<DD><B>grab </B>?<B>-global</B>? <I>window</I>
|
|
<DD><B>grab </B><I>option </I>?<I>arg arg </I>...?
|
|
</DL>
|
|
<DD><A HREF="grab.htm#M4" NAME="L550">DESCRIPTION</A>
|
|
<DL>
|
|
<DD><A HREF="grab.htm#M5" NAME="L551"><B>grab </B>?<B>-global</B>? <I>window</I></A>
|
|
<DD><A HREF="grab.htm#M6" NAME="L552"><B>grab current </B>?<I>window</I>?</A>
|
|
<DD><A HREF="grab.htm#M7" NAME="L553"><B>grab release </B><I>window</I></A>
|
|
<DD><A HREF="grab.htm#M8" NAME="L554"><B>grab set </B>?<B>-global</B>? <I>window</I></A>
|
|
<DD><A HREF="grab.htm#M9" NAME="L555"><B>grab status </B><I>window</I></A>
|
|
</DL>
|
|
<DD><A HREF="grab.htm#M10" NAME="L556">BUGS</A>
|
|
<DD><A HREF="grab.htm#M11" NAME="L557">KEYWORDS</A>
|
|
</DL><HR>
|
|
<H3><A NAME="M2">NAME</A></H3>
|
|
grab - Confine pointer and keyboard events to a window sub-tree
|
|
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
|
<B>grab </B>?<B>-global</B>? <I>window</I><BR>
|
|
<B>grab </B><I>option </I>?<I>arg arg </I>...?<BR>
|
|
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
|
This command implements simple pointer and keyboard grabs for Tk.
|
|
Tk's grabs are different than the grabs
|
|
described in the Xlib documentation.
|
|
When a grab is set for a particular window, Tk restricts all pointer
|
|
events to the grab window and its descendants in Tk's window hierarchy.
|
|
Whenever the pointer is within the grab window's subtree, the pointer
|
|
will behave exactly the same as if there had been no grab at all
|
|
and all events will be reported in the normal fashion.
|
|
When the pointer is outside <I>window</I>'s tree, button presses and
|
|
releases and
|
|
mouse motion events are reported to <I>window</I>, and window entry
|
|
and window exit events are ignored.
|
|
The grab subtree ``owns'' the pointer:
|
|
windows outside the grab subtree will be visible on the screen
|
|
but they will be insensitive until the grab is released.
|
|
The tree of windows underneath the grab window can include top-level
|
|
windows, in which case all of those top-level windows
|
|
and their descendants will continue to receive mouse events
|
|
during the grab.
|
|
<P>
|
|
Two forms of grabs are possible: local and global.
|
|
A local grab affects only the grabbing application: events will
|
|
be reported to other applications as if the grab had never occurred.
|
|
Grabs are local by default.
|
|
A global grab locks out all applications on the screen,
|
|
so that only the given subtree of the grabbing application will be
|
|
sensitive to pointer events (mouse button presses, mouse button releases,
|
|
pointer motions, window entries, and window exits).
|
|
During global grabs the window manager will not receive pointer
|
|
events either.
|
|
<P>
|
|
During local grabs, keyboard events (key presses and key releases)
|
|
are delivered as usual: the window
|
|
manager controls which application receives keyboard events, and
|
|
if they are sent to any window in the grabbing application then they are
|
|
redirected to the focus window.
|
|
During a global grab Tk grabs the keyboard so that all keyboard events
|
|
are always sent to the grabbing application.
|
|
The <B><A HREF="../TclCmd/focus.htm">focus</A></B> command is still used to determine which window in the
|
|
application receives the keyboard events.
|
|
The keyboard grab is released when the grab is released.
|
|
<P>
|
|
Grabs apply to particular displays. If an application has windows
|
|
on multiple displays then it can establish a separate grab on each
|
|
display.
|
|
The grab on a particular display affects only the windows on
|
|
that display.
|
|
It is possible for different applications on a single display to have
|
|
simultaneous local grabs, but only one application can have a global
|
|
grab on a given display at once.
|
|
<P>
|
|
The <B>grab</B> command can take any of the following forms:
|
|
<P>
|
|
<DL>
|
|
<P><DT><A NAME="M5"><B>grab </B>?<B>-global</B>? <I>window</I></A><DD>
|
|
Same as <B>grab set</B>, described below.
|
|
<P><DT><A NAME="M6"><B>grab current </B>?<I>window</I>?</A><DD>
|
|
If <I>window</I> is specified, returns the name of the current grab
|
|
window in this application for <I>window</I>'s display, or an empty
|
|
string if there is no such window.
|
|
If <I>window</I> is omitted, the command returns a list whose elements
|
|
are all of the windows grabbed by this application for all displays,
|
|
or an empty string if the application has no grabs.
|
|
<P><DT><A NAME="M7"><B>grab release </B><I>window</I></A><DD>
|
|
Releases the grab on <I>window</I> if there is one, otherwise does
|
|
nothing. Returns an empty string.
|
|
<P><DT><A NAME="M8"><B>grab set </B>?<B>-global</B>? <I>window</I></A><DD>
|
|
Sets a grab on <I>window</I>. If <B>-global</B> is specified then the
|
|
grab is global, otherwise it is local.
|
|
If a grab was already in effect for this application on
|
|
<I>window</I>'s display then it is automatically released.
|
|
If there is already a grab on <I>window</I> and it has the same
|
|
global/local form as the requested grab, then the command
|
|
does nothing. Returns an empty string.
|
|
<P><DT><A NAME="M9"><B>grab status </B><I>window</I></A><DD>
|
|
Returns <B>none</B> if no grab is currently set on <I>window</I>,
|
|
<B>local</B> if a local grab is set on <I>window</I>, and
|
|
<B><A HREF="../TkCmd/global.htm">global</A></B> if a global grab is set.
|
|
|
|
<P></DL>
|
|
<H3><A NAME="M10">BUGS</A></H3>
|
|
It took an incredibly complex and gross implementation to produce
|
|
the simple grab effect described above.
|
|
Given the current implementation, it isn't safe for applications
|
|
to use the Xlib grab facilities at all except through the Tk grab
|
|
procedures.
|
|
If applications try to manipulate X's grab mechanisms directly,
|
|
things will probably break.
|
|
<P>
|
|
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.
|
|
|
|
<H3><A NAME="M11">KEYWORDS</A></H3>
|
|
<A href="../Keywords/G.htm#grab">grab</A>, <A href="../Keywords/K.htm#keyboard events">keyboard events</A>, <A href="../Keywords/P.htm#pointer events">pointer events</A>, <A href="../Keywords/W.htm#window">window</A>
|
|
<HR><PRE>
|
|
<A HREF="../copyright.htm">Copyright</A> © 1992 The Regents of the University of California.
|
|
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
|
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
|
</BODY></HTML>
|