Note: the example code has been updated from earlier proposals, so the modules marked as "done" should be re-checked when this is turned into an approved GNOME Goal.

GNOME Goal: Update about dialogs

Applications should use GtkAboutDialog to show an about dialog. Make sure you have these properties set in your about dialog object, and that their values are up to date:

• artists: Update the list, if applicable.

• authors: Make sure it's up to date. Listing all major contributors here is a good way to motivate them to contribute more. The list may be sorted alphabetically, or based on contributions.

• comments: A really short description of what your program does.

• copyright: Update the years.

• documenters: Update the list.

• license: What to do here is still uncertain, please look at the comments.

• logo: Don't use it, replace it instead by "logo-icon-name" if possible (see also GnomeGoals/AppIcon), and get rid of the pixbuf-loading stuff.

• logo-icon-name: Should be the same as your application icon name (see GnomeGoals/AppIcon), with no extension. This is preferred over the "logo" property which takes a GdkPixbuf.

• program-name: Localized name of your application. If omitted, it defaults to the name set with g_set_application_name Note that this property only exists since gtk 2.11.0; so you have to use #if GTK_CHECK_VERSION (2, 12, 0) here if the program does not require gtk 2.11, and set the name property for gtk+ <= 2.10.

• name: This is the deprecated variant of the program-name property (see bug bug 345822 for more information) . You only need to set it when compiling the program with gtk <= 2.10; in that case you should set it to whatever you use for the program-name property above.

• title: Set to _("About TheApplicationName")

• translator-credits: should be set to _("translator-credits"). Note the use of a dash instead of underscore in that message. Moreover, you don't need to check whether this message is translated. The about_dialog code does that for you.

• version: The autoconf VERSION macro should be passed.

• website: The URL of your application's website. If you don't have any, create one on live.g.o.

• website-label: Use a label, like "MyApp Website", or don't set this property if you want to show the URL of the website (only if it's a short and easy to remember url, like gtk.org or pango.org).

• wrap-license: Should be set to TRUE most of the times.

Here is an example of how it may look like:

#include <gtk/gtk.h>

...

const gchar *authors[] =
{
      "Noah Levitt <nlevitt@columbia.edu>",
      "Daniel Elstner <daniel.elstner@gmx.net>",
      "Padraig O'Briain <Padraig.Obriain@sun.com>",
      NULL
};

const gchar *documenters[] =
{
      "Chee Bin HOH <cbhoh@gnome.org>",
      "Sun Microsystems",
      NULL
};

static const gchar license_text[] = 
"This program is free software; you can redistribute it and blablabla";

gtk_show_about_dialog (GTK_WINDOW (parent_window),
                         "title", _("About Character Map"),
#if GTK_CHECK_VERSION (2, 12, 0)
                         "program-name", _("Character Map"),
#else
                         "name", _("Character Map"),
#endif
                         "authors", authors,
                         "comments", _("A featureful Unicode character map."),
                         "copyright", "Copyright © 2004 Noah Levitt <nlevitt@columbia.edu>\n"
                                      "Copyright © 1991-2005 Unicode, Inc.",
                         "documenters", documenters,
                         "license", license_text,
                         "wrap-license", TRUE,
                         "logo-icon-name", "gucharmap",
                         "translator-credits", _("translator-credits"),
                         "version", VERSION,
                         "website", "http://live.gnome.org/Gucharmap",
                         NULL);

Alternatively to setting the program-name property, you can put

  g_set_application_name (_("Gucharmap"));

into main() since GtkAboutDialog defaults it to the application name.

Comments

documenters property:

• ShaunMcCance: gnome-doc-utils has a little-known routine that can create a header file listing the documentation contributors as a gchar*[]. I don't think any projects use this right now, in part due to the fact that I never advertised it much.

license property:

• an API to support common licenses without copy/pasting the full license text is being developed in bug 336225. It seems it will use the licence-name property. It will allow to replace the license text with a simple identifier for usual licenses, like "GPL 2+" for the whole "GPL version 2 and later" license text.

name property:

• PaoloBorelli: I don't agree here (with usage of g_set_application_name to set the name): the fact that gtk is able to guess a name from g_set_application_name in case one is not set explicitely is not a reason to do it. For instance it may be decided at a later time to use a generic name like g_set_application_name("Foo Barrer"), but the about dialog should still say "gFooBar" if gFooBar is the name of the program, for instance when you want to report a bug or google the homepage etc.

  • JonesLee: I think standing on user's point of view, they don't really understand the localized name of programs such as 'gcalctool', a name such as GNOME Calculator ofcourse make more sense. Why do users have to know the localized name to do bug report anyway? Cannot bug buddy provide a full name of the programs? (e.g GNOME Calculator ('gcalctool')). Besides, I reckon GNOME should seriously revise the name of GNOME apps, simplify the name will make users easier to remember. eg. renaming "gcalctool" to "gcalc".

  • ChPe: Also note that the "name" property is discarded in gtk 2.11, see bug 345822, so applications not using "program-name" will get the name set with g_set_application_name() used here.

title property:

• GtkAboutDialog automatically builds the dialogue's title using the name property. This is a problem in some languages, see e.g. bug 418434. Therefore we should always set the title attribute to About Name, using the same name as for the name property.

website-label property:

• ChPe: Why (let the raw URL)? I think setting a label like "XYApp Web Site" is much better than showing the raw URL.

  • BehdadEsfahbod: Depends on the case. Showing simple URLs like gtk.org or pango.org is preferred IMHO. BTW, seems like this needs some more work. Currently I don't get it the website linked at all (probably because the link handler is not set), and setting website-label doesn't show the label, still the URL.

    • ChPe: Yes, you get shown the URL unless the link handler is installed. I filed bug 337358 to have libgnomeui install a default one so that at least gnome programs don't have to reinvent the wheel here. This patch is in libgnomeui since version 2.14.

ChPe: I removed the static from the data in the code example above, since it's not necessary to make this data static. The modules already converted should be re-checked for this.

Status of this goal

When starting to work on one module, you can also put your name in the status so that other people don't duplicate the work you're doing.