It is possible to grab the
pointer, which means that all pointer events will go to
the grab window for the duration
of the grab. Normally pointer events go to the window the
pointer is inside. You should grab the pointer, for
example, if the user is using click-and-drag selection to
select a rectangular area. If they click and then
inadvertently drag the pointer outside the window, you
should continue to track the pointer's location and
change the selection accordingly. The grab also ensures
that pointer events won't be sent to other applications.
To grab the pointer, call
gdk_pointer_grab(), shown in Figure 8. The first
argument to this function is the grab window; this window
will receive events during the grab. The next argument
should be TRUE or FALSE; it specifies whether
events will go only to the grab window, or to its child
windows as well. The
confine_to argument specifies a window to confine
the pointer to. The user will not be able to move the
pointer outside this window. You can specify a different
cursor for the duration
of the grab; see the next section for details on creating
a cursor. If you don't want to change the cursor, give
NULL as the cursor argument. (Side note: it is
safe to destroy the cursor immediately after calling gdk_pointer_grab() because it is a
server-side resource and X will not deallocate it until
the grab is over.)
The final argument, time,
specifies when the grab should take effect, in server
time. This is intended to resolve conflicts if two
clients try to grab the pointer simultaneously; the time
must be after the last grab time, and it must not be in
the future. Usually, you will want to use the time field from the event
you're processing, or the
GDK_CURRENT_TIME macro.
GDK_CURRENT_TIME is a magic constant that tells the
X server to substitute the current time.
gdk_pointer_grab() returns
TRUE if it succeeds. It
is possible for it to fail if the grab window or confine_to window is hidden,
another client has the grab already, or any of the
arguments are invalid. Regrettably few applications check
this return value, which is a bug (granted, a
difficult-to-trigger one).
To ungrab the pointer, call
gdk_pointer_ungrab(); the
time argument is identical to the one in gdk_pointer_grab(). You can find
out if the pointer is grabbed using
gdk_pointer_is_grabbed(). You
must ungrab the pointer when you're finished with it,
because the user will be unable to use other applications
while the pointer is grabbed.
Note that the GDK-level concept of grabbing the pointer
is distinct from the GTK+-level grab concept. A GTK+ grab
redirects certain events to a grabbing widget, creating a "modal" widget such as
a dialog (see the section
called Grabs in the chapter called GTK+
Basics). GTK+'s grab only affects the current
application; only events that occur on one of the current
application's widgets are redirected. The scope of a GDK
grab is wider, encompassing the entire X server, not just
your application.
