AuroraMiddleware/gtk
1
0
Fork 1
mirror of https://gitlab.gnome.org/GNOME/gtk.git synced 2024-11-11 03:10:09 +00:00
Code Issues Projects Releases Wiki Activity

Move documentation from templates to inline comments: GtkAboutDialog

Browse Source 
https://bugzilla.gnome.org/show_bug.cgi?id=597865
This commit is contained in:
Javier Jardón 2009-10-14 03:23:47 +02:00
parent df9e1c3294
commit 588bec9121
3 changed files with 78 additions and 475 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

475
docs/reference/gtk/tmpl/gtkaboutdialog.sgml
View File

@ -1,475 +0,0 @@
<!-- ##### SECTION Title ##### -->
GtkAboutDialog
<!-- ##### SECTION Short_Description ##### -->
Display information about an application
<!-- ##### SECTION Long_Description ##### -->
<para>
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 <literal>About</literal> option from
the <literal>Help</literal> menu. All parts of the dialog are optional.
</para>
<para>
About dialog often contain links and email addresses. #GtkAboutDialog
supports this by offering global hooks, which are called when the user
clicks on a link or email address, see gtk_about_dialog_set_email_hook()
and gtk_about_dialog_set_url_hook(). Email addresses in the
authors, documenters and artists properties are recognized by looking for
<literal>&lt;user@<!-- -->host&gt;</literal>, URLs are
recognized by looking for <literal>http://url</literal>, with
<literal>url</literal> extending to the next space, tab or line break.
</para>
<para id="gtk-about-dialog-hook-setup">
Since 2.18 #GtkAboutDialog provides default website and email hooks that use
gtk_show_uri().
</para>
<para>
If you want provide your own hooks overriding the default ones, it is important
to do so before setting the website and email URL properties, like this:
</para>
<informalexample><programlisting>
gtk_about_dialog_set_url_hook (GTK_ABOUT_DIALOG (dialog), launch_url, NULL, NULL);
gtk_about_dialog_set_website (GTK_ABOUT_DIALOG (dialog), app_url);
</programlisting></informalexample>
<para>
To disable the default hooks, you can pass %NULL as the hook func. Then,
the #GtkAboutDialog widget will not display the website or the
email addresses as clickable.
</para>
<para>
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.
</para>
<para>
Note that GTK+ sets a default title of <literal>_("About &percnt;s")</literal>
on the dialog window (where &percnt;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:
</para>
<informalexample><programlisting>
gtk_show_about_dialog (NULL,
"program-name", "ExampleCode",
"logo", example_logo,
"title" _("About ExampleCode"),
NULL);
</programlisting></informalexample>
<para>
Note that prior to GTK+ 2.12, the #GtkAboutDialog:program-name property
was called "name". This was changed to avoid the conflict with the
#GtkWidget:name property.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
#GTK_STOCK_ABOUT
</para>
<!-- ##### SECTION Stability_Level ##### -->
<!-- ##### STRUCT GtkAboutDialog ##### -->
<para>
The <structname>GtkAboutDialog</structname> struct contains
only private fields and should not be directly accessed.
</para>
<!-- ##### ARG GtkAboutDialog:artists ##### -->
<para>
</para>
<!-- ##### ARG GtkAboutDialog:authors ##### -->
<para>
</para>
<!-- ##### ARG GtkAboutDialog:comments ##### -->
<para>
</para>
<!-- ##### ARG GtkAboutDialog:copyright ##### -->
<para>
</para>
<!-- ##### ARG GtkAboutDialog:documenters ##### -->
<para>
</para>
<!-- ##### ARG GtkAboutDialog:license ##### -->
<para>
</para>
<!-- ##### ARG GtkAboutDialog:logo ##### -->
<para>
</para>
<!-- ##### ARG GtkAboutDialog:logo-icon-name ##### -->
<para>
</para>
<!-- ##### ARG GtkAboutDialog:program-name ##### -->
<para>
</para>
<!-- ##### ARG GtkAboutDialog:translator-credits ##### -->
<para>
</para>
<!-- ##### ARG GtkAboutDialog:version ##### -->
<para>
</para>
<!-- ##### ARG GtkAboutDialog:website ##### -->
<para>
</para>
<!-- ##### ARG GtkAboutDialog:website-label ##### -->
<para>
</para>
<!-- ##### ARG GtkAboutDialog:wrap-license ##### -->
<para>
</para>
<!-- ##### FUNCTION gtk_about_dialog_new ##### -->
<para>
</para>
@Returns:
<!-- ##### FUNCTION gtk_about_dialog_get_name ##### -->
<para>
</para>
@about:
@Returns:
<!-- ##### FUNCTION gtk_about_dialog_set_name ##### -->
<para>
</para>
@about:
@name:
<!-- ##### FUNCTION gtk_about_dialog_get_program_name ##### -->
<para>
</para>
@about:
@Returns:
<!-- ##### FUNCTION gtk_about_dialog_set_program_name ##### -->
<para>
</para>
@about:
@name:
<!-- ##### FUNCTION gtk_about_dialog_get_version ##### -->
<para>
</para>
@about:
@Returns:
<!-- ##### FUNCTION gtk_about_dialog_set_version ##### -->
<para>
</para>
@about:
@version:
<!-- ##### FUNCTION gtk_about_dialog_get_copyright ##### -->
<para>
</para>
@about:
@Returns:
<!-- ##### FUNCTION gtk_about_dialog_set_copyright ##### -->
<para>
</para>
@about:
@copyright:
<!-- ##### FUNCTION gtk_about_dialog_get_comments ##### -->
<para>
</para>
@about:
@Returns:
<!-- ##### FUNCTION gtk_about_dialog_set_comments ##### -->
<para>
</para>
@about:
@comments:
<!-- ##### FUNCTION gtk_about_dialog_get_license ##### -->
<para>
</para>
@about:
@Returns:
<!-- ##### FUNCTION gtk_about_dialog_set_license ##### -->
<para>
</para>
@about:
@license:
<!-- ##### FUNCTION gtk_about_dialog_get_wrap_license ##### -->
<para>
</para>
@about:
@Returns:
<!-- ##### FUNCTION gtk_about_dialog_set_wrap_license ##### -->
<para>
</para>
@about:
@wrap_license:
<!-- ##### FUNCTION gtk_about_dialog_get_website ##### -->
<para>
</para>
@about:
@Returns:
<!-- ##### FUNCTION gtk_about_dialog_set_website ##### -->
<para>
</para>
@about:
@website:
<!-- ##### FUNCTION gtk_about_dialog_get_website_label ##### -->
<para>
</para>
@about:
@Returns:
<!-- ##### FUNCTION gtk_about_dialog_set_website_label ##### -->
<para>
</para>
@about:
@website_label:
<!-- ##### FUNCTION gtk_about_dialog_get_authors ##### -->
<para>
</para>
@about:
@Returns:
<!-- ##### FUNCTION gtk_about_dialog_set_authors ##### -->
<para>
</para>
@about:
@authors:
<!-- ##### FUNCTION gtk_about_dialog_get_artists ##### -->
<para>
</para>
@about:
@Returns:
<!-- ##### FUNCTION gtk_about_dialog_set_artists ##### -->
<para>
</para>
@about:
@artists:
<!-- ##### FUNCTION gtk_about_dialog_get_documenters ##### -->
<para>
</para>
@about:
@Returns:
<!-- ##### FUNCTION gtk_about_dialog_set_documenters ##### -->
<para>
</para>
@about:
@documenters:
<!-- ##### FUNCTION gtk_about_dialog_get_translator_credits ##### -->
<para>
</para>
@about:
@Returns:
<!-- ##### FUNCTION gtk_about_dialog_set_translator_credits ##### -->
<para>
</para>
@about:
@translator_credits:
<!-- ##### FUNCTION gtk_about_dialog_get_logo ##### -->
<para>
</para>
@about:
@Returns:
<!-- ##### FUNCTION gtk_about_dialog_set_logo ##### -->
<para>
</para>
@about:
@logo:
<!-- ##### FUNCTION gtk_about_dialog_get_logo_icon_name ##### -->
<para>
</para>
@about:
@Returns:
<!-- ##### FUNCTION gtk_about_dialog_set_logo_icon_name ##### -->
<para>
</para>
@about:
@icon_name:
<!-- ##### USER_FUNCTION GtkAboutDialogActivateLinkFunc ##### -->
<para>
The type of a function which is called when a URL or email
link is activated.
</para>
@about: the #GtkAboutDialog in which the link was activated
@link_: the URL or email address to which the activated link points
@data: user data that was passed when the function was registered
with gtk_about_dialog_set_email_hook() or
gtk_about_dialog_set_url_hook()
<!-- ##### FUNCTION gtk_about_dialog_set_email_hook ##### -->
<para>
</para>
@func:
@data:
@destroy:
@Returns:
<!-- ##### FUNCTION gtk_about_dialog_set_url_hook ##### -->
<para>
</para>
@func:
@data:
@destroy:
@Returns:
<!-- ##### FUNCTION gtk_show_about_dialog ##### -->
<para>
</para>
@parent:
@first_property_name:
@Varargs:

61
gtk/gtkaboutdialog.c
View File

@ -57,6 +57,67 @@
#include "gtkalias.h"
/**
* SECTION:gtkaboutdialog
* @Short_description: Display information about an application
* @Title: GtkAboutDialog
* @See_also:#GTK_STOCK_ABOUT
*
* 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 <literal>About</literal> option from
* the <literal>Help</literal> menu. All parts of the dialog are optional.
*
* About dialog often contain links and email addresses. #GtkAboutDialog
* supports this by offering global hooks, which are called when the user
* clicks on a link or email address, see gtk_about_dialog_set_email_hook()
* and gtk_about_dialog_set_url_hook(). Email addresses in the
* authors, documenters and artists properties are recognized by looking for
* <literal><user@<!-- -->host></literal>, URLs are
* recognized by looking for <literal>http://url</literal>, with
* <literal>url</literal> extending to the next space, tab or line break.
*
* <para id="gtk-about-dialog-hook-setup">
* Since 2.18 #GtkAboutDialog provides default website and email hooks that use
* gtk_show_uri().
*
* If you want provide your own hooks overriding the default ones, it is important
* to do so before setting the website and email URL properties, like this:
*
* <informalexample><programlisting>
* gtk_about_dialog_set_url_hook (GTK_ABOUT_DIALOG (dialog), launch_url, NULL, NULL);
* gtk_about_dialog_set_website (GTK_ABOUT_DIALOG (dialog), app_url);
* </programlisting></informalexample>
* To disable the default hooks, you can pass %NULL as the hook func. Then,
* the #GtkAboutDialog widget will not display the website or the
* email addresses as clickable.
*
* 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 <literal>_("About &percnt;s")</literal>
* on the dialog window (where &percnt;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:
*
* <informalexample><programlisting>
* gtk_show_about_dialog (NULL,
* "program-name", "ExampleCode",
* "logo", example_logo,
* "title" _("About ExampleCode"),
* NULL);
* </programlisting></informalexample>
* Note that prior to GTK+ 2.12, the #GtkAboutDialog:program-name property
* was called "name". This was changed to avoid the conflict with the
* #GtkWidget:name property.
*/
static GdkColor default_link_color = { 0, 0, 0, 0xeeee };
static GdkColor default_visited_link_color = { 0, 0x5555, 0x1a1a, 0x8b8b };

17
gtk/gtkaboutdialog.h
View File

@ -43,6 +43,12 @@ G_BEGIN_DECLS
typedef struct _GtkAboutDialog GtkAboutDialog;
typedef struct _GtkAboutDialogClass GtkAboutDialogClass;
/**
* GtkAboutDialog:
*
* The <structname>GtkAboutDialog</structname> struct contains
* only private fields and should not be directly accessed.
*/
struct _GtkAboutDialog
{
GtkDialog parent_instance;
@ -118,6 +124,17 @@ G_CONST_RETURN gchar *gtk_about_dialog_get_logo_icon_name (GtkAboutDialog
void gtk_about_dialog_set_logo_icon_name (GtkAboutDialog *about,
const gchar *icon_name);
/**
* GtkAboutDialogActivateLinkFunc:
* @about: the #GtkAboutDialog in which the link was activated
* @link_: the URL or email address to which the activated link points
* @data: user data that was passed when the function was registered
* with gtk_about_dialog_set_email_hook() or
* gtk_about_dialog_set_url_hook()
*
* The type of a function which is called when a URL or email
* link is activated.
*/
typedef void (* GtkAboutDialogActivateLinkFunc) (GtkAboutDialog *about,
const gchar *link_,
gpointer data);