Re: GTK Signal handlers return TRUE or FALSE?

[Owen Taylor <otaylor gtk org>]

"Scott D. Heavner" <sdh@po.cwru.edu> writes:
 
> The way I read the gtk tutorial, a signal handler returning TRUE
> says "I handled it, don't bother with the default handler".
> 
> In particular, I'm looking at the "select_row" signal in a gtkclist.
> If I return true, I would expect that the default handler wouldn't
> get executed and thus there would be no selection made. (Maybe hoping
> is a better word than expecting).
> 
> In general, are widgets being designed to act differently when
> a signal handler returns true vs. false.  What is supposed to be
> done before an overriding signal is invoked and what happens after?
> 
> As another example, what should happen if I intercept a button click
> event?  Should gtk go ahead and draw the button already clicked?  Am
> I then responsible for drawing it unclicked?  Or do I just assume
> that my callback/handler is just a courtesy and gtk doesn't give a
> flying f*ck what I return to it.

Here's a slighly more detailed view of what happens for event
signals:

First, note that the return from a signal emission is the 
return of the _last_ handler executed. Since event signals
are all of type GTK_RUN_LAST, this will be the default handler,
unless you connect with gtk_signal_connect_after().

Signal "emission" is the process whereby GTK+ runs all handlers
for a specific object and signal.

The way an event (say GTK_BUTTON_PRESS) is handled, is:

 - Start with the widget where the event occured.
   
 - Emit the generic "event" signal. If that signal emission
   returns TRUE, stop all processing.
 - Otherwise, emit a specific, "button_press_event" signal.
   If that returns TRUE, stop all processing.
 - Otherwise, go to the widget's parent, and repeat the above
   steps.
 - Continue until some emission returns TRUE, or until 
   you get to the toplevel widget.

Some consequences:

 - Your return value will have no effect if there is a default
   handler, unless you connect with gtk_signal_connect_after().

 - To prevent the default handler from being run, you need
   to use gtk_signal_emit_stop_by_name() - the return value
   only affects whether the signal is propagated, not the
   current emission.

So, if you want to suppress all further handling, do this
at the end of your handler.

 gtk_signal_emit_stop_by_name (GTK_OBJECT (widget), 
                               "button_press_event"));
 return FALSE;

Hope this makes things a bit clearer,
                                        Owen