Re: How and when to use GdkWindow masks?

[David Nečas <yeti physics muni cz>]

On Sun, Jan 17, 2010 at 03:34:26AM -0800, Ken Resander wrote:
> The manual for GtkWidget signals usually mentions that an event mask should be enabled, for example for motion-notify-event: 'to receive this signal, the GdkWindow associated to the widget needs to enable the GDK_POINTER_MOTION_MASK mask'.
> 
> The quoted part above is unclear. It does not say how GdkWindow should set the mask for a widget.

This part is absolutely clear: the mask must be set to recieve the events.

It can be set by the widget itself.  It can be set by the widget user.
It can be set by little green men in flying saucers...  Since you cannot
be sure what the other involved parties set, always add the events *you*
need to receive.

The unclear part can be finding the right thing to apply the mask to.

> Is it by the user calling:?
>
> I: 
>  GdkWindow * w = gtk_widget_get_parent_window ( somegtkwidget );
>  gdk_window_set_events ( w, event_mask);

Generally, no.  First, using gdk_window_set_events() is seldom right
because something else may need events you did not set and the this
something else will break.  Use gtk_widget_add_events() or obtain the
current mask first.  Second, setting the mask of the *parent* GdkWindow
is wrong (even though they can be the same).

gdk_window_set_events() is normally used only in widget implementation.

> II:
>  gtk_widget_set_events (somegtkwidget, eventmask);

See above.

>  gtk_widget_add_events (somegtkwidget, eventmask);

This is what you normally use.  If GTK_WIDGET_NO_WINDOW(window) is true,
put the widget to an event box and use its events instead.  This is the
safe way.

> Are set/add events in II convenience functions that call gtk_widget_get_parent_window and gdk_window_set_events?   

No.  Neither calls gtk_widget_get_parent_window() and
gtk_widget_set_events() does not even call gdk_window_set_events()
because it just notes what events to request when the widget will be
realized (that's why it does not work on already realized widgets).

> I have only used gtk_widget_add_events so far and observed that calling it or not calling it made no difference for basic widgets such as checkbox for the masks:
> 
>  GDK_FOCUS_CHANGE_MASK
>  GDK_ENTER_NOTIFY_MASK
>  GDK_LEAVE_NOTIFY_MASK
>  GDK_BUTTON_PRESS_MASK
>  GDK_BUTTON_RELEASE_MASK
>  GDK_KEY_PRESS_MASK
>  GDK_KEY_RELEASE_MASK

A checkbutton quite likely already receives all these becaue it needs
them to operate.  But if you need them you should add them anyway.

Yeti