| 1 |
578 |
markom |
'\"
|
| 2 |
|
|
'\" Copyright (c) 1992 The Regents of the University of California.
|
| 3 |
|
|
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
|
| 4 |
|
|
'\"
|
| 5 |
|
|
'\" See the file "license.terms" for information on usage and redistribution
|
| 6 |
|
|
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
| 7 |
|
|
'\"
|
| 8 |
|
|
'\" RCS: @(#) $Id: grab.n,v 1.1.1.1 2002-01-16 10:25:49 markom Exp $
|
| 9 |
|
|
'\"
|
| 10 |
|
|
.so man.macros
|
| 11 |
|
|
.TH grab n "" Tk "Tk Built-In Commands"
|
| 12 |
|
|
.BS
|
| 13 |
|
|
'\" Note: do not modify the .SH NAME line immediately below!
|
| 14 |
|
|
.SH NAME
|
| 15 |
|
|
grab \- Confine pointer and keyboard events to a window sub-tree
|
| 16 |
|
|
.SH SYNOPSIS
|
| 17 |
|
|
\fBgrab \fR?\fB\-global\fR? \fIwindow\fR
|
| 18 |
|
|
.sp
|
| 19 |
|
|
\fBgrab \fIoption \fR?\fIarg arg \fR...?
|
| 20 |
|
|
.BE
|
| 21 |
|
|
|
| 22 |
|
|
.SH DESCRIPTION
|
| 23 |
|
|
.PP
|
| 24 |
|
|
This command implements simple pointer and keyboard grabs for Tk.
|
| 25 |
|
|
Tk's grabs are different than the grabs
|
| 26 |
|
|
described in the Xlib documentation.
|
| 27 |
|
|
When a grab is set for a particular window, Tk restricts all pointer
|
| 28 |
|
|
events to the grab window and its descendants in Tk's window hierarchy.
|
| 29 |
|
|
Whenever the pointer is within the grab window's subtree, the pointer
|
| 30 |
|
|
will behave exactly the same as if there had been no grab at all
|
| 31 |
|
|
and all events will be reported in the normal fashion.
|
| 32 |
|
|
When the pointer is outside \fIwindow\fR's tree, button presses and
|
| 33 |
|
|
releases and
|
| 34 |
|
|
mouse motion events are reported to \fIwindow\fR, and window entry
|
| 35 |
|
|
and window exit events are ignored.
|
| 36 |
|
|
The grab subtree ``owns'' the pointer:
|
| 37 |
|
|
windows outside the grab subtree will be visible on the screen
|
| 38 |
|
|
but they will be insensitive until the grab is released.
|
| 39 |
|
|
The tree of windows underneath the grab window can include top-level
|
| 40 |
|
|
windows, in which case all of those top-level windows
|
| 41 |
|
|
and their descendants will continue to receive mouse events
|
| 42 |
|
|
during the grab.
|
| 43 |
|
|
.PP
|
| 44 |
|
|
Two forms of grabs are possible: local and global.
|
| 45 |
|
|
A local grab affects only the grabbing application: events will
|
| 46 |
|
|
be reported to other applications as if the grab had never occurred.
|
| 47 |
|
|
Grabs are local by default.
|
| 48 |
|
|
A global grab locks out all applications on the screen,
|
| 49 |
|
|
so that only the given subtree of the grabbing application will be
|
| 50 |
|
|
sensitive to pointer events (mouse button presses, mouse button releases,
|
| 51 |
|
|
pointer motions, window entries, and window exits).
|
| 52 |
|
|
During global grabs the window manager will not receive pointer
|
| 53 |
|
|
events either.
|
| 54 |
|
|
.PP
|
| 55 |
|
|
During local grabs, keyboard events (key presses and key releases)
|
| 56 |
|
|
are delivered as usual: the window
|
| 57 |
|
|
manager controls which application receives keyboard events, and
|
| 58 |
|
|
if they are sent to any window in the grabbing application then they are
|
| 59 |
|
|
redirected to the focus window.
|
| 60 |
|
|
During a global grab Tk grabs the keyboard so that all keyboard events
|
| 61 |
|
|
are always sent to the grabbing application.
|
| 62 |
|
|
The \fBfocus\fR command is still used to determine which window in the
|
| 63 |
|
|
application receives the keyboard events.
|
| 64 |
|
|
The keyboard grab is released when the grab is released.
|
| 65 |
|
|
.PP
|
| 66 |
|
|
Grabs apply to particular displays. If an application has windows
|
| 67 |
|
|
on multiple displays then it can establish a separate grab on each
|
| 68 |
|
|
display.
|
| 69 |
|
|
The grab on a particular display affects only the windows on
|
| 70 |
|
|
that display.
|
| 71 |
|
|
It is possible for different applications on a single display to have
|
| 72 |
|
|
simultaneous local grabs, but only one application can have a global
|
| 73 |
|
|
grab on a given display at once.
|
| 74 |
|
|
.PP
|
| 75 |
|
|
The \fBgrab\fR command can take any of the following forms:
|
| 76 |
|
|
.TP
|
| 77 |
|
|
\fBgrab \fR?\fB\-global\fR? \fIwindow\fR
|
| 78 |
|
|
Same as \fBgrab set\fR, described below.
|
| 79 |
|
|
.TP
|
| 80 |
|
|
\fBgrab current \fR?\fIwindow\fR?
|
| 81 |
|
|
If \fIwindow\fR is specified, returns the name of the current grab
|
| 82 |
|
|
window in this application for \fIwindow\fR's display, or an empty
|
| 83 |
|
|
string if there is no such window.
|
| 84 |
|
|
If \fIwindow\fR is omitted, the command returns a list whose elements
|
| 85 |
|
|
are all of the windows grabbed by this application for all displays,
|
| 86 |
|
|
or an empty string if the application has no grabs.
|
| 87 |
|
|
.TP
|
| 88 |
|
|
\fBgrab release \fIwindow\fR
|
| 89 |
|
|
Releases the grab on \fIwindow\fR if there is one, otherwise does
|
| 90 |
|
|
nothing. Returns an empty string.
|
| 91 |
|
|
.TP
|
| 92 |
|
|
\fBgrab set \fR?\fB\-global\fR? \fIwindow\fR
|
| 93 |
|
|
Sets a grab on \fIwindow\fR. If \fB\-global\fR is specified then the
|
| 94 |
|
|
grab is global, otherwise it is local.
|
| 95 |
|
|
If a grab was already in effect for this application on
|
| 96 |
|
|
\fIwindow\fR's display then it is automatically released.
|
| 97 |
|
|
If there is already a grab on \fIwindow\fR and it has the same
|
| 98 |
|
|
global/local form as the requested grab, then the command
|
| 99 |
|
|
does nothing. Returns an empty string.
|
| 100 |
|
|
.TP
|
| 101 |
|
|
\fBgrab status \fIwindow\fR
|
| 102 |
|
|
Returns \fBnone\fR if no grab is currently set on \fIwindow\fR,
|
| 103 |
|
|
\fBlocal\fR if a local grab is set on \fIwindow\fR, and
|
| 104 |
|
|
\fBglobal\fR if a global grab is set.
|
| 105 |
|
|
|
| 106 |
|
|
.SH BUGS
|
| 107 |
|
|
.PP
|
| 108 |
|
|
It took an incredibly complex and gross implementation to produce
|
| 109 |
|
|
the simple grab effect described above.
|
| 110 |
|
|
Given the current implementation, it isn't safe for applications
|
| 111 |
|
|
to use the Xlib grab facilities at all except through the Tk grab
|
| 112 |
|
|
procedures.
|
| 113 |
|
|
If applications try to manipulate X's grab mechanisms directly,
|
| 114 |
|
|
things will probably break.
|
| 115 |
|
|
.PP
|
| 116 |
|
|
If a single process is managing several different Tk applications,
|
| 117 |
|
|
only one of those applications can have a local grab for a given
|
| 118 |
|
|
display at any given time. If the applications are in different
|
| 119 |
|
|
processes, this restriction doesn't exist.
|
| 120 |
|
|
|
| 121 |
|
|
.SH KEYWORDS
|
| 122 |
|
|
grab, keyboard events, pointer events, window
|
