Re: Signal handlers: parameter names

[Tim Janik <timj gtk org>]

On Thu, 8 Mar 2001, John Margaglione wrote:

> I was thinking about tools like glade, and specifically a tool I wrote a
> little while back called g2c, which converts glade XML files to C code. 
> One of the problems I had then was that I could get the types of all of
> the parameters to a signal, but I couldn't get the names of the
> parameters.  It seems this is still an issue, since gtk_signal_new still
> does not contain a place to name your signal's arguments.  This would be
> enormously handy for tools like glade.  Right now we have to maintain
> huge lists of signal handler names/parameters in our code, then do table
> lookups on the lists to write out the C code.  If we could dynamically
> discover the types AND names of the parameters, it would reduce the
> amount of BS code we have to write a LOT.  It would also allow GUI
> builders to handle new widget callbacks without recoding the builder.  
> 
> Here is my proposal:
> 
> guint
> gtk_signal_new_with_names (const gchar *name,
>                            GtkSignalRunType signal_flags,
>                            GtkType object_type,
>                            guint function_offset,
>                            GtkSignalMarshaller marshaller,
>                            GtkType return_val,
>                            guint n_args,
>                            gchar **arg_names,
>                            GtkType *args);
> 
> arg_names would be a null-terminated list of strings corresponding to
> the names of the arguments.
> 
> By using a new function name, we maintain code compatibility with
> existing widgets (this seems to be a big topic today, so I thought I'd
> mention it).  I could recode the core gtk+ classes to use
> gtk_signal_new_with_names in a week or two, less with others' help.  If
> this can't make it in to 1.4 I won't cry, but I'd like to see it in
> there if possible.  

ok, lemme give bit of background first on why we just use type IDs
for signal parameters even in GSignal.

at some point i prompted owen on irc to discuss with him whether to
use plain type IDs for the GSignal code like it's done for GtkSignal
in gtk+1.2 as well, or whether to use GParamSpec structures to describe
signal parameters.
i have to say that for BSE, i have a special procedure type, that's
something like a generically callable function that you also can query
the parameters off. there, i did use GParamSpec for the parameter
descriptions. it's a somewhat bigger burden for the implementor
of the procedures, but it was required because BEAST comes with
an "Invoke this procedure" dialog where you want to go the full route
of using paramspecs, since the GUI needs to know defaults and ranges
etc. as with properties.
besides that, procedures feature "preset" parameters, that is, say
you have a FooEditor view and invoke a ModifyFoo procedure on it's Foo
model with the procedure having a Foo* pointer as first argument.
here, FooEditor can supply a "preset" parameter for the procedure
invokation dialog that provides the dialog with a parameter named
"foo" pointing to the Foo* model that FooEditor is working on. so
inherently, the procedure invocation code has to make matches on
parameter names.

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
b) a GUI builder rarely needs to go through the fullest extend of
   offering a "invoke this signal" dialog
c) there's no functional rquirement to perform matches on signal
   parameter names (as opposed to object properties, where this
   is obviously required)

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

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.
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:

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
> 

---
ciaoTJ