GDK_POINTER_MOTION_HINT_MASK has no effect

["Stewart Weiss" <stewart weiss acm org>]

I have been playing around with the motion_notify_event callback in the
Scribble example from the tutorial, and I have discovered that none of
what the documentation states is correct.  I modified the handler to
generate
output on the standard outout device as follows:

gboolean motion_notify_event( GtkWidget      *widget,
                              GdkEventMotion *event,
                              gpointer       *mydata )
{
    int x, y;
    GdkModifierType state;

    if (event->is_hint) {
        gdk_window_get_pointer (event->window, &x, &y, &state);
        g_print ( "is hint at %d, %d\n", x, y );
    }
    else {
        x = event->x;
        y = event->y;
        state = event->state;
        g_print ( "is not hint at %d, %d\n", x, y );
    }

I have set events on the widget using all 8 possible combinations of the
three
masks:
   GDK_POINTER_MOTION_MASK
   GDK_BUTTON_MOTION_MASK
   GDK_POINTER_MOTION_HINT_MASK

What I have found is that the event->is_hint IS NEVER true, regardless of
the
masks I set on the widget.  What IS TRUE is that when the
GDK_BUTTON_MOTION_MASK
is set on the widget, with or without the GDK_POINTER_MOTION_HINT_MASK, the
only
signals emitted by the widget are when the mouse button is down while the
pointer
is in motion. This is contrary to what is written in the GDK Reference
Manual.

Because the "is hint at ..." is never displayed, it also implies that
gdk_window_get_pointer() is never called.

I was trying to implement a straight-line tool and I had hoped that I could
detect
the starting and ending points using the fact that the is_hint member would
be true
only when the window was entered, or a button press or release event (as it
says in
the tutorial.)   I figured I could get the point when the mouse button was
first
pressed and then wait until the mouse button was released to write the line
into
my pixmap.

Does anyone know what the real semantics are, and when is_hint is true?

Stewart