Top |
Functions
Properties
GStrv | artists | Read / Write |
GStrv | authors | Read / Write |
char * | comments | Read / Write |
char * | copyright | Read / Write |
GStrv | documenters | Read / Write |
char * | license | Read / Write |
GtkLicense | license-type | Read / Write |
GdkPaintable * | logo | Read / Write |
char * | logo-icon-name | Read / Write |
char * | program-name | Read / Write |
char * | system-information | Read / Write |
char * | translator-credits | Read / Write |
char * | version | Read / Write |
char * | website | Read / Write |
char * | website-label | Read / Write |
gboolean | wrap-license | Read / Write |
Implemented Interfaces
GtkAboutDialog implements GtkAccessible, GtkBuildable, GtkConstraintTarget, GtkNative, GtkShortcutManager and GtkRoot.
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 7 8 9 |
GFile *logo_file = g_file_new_for_path ("./logo.png"); GdkTexture *example_logo = gdk_texture_new_from_file (logo_file, NULL); g_object_unref (logo_file); gtk_show_about_dialog (NULL, "program-name", "ExampleCode", "logo", example_logo, "title", _("About ExampleCode"), NULL); |
Functions
gtk_about_dialog_get_program_name ()
const char *
gtk_about_dialog_get_program_name (GtkAboutDialog *about
);
Returns the program name displayed in the about dialog.
gtk_about_dialog_set_program_name ()
void gtk_about_dialog_set_program_name (GtkAboutDialog *about
,const char *name
);
Sets the name to display in the about dialog.
If this is not set, it defaults to g_get_application_name()
.
gtk_about_dialog_get_version ()
const char *
gtk_about_dialog_get_version (GtkAboutDialog *about
);
Returns the version string.
gtk_about_dialog_set_version ()
void gtk_about_dialog_set_version (GtkAboutDialog *about
,const char *version
);
Sets the version string to display in the about dialog.
gtk_about_dialog_get_copyright ()
const char *
gtk_about_dialog_get_copyright (GtkAboutDialog *about
);
Returns the copyright string.
gtk_about_dialog_set_copyright ()
void gtk_about_dialog_set_copyright (GtkAboutDialog *about
,const char *copyright
);
Sets the copyright string to display in the about dialog. This should be a short string of one or two lines.
gtk_about_dialog_get_comments ()
const char *
gtk_about_dialog_get_comments (GtkAboutDialog *about
);
Returns the comments string.
gtk_about_dialog_set_comments ()
void gtk_about_dialog_set_comments (GtkAboutDialog *about
,const char *comments
);
Sets the comments string to display in the about dialog. This should be a short string of one or two lines.
gtk_about_dialog_get_license ()
const char *
gtk_about_dialog_get_license (GtkAboutDialog *about
);
Returns the license information.
gtk_about_dialog_set_license ()
void gtk_about_dialog_set_license (GtkAboutDialog *about
,const char *license
);
Sets the license information to be displayed in the secondary
license dialog. If license
is NULL
, the license button is
hidden.
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.
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.
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()
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()
.
gtk_about_dialog_get_website ()
const char *
gtk_about_dialog_get_website (GtkAboutDialog *about
);
Returns the website URL.
gtk_about_dialog_set_website ()
void gtk_about_dialog_set_website (GtkAboutDialog *about
,const char *website
);
Sets the URL to use for the website link.
gtk_about_dialog_get_website_label ()
const char *
gtk_about_dialog_get_website_label (GtkAboutDialog *about
);
Returns the label used for the website link.
gtk_about_dialog_set_website_label ()
void gtk_about_dialog_set_website_label (GtkAboutDialog *about
,const char *website_label
);
Sets the label to be used for the website link.
gtk_about_dialog_get_authors ()
const char * const *
gtk_about_dialog_get_authors (GtkAboutDialog *about
);
Returns the string which are displayed in the authors tab of the secondary credits dialog.
gtk_about_dialog_set_authors ()
void gtk_about_dialog_set_authors (GtkAboutDialog *about
,const char **authors
);
Sets the strings which are displayed in the authors tab of the secondary credits dialog.
gtk_about_dialog_get_artists ()
const char * const *
gtk_about_dialog_get_artists (GtkAboutDialog *about
);
Returns the string which are displayed in the artists tab of the secondary credits dialog.
gtk_about_dialog_set_artists ()
void gtk_about_dialog_set_artists (GtkAboutDialog *about
,const char **artists
);
Sets the strings which are displayed in the artists tab of the secondary credits dialog.
gtk_about_dialog_get_documenters ()
const char * const *
gtk_about_dialog_get_documenters (GtkAboutDialog *about
);
Returns the string which are displayed in the documenters tab of the secondary credits dialog.
gtk_about_dialog_set_documenters ()
void gtk_about_dialog_set_documenters (GtkAboutDialog *about
,const char **documenters
);
Sets the strings which are displayed in the documenters tab of the credits dialog.
gtk_about_dialog_get_translator_credits ()
const char *
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.
gtk_about_dialog_set_translator_credits ()
void gtk_about_dialog_set_translator_credits (GtkAboutDialog *about
,const char *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.
gtk_about_dialog_get_logo ()
GdkPaintable *
gtk_about_dialog_get_logo (GtkAboutDialog *about
);
Returns the paintable displayed as logo in the about dialog.
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.
gtk_about_dialog_get_logo_icon_name ()
const char *
gtk_about_dialog_get_logo_icon_name (GtkAboutDialog *about
);
Returns the icon name displayed as logo in the about dialog.
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 char *icon_name
);
Sets the icon name to be displayed as logo in the about dialog.
gtk_about_dialog_get_system_information ()
const char *
gtk_about_dialog_get_system_information
(GtkAboutDialog *about
);
Returns the system information that is shown in the about dialog.
gtk_about_dialog_set_system_information ()
void gtk_about_dialog_set_system_information (GtkAboutDialog *about
,const char *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”.
gtk_about_dialog_add_credit_section ()
void gtk_about_dialog_add_credit_section (GtkAboutDialog *about
,const char *section_name
,const char **people
);
Creates a new section in the Credits page.
gtk_show_about_dialog ()
void gtk_show_about_dialog (GtkWindow *parent
,const char *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.
Types and Values
enum GtkLicense
The type of license for an application.
This enumeration can be expanded at later date.
Members
No license specified |
||
A license text is going to be specified by the developer |
||
The GNU General Public License, version 2.0 or later |
||
The GNU General Public License, version 3.0 or later |
||
The GNU Lesser General Public License, version 2.1 or later |
||
The GNU Lesser General Public License, version 3.0 or later |
||
The BSD standard license |
||
The MIT/X11 standard license |
||
The Artistic License, version 2.0 |
||
The GNU General Public License, version 2.0 only |
||
The GNU General Public License, version 3.0 only |
||
The GNU Lesser General Public License, version 2.1 only |
||
The GNU Lesser General Public License, version 3.0 only |
||
The GNU Affero General Public License, version 3.0 or later |
||
The GNU Affero General Public License, version 3.0 only |
||
The 3-clause BSD licence |
||
The Apache License, version 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” char *
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” char *
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” char *
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_name()
will be used.
Owner: GtkAboutDialog
Flags: Read / Write
The “logo-icon-name”
property
“logo-icon-name” char *
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” char *
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” char *
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” char *
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” char *
The version of the program.
Owner: GtkAboutDialog
Flags: Read / Write
Default value: NULL
The “website”
property
“website” char *
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” char *
The label for the link to the website of the program.
Owner: GtkAboutDialog
Flags: Read / Write
Default value: NULL
Signal Details
The “activate-link”
signal
gboolean user_function (GtkAboutDialog *label, char *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. |
Flags: Run Last