About dialog API

[Owen Taylor <otaylor redhat com>]

What is currently on:

 http://bugzilla.gnome.org/show_bug.cgi?id=109435

===
GtkWidget *gtk_about_dialog_new      (void);

void       gtk_about_dialog_show     (GtkAboutDialog *about,
				      GtkWindow    *parent,
				      const gchar  *name,
				      const gchar  *version,
				      const gchar  *copyright,
				      const gchar  *comments,
				      const gchar **authors,
				      const gchar **documenters,
				      const gchar  *translator_credits,
				      GdkPixbuf    *logo_pixbuf);
===

The about argument to _show() is mandatory. 

I think this is shooting toward Havoc's comment on the bug:

> Owen suggests having the new() function take no arguments
> and the resulting dialog doesn't destroy itself on response signal, 
> but then have a convenience function:
> 
>  void gtk_about_show (GtkWindow *parent, ... all those args ...)
> 
> that would manage an about dialog associated with the given parent 
> window (one about dialog per window, rather than a global dialog 
> for the whole app).

But doesn't seem to be quite what I was discussing with Havoc -
what I was discussing was more along the lines of:


GtkWidget *gtk_about_dialog_new      (void);
void       gtk_about_dialog_set_name (GtkAboutDialog *dialog,
                                      const gchar    *credits);
void       gtk_about_dialog_set_version (GtkAboutDialog dialog,
                                         const gchar   *version);
[...]
void       gtk_about_dialog_show     (GtkWindow    *parent,
				      const gchar  *name,
				      const gchar  *version,
				      const gchar  *copyright,
				      const gchar  *comments,
				      const gchar **authors,
				      const gchar **documenters,
				      const gchar  *translator_credits,
				      GdkPixbuf    *logo_pixbuf);

Where gtk_about_dialog_show () would look like:

 if (parent)
   dialog = g_object_get_data (parent, "gtk-about-dialog");

 if (!dialog)
   {
     /* Create the dialog according to the arguments */
   }

  gtk_window_present (dialog);


I'm a bit concerned about the number of arguments to 
gtk_about_dialog_show():

 A) It's just too many to remember
 B) If we need 9, I'd worry that tomorrow we'll want 10;
    a function with 9 arguments is a non-extensible API.

One possibility would be to simply have:

 void gtk_about_dialog_show (GtkWIndow *parent, ...);

And pass the varargs to g_object_new_valist(). 

So, 

 gtk_about_dialog_show (parent, 
                        "name", PACKAGE,
                        "version", VERSION,
                        [..]);

Other solutions I can think of are:

 about = gtk_about_dialog_get (parent);
 gtk_about_dialog_set_name (about, "PACKAGE");
 [...]
 gtk_about_dialog_show (about);


 gtk_about_dialog_show (&about_info,
                        GTK_ABOUT_DIALOG_NAME |
                        GTK_ABOUT_DIALOG_VERSION |
                        [...]);

But I think I like the varargs method best. My main other
API comment is that I don't think using 
g_param_spec_value_array() for the "array" properties
is a good idea. It doesn't work for GUI builders, since
a GUI builder has no idea what type the array elements
need to be. And it isn't convenient in C either.

What I might suggest is simply using a newline separated
string:

 "author", 
 "Anders Carlsson <andersca gnu org>\n"
 "Matthias Clasen <maclas gmx de>\n"

Works well from C, works well from language bindings, works well 
from a GUI builder.

What it doesn't allow is a lot of flexibility for adding
extra fields of contributor information, but I think string
heuristic string parsing should be OK for that.

I had various minor implementation comments, but I think I'll hold
off on those until we get the API basically settled.

Regards,
                                         Owen