From 588bec91211977b311d9f2c808d3ff241fa53c38 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Javier=20Jard=C3=B3n?= Date: Wed, 14 Oct 2009 03:23:47 +0200 Subject: [PATCH] Move documentation from templates to inline comments: GtkAboutDialog https://bugzilla.gnome.org/show_bug.cgi?id=597865 --- docs/reference/gtk/tmpl/gtkaboutdialog.sgml | 475 -------------------- gtk/gtkaboutdialog.c | 61 +++ gtk/gtkaboutdialog.h | 17 + 3 files changed, 78 insertions(+), 475 deletions(-) delete mode 100644 docs/reference/gtk/tmpl/gtkaboutdialog.sgml diff --git a/docs/reference/gtk/tmpl/gtkaboutdialog.sgml b/docs/reference/gtk/tmpl/gtkaboutdialog.sgml deleted file mode 100644 index 6aac589c90..0000000000 --- a/docs/reference/gtk/tmpl/gtkaboutdialog.sgml +++ /dev/null @@ -1,475 +0,0 @@ - -GtkAboutDialog - - -Display information about an application - - - -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 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 -<user@host>, URLs are -recognized by looking for http://url, with -url extending to the next space, tab or line break. - - -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: - - -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); - - -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 _("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: - - -gtk_show_about_dialog (NULL, - "program-name", "ExampleCode", - "logo", example_logo, - "title" _("About ExampleCode"), - NULL); - - -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. - - - - -#GTK_STOCK_ABOUT - - - - - - - -The GtkAboutDialog struct contains -only private fields and should not be directly accessed. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@Returns: - - - - - - - -@about: -@Returns: - - - - - - - -@about: -@name: - - - - - - - -@about: -@Returns: - - - - - - - -@about: -@name: - - - - - - - -@about: -@Returns: - - - - - - - -@about: -@version: - - - - - - - -@about: -@Returns: - - - - - - - -@about: -@copyright: - - - - - - - -@about: -@Returns: - - - - - - - -@about: -@comments: - - - - - - - -@about: -@Returns: - - - - - - - -@about: -@license: - - - - - - - -@about: -@Returns: - - - - - - - -@about: -@wrap_license: - - - - - - - -@about: -@Returns: - - - - - - - -@about: -@website: - - - - - - - -@about: -@Returns: - - - - - - - -@about: -@website_label: - - - - - - - -@about: -@Returns: - - - - - - - -@about: -@authors: - - - - - - - -@about: -@Returns: - - - - - - - -@about: -@artists: - - - - - - - -@about: -@Returns: - - - - - - - -@about: -@documenters: - - - - - - - -@about: -@Returns: - - - - - - - -@about: -@translator_credits: - - - - - - - -@about: -@Returns: - - - - - - - -@about: -@logo: - - - - - - - -@about: -@Returns: - - - - - - - -@about: -@icon_name: - - - - -The type of a function which is called when a URL or email -link is activated. - - -@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() - - - - - - - -@func: -@data: -@destroy: -@Returns: - - - - - - - -@func: -@data: -@destroy: -@Returns: - - - - - - - -@parent: -@first_property_name: -@Varargs: - - diff --git a/gtk/gtkaboutdialog.c b/gtk/gtkaboutdialog.c index 91d30fe344..6498d1df37 100644 --- a/gtk/gtkaboutdialog.c +++ b/gtk/gtkaboutdialog.c @@ -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 About option from + * the Help 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 + * host>, URLs are + * recognized by looking for http://url, with + * url extending to the next space, tab or line break. + * + * + * 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: + * + * + * 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); + * + * 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 _("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: + * + * + * gtk_show_about_dialog (NULL, + * "program-name", "ExampleCode", + * "logo", example_logo, + * "title" _("About ExampleCode"), + * NULL); + * + * 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 }; diff --git a/gtk/gtkaboutdialog.h b/gtk/gtkaboutdialog.h index 02f2fbec03..efb50b1cf0 100644 --- a/gtk/gtkaboutdialog.h +++ b/gtk/gtkaboutdialog.h @@ -43,6 +43,12 @@ G_BEGIN_DECLS typedef struct _GtkAboutDialog GtkAboutDialog; typedef struct _GtkAboutDialogClass GtkAboutDialogClass; +/** + * GtkAboutDialog: + * + * The GtkAboutDialog 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);