gtk2/docs/reference/gtk/migrating-GtkAboutDialog.sgml

<?xml version="1.0"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
]>
<chapter id="gtk-migrating-GtkAboutDialog">

  <title>Migrating from GnomeAbout to GtkAboutDialog</title>

  <para>
    Since version 2.6, GTK+ provides the #GtkAboutDialog widget as a 
    replacement for the <structname>GnomeAbout</structname> dialog in 
    the libgnomeui library.
  </para>

  <para>
    #GtkAboutDialog supports all features found in <structname>GnomeAbout</structname>.
    The <structname>GtkAboutDialog</structname> API is bigger, since it follows 
    the GTK+ policy to have getters and setters for all widget properties, 
    but it isn't much more complex than <structname>GnomeAbout</structname>.
  </para>

  <para>
    To convert an application that uses <structname>GnomeAbout</structname> to 
    <structname>GtkAboutDialog</structname>, as a first step, replace calls 
    like
    <informalexample><programlisting>
    const gchar *documentors[] = { 
      "Documenter 1", 
      "Documenter 2", 
      NULL 
    };

    const gchar *documentors[] = { 
      "Author 1", 
      "Author 2", 
      NULL 
    };

    GtkWidget *about = gnome_about_new ("GNOME Test Program", VERSION,
					"(C) 1998-2001 The Free Software Foundation",
					"Program to display GNOME functions.",
					authors,
					documenters,
					_("translator-credits"),
					"logo.png");
    </programlisting></informalexample>
    by something like 
    <informalexample><programlisting>
    GdkPixbuf *logo = gdk_pixbuf_new_from_file ("logo.png", NULL);
    GtkWidget *about = g_object_new (GTK_TYPE_ABOUT_DIALOG,
                                     "name", "GNOME Test Program", 
                                     "version", VERSION,
			             "copyright", "(C) 1998-2001 The Free Software Foundation",
				     "comments", "Program to display GNOME functions.",
			             "authors", authors,
			             "documenters", documenters,
			             "translator-credits", _("translator-credits"),
				     "logo", logo,
                                     NULL);
    g_object_unref (pixbuf);
    </programlisting></informalexample>
    If the g_object_new() construction scares you, you can also use 
    gtk_about_dialog_new() to construct the dialog and then use the 
    setters for the individual properties.
  </para>

  <para>
    Once you are done with the initial conversion, you may want to look into 
    using some of the features of <structname>GtkAboutDialog</structname> 
    which are not present in <structname>GnomeAbout</structname>.
    <itemizedlist>
      <listitem><para>
        You can specify license information with the 
        #GtkAboutDialog:license property
      </para></listitem>
      <listitem><para>
        You can add separate credits for artists with the 
        #GtkAboutDialog:artists property
      </para></listitem>
      <listitem><para>
        You can add a pointer to the website of your application, using the 
        #GtkAboutDialog:website and #GtkAboutDialog:website-label properties.
      </para></listitem>
      <listitem><para>
        If your credits contain email addresses or URLs, you can turn them 
        into clickable links using gtk_about_dialog_set_email_hook() and 
        gtk_about_dialog_set_url_hook(). 
      </para></listitem>   
    </itemizedlist>
  </para>
</chapter>

<!--
Local variables:
mode: sgml
sgml-parent-document: ("gtk-docs.sgml" "book" "part" "chapter")
End:
-->