Re: Signal handlers: parameter names

[John Margaglione <jmargaglione yahoo com>]

> for GSignal we decided against that, mostly because
> a) it requires a significant amount of changes to the current set
>    of signals provided by widgets

I am recommending an additional function call that will be optional. 
If the component writer doesn't want to go to the trouble, no problem. 
But at least for the core classes we can have support.

And how hard is it to include a list of strings with each call to
g_signal_new anyway?  No additional function calls are needed, unlike
the GParam code (and after modifying a couple dozen files for GParam, I
can't imagine how much harder it could get :) ).  

> b) a GUI builder rarely needs to go through the fullest extend of
>    offering a "invoke this signal" dialog

I'm not talking about invoking signals, I'm talking about creating a
dialog box to connect signals.  In Glade right now you can select a
signal by choosing from a list of available signals from a listbox. 
When you choose one of the signals and generate the source code, Glade
has to do a lookup on the names of the parameters to the signal.  These
have to be stored as static arrays in the Glade source code.  If a new
signal is added, or the names of the parameters are changed, Glade has
to be updated.  Using my suggestion there is no rework of Glade
necessary.

> c) there's no functional rquirement to perform matches on signal
>    parameter names (as opposed to object properties, where this
>    is obviously required)

Again, I don't want to do lookups based on the names of the parameters,
I just want to know what they are, RUNTIME.

> as i understand you, you just have the problem to provide "sane"
> parameter names for signal. just for that, requirering the
> signal creater to supply names for all parameters is imho a
> bad tradeoff, let alone the uglyness of implementation, e.g.
> signal_new (..., GTK_TYPE_NONE, 2,
>             "widget", GTK_TYPE_WIDGET,
>             "event", GTK_TYPE_EVENT),
> because:
> 1) signal parameter names are usually not as expressive as e.g.
> property
>    names are, in fact, for the most part they are somewhat similarly
> named
>    to the type name of the signal parameter   
> 2) requirering signal creators to name every arg, because a small
> portion
>    of signal parameter names can not be auto-generated for doc or
> builder
>    tools imposes a disproportional burden
> 3) we'll have to provide old compat API for signal creation either
> way,
>    so you will still need code to handle unnamed signal parameters

Take for example "add_accelerator" from GtkWidget.  Here's the
prototype of the callback:

gint (*add_accelerator) (
GtkWidget      *widget,
guint           accel_signal_id,
GtkAccelGroup  *accel_group,
guint           accel_key,
GdkModifierType accel_mods,
GtkAccelFlags   accel_flags )

If the user connects this signal to a function they call on_add_accel,
here is what a "generic" function prototype would look like:  

gint on_add_accel (widget, guint_1, accel_group, guint_2,
modifier_type, accel_flags).

Now what is the user supposed to think about guint_1 and guint_2?  They
now have to look up the documentation for add_accel.  If they had seen
accel_signal_id and accel_key, they probably wouldn't have to look
anything up.  Perhaps the first time.  If anything they make good
reminders, especially if the callback prototype has two gbooleans in a
row, or something similar.

> 
> for those reasons, i think it'd be better to code up a
> GList* g_signal_list_param_names (const GSignalQuery *query);
> function that does clever generic generation of signal parameter
> names,
> based on types, that yields acceptable results for 90% of signals
> out there.

We already do that. That one's not so hard.

> for a handfull of signals that will not be good enough, say:
>   void   (*extend_selection)    (GtkCList       *clist,
>                                  GtkScrollType   scroll_type,
>                                  gfloat          position,
>                                  gboolean      
auto_start_selection);
> but for that, we could ship a file with the gtk distro that comes
> with
> signal parameter name lists for those signals where auto-generation
> yields inferior results. so ultimately, g_signal_list_param_names()
> should
> also be able to parse signal description files, containing, say:

Now you have two places to document your signal instead of one.  Plus,
that doesn't help with custom components, such as gnome-db.  We need a
way for custom component writers to create widgets that integrate with
builders out of the box.   

If the signal is not ambiguous, for example if all of the parameters
are GtkTypes, then the author can just leave the call as-is.  But if
there is any change of ambiguity, they use the alternate call syntax.

> GtkCList::extend_selection (clist, scroll_type, position,
> auto_start_selection);
> 
> so yes, that'll be mostly what you have already, except that, if we
> actually implement such a function in GLib and leave signal creation
> as simple as it currently is, there's no additional burden for widget
> implementors, and GUI builders as well as gtk-doc (and maybe LB code)
> don't need to come with their own magic to figure signal parameter
> names.
> all it'd take is someone implementing g_signal_list_param_names() and
> someone adding those signals to a text file where auto-generation
> produces
> bad results.

John

__________________________________________________
Do You Yahoo!?
Get email at your own domain with Yahoo! Mail. 
http://personal.mail.yahoo.com/