Re: About dialog API

[Matthias Clasen <maclas gmx de>]

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

Yes, I wrote that in response to Havoc comment, which maybe was a bit too
terse for me
to get what you're after.

> 
> 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);
> 

This makes sense.

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

Maybe we should add typed arrays, so that we can make it a string array.
Isn't there already a bug about adding typed arrays ?

> 
> 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 have looked around a bit for other about dialogs, and the KDE api for that
associates an optional URL (homepage or something), email address and a
comment
(area of work or something) with contributors mentioned in the about dialog.
I guess 
thats about anything one would ever want to add. So if we can come up with a
string format
which allows to 

a) get this information in
b) is easily parseable
c) lets us conveniently ignore some parts (e.g. the URL, since we can't
depend on gnome_url_show)

I have nothing against it.

One proposal would be to say URLs are not needed and  use something like

"name1 <email1>\n\tcomment1\n"
"name2 <email2>\n\tcomment2\n"
"name3 <email3>\n"
"name4\n\tcomment4\n"

which has the advantage that it can be directly dumped into the label and
yield reasonable results.


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

Good. The main API questions I still see are:

a) do we want to allow "custom tabs", e.g. "Artwork" ? I have made some
comments about that in the bug.
b) the setters/getters question 
c) do we need to have more app information beyond the generic comment ?
Examples which have been
mentioned are bug reporting address, web site.  Of course, this partially
depends on the implementation question whether we can do something intelligent
with email addresses and urls (show them as links) without gnome_url_show().

Matthias

-- 
+++ GMX - Mail, Messaging & more  http://www.gmx.net +++
Bitte lächeln! Fotogalerie online mit GMX ohne eigene Homepage!