GtkAboutDialog

GtkAboutDialog — Display information about an application

Functions

GtkWidget * gtk_about_dialog_new ()
const gchar * gtk_about_dialog_get_program_name ()
void gtk_about_dialog_set_program_name ()
const gchar * gtk_about_dialog_get_version ()
void gtk_about_dialog_set_version ()
const gchar * gtk_about_dialog_get_copyright ()
void gtk_about_dialog_set_copyright ()
const gchar * gtk_about_dialog_get_comments ()
void gtk_about_dialog_set_comments ()
const gchar * gtk_about_dialog_get_license ()
void gtk_about_dialog_set_license ()
gboolean gtk_about_dialog_get_wrap_license ()
void gtk_about_dialog_set_wrap_license ()
GtkLicense gtk_about_dialog_get_license_type ()
void gtk_about_dialog_set_license_type ()
const gchar * gtk_about_dialog_get_website ()
void gtk_about_dialog_set_website ()
const gchar * gtk_about_dialog_get_website_label ()
void gtk_about_dialog_set_website_label ()
const gchar * const * gtk_about_dialog_get_authors ()
void gtk_about_dialog_set_authors ()
const gchar * const * gtk_about_dialog_get_artists ()
void gtk_about_dialog_set_artists ()
const gchar * const * gtk_about_dialog_get_documenters ()
void gtk_about_dialog_set_documenters ()
const gchar * gtk_about_dialog_get_translator_credits ()
void gtk_about_dialog_set_translator_credits ()
GdkPaintable * gtk_about_dialog_get_logo ()
void gtk_about_dialog_set_logo ()
const gchar * gtk_about_dialog_get_logo_icon_name ()
void gtk_about_dialog_set_logo_icon_name ()
const gchar * gtk_about_dialog_get_system_information ()
void gtk_about_dialog_set_system_information ()
void gtk_about_dialog_add_credit_section ()
void gtk_show_about_dialog ()

Properties

GStrv artists Read / Write
GStrv authors Read / Write
gchar * comments Read / Write
gchar * copyright Read / Write
GStrv documenters Read / Write
gchar * license Read / Write
GtkLicense license-type Read / Write
GdkPaintable * logo Read / Write
gchar * logo-icon-name Read / Write
gchar * program-name Read / Write
gchar * system-information Read / Write
gchar * translator-credits Read / Write
gchar * version Read / Write
gchar * website Read / Write
gchar * website-label Read / Write
gboolean wrap-license Read / Write

Signals

gboolean activate-link Run Last

Types and Values

Object Hierarchy

    GObject
    ╰── GInitiallyUnowned
        ╰── GtkWidget
            ╰── GtkWindow
                ╰── GtkDialog
                    ╰── GtkAboutDialog

Implemented Interfaces

GtkAboutDialog implements AtkImplementorIface, GtkBuildable, GtkConstraintTarget, GtkNative, GtkShortcutManager and GtkRoot.

Includes

#include <gtk/gtk.h>

Description

The GtkAboutDialog offers a simple way to display information about a program like its logo, name, copyright, website and license. It is also possible to give credits to the authors, documenters, translators and artists who have worked on the program. An about dialog is typically opened when the user selects the About option from the Help menu. All parts of the dialog are optional.

About dialogs often contain links and email addresses. GtkAboutDialog displays these as clickable links. By default, it calls gtk_show_uri() when a user clicks one. The behaviour can be overridden with the “activate-link” signal.

To specify a person with an email address, use a string like "Edgar Allan Poe <edgar@poe.com>". To specify a website with a title, use a string like "GTK+ team http://www.gtk.org".

To make constructing a GtkAboutDialog as convenient as possible, you can use the function gtk_show_about_dialog() which constructs and shows a dialog and keeps it around so that it can be shown again.

Note that GTK+ sets a default title of _("About %s") on the dialog window (where %s is replaced by the name of the application, but in order to ensure proper translation of the title, applications should set the title property explicitly when constructing a GtkAboutDialog, as shown in the following example:

1
2
3
4
5
6
GdkTexture *example_logo = gdk_texture_new_from_file ("./logo.png", NULL);
gtk_show_about_dialog (NULL,
                       "program-name", "ExampleCode",
                       "logo", example_logo,
                       "title", _("About ExampleCode"),
                       NULL);

It is also possible to show a GtkAboutDialog like any other GtkDialog, and use the “response” signal to catch user responses. In this case, you might need to know that the “Close” button returns the GTK_RESPONSE_CANCEL response id.

Functions

gtk_about_dialog_new ()

GtkWidget *
gtk_about_dialog_new (void);

Creates a new GtkAboutDialog.

Returns

a newly created GtkAboutDialog


gtk_about_dialog_get_program_name ()

const gchar *
gtk_about_dialog_get_program_name (GtkAboutDialog *about);

Returns the program name displayed in the about dialog.

Parameters

about

a GtkAboutDialog

 

Returns

The program name. The string is owned by the about dialog and must not be modified.


gtk_about_dialog_set_program_name ()

void
gtk_about_dialog_set_program_name (GtkAboutDialog *about,
                                   const gchar *name);

Sets the name to display in the about dialog. If this is not set, it defaults to g_get_application_name().

Parameters

about

a GtkAboutDialog

 

name

the program name

 

gtk_about_dialog_get_version ()

const gchar *
gtk_about_dialog_get_version (GtkAboutDialog *about);

Returns the version string.

Parameters

about

a GtkAboutDialog

 

Returns

The version string. The string is owned by the about dialog and must not be modified.


gtk_about_dialog_set_version ()

void
gtk_about_dialog_set_version (GtkAboutDialog *about,
                              const gchar *version);

Sets the version string to display in the about dialog.

Parameters

about

a GtkAboutDialog

 

version

the version string.

[allow-none]

gtk_about_dialog_get_copyright ()

const gchar *
gtk_about_dialog_get_copyright (GtkAboutDialog *about);

Returns the copyright string.

Parameters

about

a GtkAboutDialog

 

Returns

The copyright string. The string is owned by the about dialog and must not be modified.


gtk_about_dialog_set_copyright ()

void
gtk_about_dialog_set_copyright (GtkAboutDialog *about,
                                const gchar *copyright);

Sets the copyright string to display in the about dialog. This should be a short string of one or two lines.

Parameters

about

a GtkAboutDialog

 

copyright

the copyright string.

[allow-none]

gtk_about_dialog_get_comments ()

const gchar *
gtk_about_dialog_get_comments (GtkAboutDialog *about);

Returns the comments string.

Parameters

about

a GtkAboutDialog

 

Returns

The comments. The string is owned by the about dialog and must not be modified.


gtk_about_dialog_set_comments ()

void
gtk_about_dialog_set_comments (GtkAboutDialog *about,
                               const gchar *comments);

Sets the comments string to display in the about dialog. This should be a short string of one or two lines.

Parameters

about

a GtkAboutDialog

 

comments

a comments string.

[allow-none]

gtk_about_dialog_get_license ()

const gchar *
gtk_about_dialog_get_license (GtkAboutDialog *about);

Returns the license information.

Parameters

about

a GtkAboutDialog

 

Returns

The license information. The string is owned by the about dialog and must not be modified.


gtk_about_dialog_set_license ()

void
gtk_about_dialog_set_license (GtkAboutDialog *about,
                              const gchar *license);

Sets the license information to be displayed in the secondary license dialog. If license is NULL, the license button is hidden.

Parameters

about

a GtkAboutDialog

 

license

the license information or NULL.

[allow-none]

gtk_about_dialog_get_wrap_license ()

gboolean
gtk_about_dialog_get_wrap_license (GtkAboutDialog *about);

Returns whether the license text in about is automatically wrapped.

Parameters

about

a GtkAboutDialog

 

Returns

TRUE if the license text is wrapped


gtk_about_dialog_set_wrap_license ()

void
gtk_about_dialog_set_wrap_license (GtkAboutDialog *about,
                                   gboolean wrap_license);

Sets whether the license text in about is automatically wrapped.

Parameters

about

a GtkAboutDialog

 

wrap_license

whether to wrap the license

 

gtk_about_dialog_get_license_type ()

GtkLicense
gtk_about_dialog_get_license_type (GtkAboutDialog *about);

Retrieves the license set using gtk_about_dialog_set_license_type()

Parameters

about

a GtkAboutDialog

 

Returns

a GtkLicense value


gtk_about_dialog_set_license_type ()

void
gtk_about_dialog_set_license_type (GtkAboutDialog *about,
                                   GtkLicense license_type);

Sets the license of the application showing the about dialog from a list of known licenses.

This function overrides the license set using gtk_about_dialog_set_license().

Parameters

about

a GtkAboutDialog

 

license_type

the type of license

 

gtk_about_dialog_get_website ()

const gchar *
gtk_about_dialog_get_website (GtkAboutDialog *about);

Returns the website URL.

Parameters

about

a GtkAboutDialog

 

Returns

The website URL. The string is owned by the about dialog and must not be modified.


gtk_about_dialog_set_website ()

void
gtk_about_dialog_set_website (GtkAboutDialog *about,
                              const gchar *website);

Sets the URL to use for the website link.

Parameters

about

a GtkAboutDialog

 

website

a URL string starting with "http://".

[allow-none]

gtk_about_dialog_get_website_label ()

const gchar *
gtk_about_dialog_get_website_label (GtkAboutDialog *about);

Returns the label used for the website link.

Parameters

about

a GtkAboutDialog

 

Returns

The label used for the website link. The string is owned by the about dialog and must not be modified.


gtk_about_dialog_set_website_label ()

void
gtk_about_dialog_set_website_label (GtkAboutDialog *about,
                                    const gchar *website_label);

Sets the label to be used for the website link.

Parameters

about

a GtkAboutDialog

 

website_label

the label used for the website link

 

gtk_about_dialog_get_authors ()

const gchar * const *
gtk_about_dialog_get_authors (GtkAboutDialog *about);

Returns the string which are displayed in the authors tab of the secondary credits dialog.

Parameters

about

a GtkAboutDialog

 

Returns

A NULL-terminated string array containing the authors. The array is owned by the about dialog and must not be modified.

[array zero-terminated=1][transfer none]


gtk_about_dialog_set_authors ()

void
gtk_about_dialog_set_authors (GtkAboutDialog *about,
                              const gchar **authors);

Sets the strings which are displayed in the authors tab of the secondary credits dialog.

Parameters

about

a GtkAboutDialog

 

authors

a NULL-terminated array of strings.

[array zero-terminated=1]

gtk_about_dialog_get_artists ()

const gchar * const *
gtk_about_dialog_get_artists (GtkAboutDialog *about);

Returns the string which are displayed in the artists tab of the secondary credits dialog.

Parameters

about

a GtkAboutDialog

 

Returns

A NULL-terminated string array containing the artists. The array is owned by the about dialog and must not be modified.

[array zero-terminated=1][transfer none]


gtk_about_dialog_set_artists ()

void
gtk_about_dialog_set_artists (GtkAboutDialog *about,
                              const gchar **artists);

Sets the strings which are displayed in the artists tab of the secondary credits dialog.

Parameters

about

a GtkAboutDialog

 

artists

a NULL-terminated array of strings.

[array zero-terminated=1]

gtk_about_dialog_get_documenters ()

const gchar * const *
gtk_about_dialog_get_documenters (GtkAboutDialog *about);

Returns the string which are displayed in the documenters tab of the secondary credits dialog.

Parameters

about

a GtkAboutDialog

 

Returns

A NULL-terminated string array containing the documenters. The array is owned by the about dialog and must not be modified.

[array zero-terminated=1][transfer none]


gtk_about_dialog_set_documenters ()

void
gtk_about_dialog_set_documenters (GtkAboutDialog *about,
                                  const gchar **documenters);

Sets the strings which are displayed in the documenters tab of the credits dialog.

Parameters

about

a GtkAboutDialog

 

documenters

a NULL-terminated array of strings.

[array zero-terminated=1]

gtk_about_dialog_get_translator_credits ()

const gchar *
gtk_about_dialog_get_translator_credits
                               (GtkAboutDialog *about);

Returns the translator credits string which is displayed in the translators tab of the secondary credits dialog.

Parameters

about

a GtkAboutDialog

 

Returns

The translator credits string. The string is owned by the about dialog and must not be modified.


gtk_about_dialog_set_translator_credits ()

void
gtk_about_dialog_set_translator_credits
                               (GtkAboutDialog *about,
                                const gchar *translator_credits);

Sets the translator credits string which is displayed in the translators tab of the secondary credits dialog.

The intended use for this string is to display the translator of the language which is currently used in the user interface. Using gettext(), a simple way to achieve that is to mark the string for translation:

1
2
3
GtkWidget *about = gtk_about_dialog_new ();
 gtk_about_dialog_set_translator_credits (GTK_ABOUT_DIALOG (about),
                                          _("translator-credits"));

It is a good idea to use the customary msgid “translator-credits” for this purpose, since translators will already know the purpose of that msgid, and since GtkAboutDialog will detect if “translator-credits” is untranslated and hide the tab.

Parameters

about

a GtkAboutDialog

 

translator_credits

the translator credits.

[allow-none]

gtk_about_dialog_get_logo ()

GdkPaintable *
gtk_about_dialog_get_logo (GtkAboutDialog *about);

Returns the paintable displayed as logo in the about dialog.

Parameters

about

a GtkAboutDialog

 

Returns

the paintable displayed as logo or NULL if the logo is unset or has been set via gtk_about_dialog_set_logo_icon_name(). The paintable is owned by the about dialog. If you want to keep a reference to it, you have to call g_object_ref() on it.

[transfer none][nullable]


gtk_about_dialog_set_logo ()

void
gtk_about_dialog_set_logo (GtkAboutDialog *about,
                           GdkPaintable *logo);

Sets the logo in the about dialog.

Parameters

about

a GtkAboutDialog

 

logo

a GdkPaintable, or NULL.

[allow-none]

gtk_about_dialog_get_logo_icon_name ()

const gchar *
gtk_about_dialog_get_logo_icon_name (GtkAboutDialog *about);

Returns the icon name displayed as logo in the about dialog.

Parameters

about

a GtkAboutDialog

 

Returns

the icon name displayed as logo or NULL if the logo has been set via gtk_about_dialog_set_logo(). The string is owned by the dialog. If you want to keep a reference to it, you have to call g_strdup() on it.

[transfer none][nullable]


gtk_about_dialog_set_logo_icon_name ()

void
gtk_about_dialog_set_logo_icon_name (GtkAboutDialog *about,
                                     const gchar *icon_name);

Sets the icon name to be displayed as logo in the about dialog.

Parameters

about

a GtkAboutDialog

 

icon_name

an icon name, or NULL.

[allow-none]

gtk_about_dialog_get_system_information ()

const gchar *
gtk_about_dialog_get_system_information
                               (GtkAboutDialog *about);

Returns the system information that is shown in the about dialog.

Parameters

about

a GtkAboutDialog

 

Returns

the system information


gtk_about_dialog_set_system_information ()

void
gtk_about_dialog_set_system_information
                               (GtkAboutDialog *about,
                                const gchar *system_information);

Sets the system information to be displayed in the about dialog. If system_information is NULL, the system information tab is hidden.

See “system-information”.

Parameters

about

a GtkAboutDialog

 

system_information

system information or NULL.

[allow-none]

gtk_about_dialog_add_credit_section ()

void
gtk_about_dialog_add_credit_section (GtkAboutDialog *about,
                                     const gchar *section_name,
                                     const gchar **people);

Creates a new section in the Credits page.

Parameters

about

A GtkAboutDialog

 

section_name

The name of the section

 

people

The people who belong to that section.

[array zero-terminated=1]

gtk_show_about_dialog ()

void
gtk_show_about_dialog (GtkWindow *parent,
                       const gchar *first_property_name,
                       ...);

This is a convenience function for showing an application’s about box. The constructed dialog is associated with the parent window and reused for future invocations of this function.

Parameters

parent

transient parent, or NULL for none.

[allow-none]

first_property_name

the name of the first property

 

...

value of first property, followed by more properties, NULL-terminated

 

Types and Values

GtkAboutDialog

typedef struct _GtkAboutDialog GtkAboutDialog;

enum GtkLicense

The type of license for an application.

This enumeration can be expanded at later date.

Members

GTK_LICENSE_UNKNOWN

No license specified

 

GTK_LICENSE_CUSTOM

A license text is going to be specified by the developer

 

GTK_LICENSE_GPL_2_0

The GNU General Public License, version 2.0 or later

 

GTK_LICENSE_GPL_3_0

The GNU General Public License, version 3.0 or later

 

GTK_LICENSE_LGPL_2_1

The GNU Lesser General Public License, version 2.1 or later

 

GTK_LICENSE_LGPL_3_0

The GNU Lesser General Public License, version 3.0 or later

 

GTK_LICENSE_BSD

The BSD standard license

 

GTK_LICENSE_MIT_X11

The MIT/X11 standard license

 

GTK_LICENSE_ARTISTIC

The Artistic License, version 2.0

 

GTK_LICENSE_GPL_2_0_ONLY

The GNU General Public License, version 2.0 only

 

GTK_LICENSE_GPL_3_0_ONLY

The GNU General Public License, version 3.0 only

 

GTK_LICENSE_LGPL_2_1_ONLY

The GNU Lesser General Public License, version 2.1 only

 

GTK_LICENSE_LGPL_3_0_ONLY

The GNU Lesser General Public License, version 3.0 only

 

GTK_LICENSE_AGPL_3_0

The GNU Affero General Public License, version 3.0 or later

 

GTK_LICENSE_AGPL_3_0_ONLY

The GNU Affero General Public License, version 3.0 only

 

GTK_LICENSE_BSD_3

The 3-clause BSD licence

 

GTK_LICENSE_APACHE_2_0

The Apache License, version 2.0

 

GTK_LICENSE_MPL_2_0

The Mozilla Public License, version 2.0

 

Property Details

The “artists” property

  “artists”                  GStrv

The people who contributed artwork to the program, as a NULL-terminated array of strings. Each string may contain email addresses and URLs, which will be displayed as links, see the introduction for more details.

Owner: GtkAboutDialog

Flags: Read / Write


The “authors” property

  “authors”                  GStrv

The authors of the program, as a NULL-terminated array of strings. Each string may contain email addresses and URLs, which will be displayed as links, see the introduction for more details.

Owner: GtkAboutDialog

Flags: Read / Write


The “comments” property

  “comments”                 gchar *

Comments about the program. This string is displayed in a label in the main dialog, thus it should be a short explanation of the main purpose of the program, not a detailed list of features.

Owner: GtkAboutDialog

Flags: Read / Write

Default value: NULL


The “copyright” property

  “copyright”                gchar *

Copyright information for the program.

Owner: GtkAboutDialog

Flags: Read / Write

Default value: NULL


The “documenters” property

  “documenters”              GStrv

The people documenting the program, as a NULL-terminated array of strings. Each string may contain email addresses and URLs, which will be displayed as links, see the introduction for more details.

Owner: GtkAboutDialog

Flags: Read / Write


The “license” property

  “license”                  gchar *

The license of the program. This string is displayed in a text view in a secondary dialog, therefore it is fine to use a long multi-paragraph text. Note that the text is only wrapped in the text view if the "wrap-license" property is set to TRUE; otherwise the text itself must contain the intended linebreaks. When setting this property to a non-NULL value, the “license-type” property is set to GTK_LICENSE_CUSTOM as a side effect.

The text may contain links in this format <http://www.some.place/> and email references in the form <mail-tosome.body >, and these will be converted into clickable links.

Owner: GtkAboutDialog

Flags: Read / Write

Default value: NULL


The “license-type” property

  “license-type”             GtkLicense

The license of the program, as a value of the GtkLicense enumeration.

The GtkAboutDialog will automatically fill out a standard disclaimer and link the user to the appropriate online resource for the license text.

If GTK_LICENSE_UNKNOWN is used, the link used will be the same specified in the “website” property.

If GTK_LICENSE_CUSTOM is used, the current contents of the “license” property are used.

For any other GtkLicense value, the contents of the “license” property are also set by this property as a side effect.

Owner: GtkAboutDialog

Flags: Read / Write

Default value: GTK_LICENSE_UNKNOWN


The “logo” property

  “logo”                     GdkPaintable *

A logo for the about box. If it is NULL, the default window icon set with gtk_window_set_default_icon() will be used.

Owner: GtkAboutDialog

Flags: Read / Write


The “logo-icon-name” property

  “logo-icon-name”           gchar *

A named icon to use as the logo for the about box. This property overrides the “logo” property.

Owner: GtkAboutDialog

Flags: Read / Write

Default value: NULL


The “program-name” property

  “program-name”             gchar *

The name of the program. If this is not set, it defaults to g_get_application_name().

Owner: GtkAboutDialog

Flags: Read / Write

Default value: NULL


The “system-information” property

  “system-information”       gchar *

Information about the system on which the program is running. This is displayed in a separate tab, therefore it is fine to use a long multi-paragraph text. Note that the text should contain the intended linebreaks.

The text may contain links in this format <http://www.some.place/> and email references in the form <mail-tosome.body >, and these will be converted into clickable links.

Owner: GtkAboutDialog

Flags: Read / Write

Default value: NULL


The “translator-credits” property

  “translator-credits”       gchar *

Credits to the translators. This string should be marked as translatable. The string may contain email addresses and URLs, which will be displayed as links, see the introduction for more details.

Owner: GtkAboutDialog

Flags: Read / Write

Default value: NULL


The “version” property

  “version”                  gchar *

The version of the program.

Owner: GtkAboutDialog

Flags: Read / Write

Default value: NULL


The “website” property

  “website”                  gchar *

The URL for the link to the website of the program. This should be a string starting with "http://.

Owner: GtkAboutDialog

Flags: Read / Write

Default value: NULL


The “website-label” property

  “website-label”            gchar *

The label for the link to the website of the program.

Owner: GtkAboutDialog

Flags: Read / Write

Default value: NULL


The “wrap-license” property

  “wrap-license”             gboolean

Whether to wrap the text in the license dialog.

Owner: GtkAboutDialog

Flags: Read / Write

Default value: FALSE

Signal Details

The “activate-link” signal

gboolean
user_function (GtkAboutDialog *label,
               gchar          *uri,
               gpointer        user_data)

The signal which gets emitted to activate a URI. Applications may connect to it to override the default behaviour, which is to call gtk_show_uri().

Parameters

label

The object on which the signal was emitted

 

uri

the URI that is activated

 

user_data

user data set when the signal handler was connected.

 

Returns

TRUE if the link has been activated

Flags: Run Last