The Mouse Pointer

Pointer Location

You can query the pointer's location with gdk_window_get_pointer() (Figure 7). This function requests the X and Y coordinates of the pointer relative to the window passed as its first argument. It also requests the currently active modifiers (including modifier keys and buttons; this field is identical to the state field in several events, such as button events). If NULL is passed for the x, y, or state arguments, that argument will be ignored.

#include <gdk/gdk.h>

Grabbing the Pointer

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.

#include <gdk/gdk.h>

Changing the Cursor

You can change the cursor shape at any time; cursor shapes are set on a window-by-window basis with gdk_window_set_cursor() (Figure 9). By default, windows use their parent's cursor; you can restore the default cursor by setting a window's cursor to NULL.

Two ways are provided to create a cursor. The simplest way is to choose a cursor from the cursor font that comes with X. The cursor font contains cursors instead of characters; you can view it with the command xfd -fn cursor. You can also browse the available cursors using the testgtk program that comes with GTK+. Each cursor shape has a constant defined in gdk/gdkcursors.h. gdk_cursor_new() accepts one of these constants as its only argument:

  GdkCursor* cursor;
  cursor = gdk_cursor_new(GDK_CLOCK);
  gdk_window_set_cursor(window, cursor);
  gdk_cursor_destroy(cursor);

Notice that you can destroy the cursor as soon as you attach it to a window; GdkCursor is a client-side handle for a server-side resource, and X will keep the server-side resource around as long as it's in use.

If none of the cursors in the cursor font are appropriate, you can create a custom cursor from a bitmap. Two bitmaps, actually: the source pixmap, and the mask. Since these are bitmaps, every pixel is either on or off (0 or 1). If a pixel is 0 in the mask, that pixel will be transparent. If a pixel is 1 in both pixmaps, it will be displayed in the fg (foreground) color passed to gdk_cursor_new_from_pixmap(). If a pixel is 1 in the mask but 0 in the source pixmap, it will be displayed in the bg (background) color. The source and mask pixmaps must be the same size, and they must have a depth of one.

The foreground and background colors should be contrasting, so the cursor will be visible against any background. Most cursors are drawn in the foreground color and outlined in the background color. (To see this, move an X cursor over a dark background; you will notice a white outline around its edges.) To achieve this, mask should be slightly larger than source, but the same shape.

The final two arguments to gdk_cursor_new_from_pixmap() are the coordinates of the cursor's hot spot. This is the point drawn at the mouse pointer's location---the tip of an arrow cursor, or the center of a crosshair cursor. gdk_cursor_new_from_pixmap() will fail if the hot spot is not within the bitmap.

#include <gdk/gdk.h>