new convention for signals with return-values

[Tim Janik <timj gtk org>]

hello everyone,

i'm about to change the run-type for a few signal for gtk+-1.0.3 and
gtk+-1.1.0, and will try to eplain the reasonings for that here.
the affected signals are:

GtkContainer::need-resize		(returns: further resize needed?)
GtkWidget::proximity-in-event		(returns: event handled?)
GtkWidget::drop-enter-event		(returns: event handled?)
GtkWidget::drop-leave-event		(returns: event handled?)
GtkWidget::drop-data-available-event	(returns: event handled?)
GtkTipsQuery::widget-selected		(returns: stop querying?)

all of them are currently GTK_RUN_FIRST signals and return boolean values,
the planned change is to change the runtype for all of them to GTK_RUN_LAST.

why shouldn't return-value signals be of type GTK_RUN_FIRST?
   - any signal connections made to those signals, even ones made for simple
     notification purposes will overload the return value.
   - return value overloading becomes dubious with more than one handler
     connection (especially if some of them are disconnected again or use the
     newly introduced incremental-blocking feature), and should only be used
     in controlled circumstances, i.e. through _after connections.
   - return values that affect further handling of e.g. an event, so as to
     return TRUE; for event-handled? usually are used to intercept the further
     handling, but real interception is not possible because GTK_RUN_FIRST
     signals can not be stopped (e.g. thorugh gtk_signal_emit_stop).

no what does this change for existing code?
well the one signal of the above that is most likely to be already in use
is GtkTipsQuery::widget-selected.
now, if you want to be notified about a newly selected widget you simply
_connect to this signal, and the return value of your connection will be
ignored if 1) the widget introduces a default handler and 2) you don't
intercept the emission via emit_stop.
if you want to affect the return value, such as to terminate the query
process (the default is TRUE), you simply use an _after connection that
 returns false, e.g.

gtk_signal_connect_after (GTK_OBJECT (tipsquery),
                          "widget-selected",
                          GTK_SIGNAL_FUNC (gtk_false),
                          NULL);


/me is waiting for the crowd's questions now...


---
ciaoTJ