Re: volunteer needed: event return values

[Owen Taylor <otaylor redhat com>]

srlytle_list yahoo com writes:

> i like this improvement (the 1.2 behavior was annoying), so i
> will do what i can. so far i:
> 
> used gtk-reference to find all signals with return values
> grep'd to find all occurrences of those signals in the .c's
> 
> here are the signals that i came up with.

[...]
> 
> i'm just going thru the .c's in alphabetic order. if anyone wants the
> list of "this file contains these non-void-returning signals",
> let me know.

Wolfgang Sourdeau <wolfgang contre com> also expressed an interest
in working on this, so you can negotiate between the two 

> a large percentage of the functions are expose_event handlers,
> so an explanation of how that signal should work would probably
> do a lot of good up front.

Actually, we need to note here that expose events are really
different than a lot of other events. For events like mouse
button presses and key presses, it really makes sense for
the event to only be handled by one entity. A mouse press
should trigger one action, not several.

But, that's not the same for an expose event, many handlers
can handle an expose event, each drawing part of the area,
with the drawing of the last expose handler being the
final authority.

Of the signals you listed, 

> GtkWidget::button-press-event
> GtkWidget::button-release-event
> GtkWidget::key-press-event
> GtkWidget::key-release-event
> GtkWidget::drag-motion
> GtkWidget::drag-drop
> GtkWidget::delete-event
> GtkWidget::selection-request-event
> GtkWidget::selection-notify-event
> GtkWidget::client-event

Are basically actions, and should typically have a single
handler. [ Though selection-request and selection-notify
are horribly internal, and never should have been signals ]

These are the signals you should concentrate on.

> GtkWidget::map-event
> GtkWidget::unmap-event
> GtkWidget::enter-notify-event
> GtkWidget::leave-notify-event
> GtkWidget::focus-in-event
> GtkWidget::focus-out-event
> GtkWidget::motion-notify-event
> GtkWidget::visibility-notify-event
> GtkWidget::destroy-event
> GtkWidget::configure-event
> GtkWidget::property-notify-event
> GtkWidget::selection-clear-event
> GtkWidget::proximity-in-event
> GtkWidget::proximity-out-event

These however, are mostly notifications of state changes. There is no
reason why multiple entities shouldn't get notified of state changes.
Thus, there handlers should typically return FALSE, regardless
if they take note of the event.

(There is even some question whether these signals should
have the TRUE-stops-emit behavior, though it may be less
confusing if they do.)

It should be noted that most of these are _not_ propagated
to parent widgets. (Look at gtkmain.c:gtk_main_do_event)

> GtkWidget::expose-event
> GtkWidget::no-expose-event

Both of these are notification, and it is fine if they have multiple
handlers, but they aren't really notification of changes as are
the events in the above list. The rest are varied:

> GtkContainer::focus

A quite different case than event signals, but probably should have
the TRUE-return-stops-emit-behavior as well. All return values from
::focus should currently be OK.

> GtkTipsQuery::widget-selected

Again, probably should have TRUE-stops-emit, but quite different
from event handlers, and again, should need no fixing.

> GtkWidget::event

Needs TRUE-stops-emit, but whether the handlers should return
TRUE should depend on the type of the event.

> for a container, should it return TRUE if it drew a portion of the
> expose event, or does it need to make sure that it has redrawn
> the entire event->area. eg, this is what i think
> 
> static gint
> gtk_bin_expose (GtkWidget      *widget,
>                 GdkEventExpose *event)
> {
>   GtkBin *bin;
>   GdkEventExpose child_event;
> 
>   g_return_val_if_fail (widget != NULL, FALSE);
>   g_return_val_if_fail (GTK_IS_BIN (widget), FALSE);
>   g_return_val_if_fail (event != NULL, FALSE);
> 
>   if (GTK_WIDGET_DRAWABLE (widget))
>     {
>       bin = GTK_BIN (widget);
> 
>       child_event = *event;
>       if (bin->child && GTK_WIDGET_DRAWABLE (bin->child) &&
>           GTK_WIDGET_NO_WINDOW (bin->child) &&
>           gtk_widget_intersect (bin->child, &event->area, &child_event.area)) 
> -       gtk_widget_event (bin->child, (GdkEvent*) &child_event);
> +       return gtk_widget_event (bin->child, (GdkEvent*) &child_event);
>     }
>   return FALSE;
> }
> 
> it should be (ie, return TRUE, unless you do nothing), but i am less
> certain for gtk_box_expose. anyone have any recommendations, or is my plan ok.

Actually, my feeling is that expose event handlers should just
categorically return FALSE.

> for things like key_press/etc, it seems a lot simpler.

These are the things I'm worried about. 

I'm sure I've muddied the water a lot with this mail - made
this a less clear task. Don't hestitate to ask more questions
if you need help figuring things out.

Regards,
                                        Owen