Commit 95fd5011 authored by Javier Jardón's avatar Javier Jardón

Move documentation to inline comments: GtkMessageDialog

Also, add a note about GTK_BUTTONS_OK, GTK_BUTTONS_YES_NO
and GTK_BUTTONS_OK_CANCEL are discouraged by the GNOME HIG.

https://bugzilla.gnome.org/show_bug.cgi?id=597865
parent 51a1af7a
<!-- ##### SECTION Title ##### -->
GtkMessageDialog
<!-- ##### SECTION Short_Description ##### -->
A convenient message window
<!-- ##### SECTION Long_Description ##### -->
<para>
#GtkMessageDialog presents a dialog with an image representing the type of
message (Error, Question, etc.) alongside some message text. It's simply a
convenience widget; you could construct the equivalent of #GtkMessageDialog
from #GtkDialog without too much effort, but #GtkMessageDialog saves typing.
</para>
<para>
The easiest way to do a modal message dialog is to use gtk_dialog_run(), though
you can also pass in the %GTK_DIALOG_MODAL flag, gtk_dialog_run() automatically
makes the dialog modal and waits for the user to respond to it. gtk_dialog_run()
returns when any dialog button is clicked.
<example>
<title>A modal dialog.</title>
<programlisting>
dialog = gtk_message_dialog_new (main_application_window,
GTK_DIALOG_DESTROY_WITH_PARENT,
GTK_MESSAGE_ERROR,
GTK_BUTTONS_CLOSE,
"Error loading file '&percnt;s': &percnt;s",
filename, g_strerror (errno));
gtk_dialog_run (GTK_DIALOG (dialog));
gtk_widget_destroy (dialog);
</programlisting>
</example>
</para>
<para>
You might do a non-modal #GtkMessageDialog as follows:
<example>
<title>A non-modal dialog.</title>
<programlisting>
dialog = gtk_message_dialog_new (main_application_window,
GTK_DIALOG_DESTROY_WITH_PARENT,
GTK_MESSAGE_ERROR,
GTK_BUTTONS_CLOSE,
"Error loading file '&percnt;s': &percnt;s",
filename, g_strerror (errno));
/* Destroy the dialog when the user responds to it (e.g. clicks a button) */
g_signal_connect_swapped (dialog, "response",
G_CALLBACK (gtk_widget_destroy),
dialog);
</programlisting>
</example>
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
#GtkDialog
</para>
<!-- ##### SECTION Stability_Level ##### -->
<!-- ##### STRUCT GtkMessageDialog ##### -->
<para>
</para>
<!-- ##### ARG GtkMessageDialog:buttons ##### -->
<para>
</para>
<!-- ##### ARG GtkMessageDialog:image ##### -->
<para>
</para>
<!-- ##### ARG GtkMessageDialog:message-type ##### -->
<para>
</para>
<!-- ##### ARG GtkMessageDialog:secondary-text ##### -->
<para>
</para>
<!-- ##### ARG GtkMessageDialog:secondary-use-markup ##### -->
<para>
</para>
<!-- ##### ARG GtkMessageDialog:text ##### -->
<para>
</para>
<!-- ##### ARG GtkMessageDialog:use-markup ##### -->
<para>
</para>
<!-- ##### ARG GtkMessageDialog:message-border ##### -->
<para>
</para>
<!-- ##### ARG GtkMessageDialog:use-separator ##### -->
<para>
</para>
<!-- ##### ENUM GtkMessageType ##### -->
<para>
The type of message being displayed in the dialog.
</para>
@GTK_MESSAGE_INFO: Informational message
@GTK_MESSAGE_WARNING: Nonfatal warning message
@GTK_MESSAGE_QUESTION: Question requiring a choice
@GTK_MESSAGE_ERROR: Fatal error message
@GTK_MESSAGE_OTHER: None of the above, doesn't get an icon
<!-- ##### ENUM GtkButtonsType ##### -->
<para>
Prebuilt sets of buttons for the dialog. If
none of these choices are appropriate, simply use %GTK_BUTTONS_NONE
then call gtk_dialog_add_buttons().
</para>
@GTK_BUTTONS_NONE: no buttons at all
@GTK_BUTTONS_OK: an OK button
@GTK_BUTTONS_CLOSE: a Close button
@GTK_BUTTONS_CANCEL: a Cancel button
@GTK_BUTTONS_YES_NO: Yes and No buttons
@GTK_BUTTONS_OK_CANCEL: OK and Cancel buttons
<!-- ##### FUNCTION gtk_message_dialog_new ##### -->
<para>
</para>
@parent:
@flags:
@type:
@buttons:
@message_format:
@Varargs:
@Returns:
<!-- ##### FUNCTION gtk_message_dialog_new_with_markup ##### -->
<para>
</para>
@parent:
@flags:
@type:
@buttons:
@message_format:
@Varargs:
@Returns:
<!-- ##### FUNCTION gtk_message_dialog_set_markup ##### -->
<para>
</para>
@message_dialog:
@str:
<!-- ##### FUNCTION gtk_message_dialog_set_image ##### -->
<para>
</para>
@dialog:
@image:
<!-- ##### FUNCTION gtk_message_dialog_get_image ##### -->
<para>
</para>
@dialog:
@Returns:
<!-- ##### FUNCTION gtk_message_dialog_format_secondary_text ##### -->
<para>
</para>
@message_dialog:
@message_format:
@Varargs:
<!-- ##### FUNCTION gtk_message_dialog_format_secondary_markup ##### -->
<para>
</para>
@message_dialog:
@message_format:
@Varargs:
......@@ -208,6 +208,16 @@ typedef enum
GTK_MENU_DIR_PREV
} GtkMenuDirectionType;
/**
* GtkMessageType:
* @GTK_MESSAGE_INFO: Informational message
* @GTK_MESSAGE_WARNING: Nonfatal warning message
* @GTK_MESSAGE_QUESTION: Question requiring a choice
* @GTK_MESSAGE_ERROR: Fatal error message
* @GTK_MESSAGE_OTHER: None of the above, doesn't get an icon
*
* The type of message being displayed in the dialog.
*/
typedef enum
{
GTK_MESSAGE_INFO,
......
......@@ -40,6 +40,53 @@
#include "gtkprivate.h"
#include "gtkalias.h"
/**
* SECTION:gtkmessagedialog
* @Short_description: A convenient message window
* @Title: GtkMessageDialog
* @See_also:#GtkDialog
*
* #GtkMessageDialog presents a dialog with an image representing the type of
* message (Error, Question, etc.) alongside some message text. It's simply a
* convenience widget; you could construct the equivalent of #GtkMessageDialog
* from #GtkDialog without too much effort, but #GtkMessageDialog saves typing.
*
* The easiest way to do a modal message dialog is to use gtk_dialog_run(), though
* you can also pass in the %GTK_DIALOG_MODAL flag, gtk_dialog_run() automatically
* makes the dialog modal and waits for the user to respond to it. gtk_dialog_run()
* returns when any dialog button is clicked.
* <example>
* <title>A modal dialog.</title>
* <programlisting>
* dialog = gtk_message_dialog_new (main_application_window,
* GTK_DIALOG_DESTROY_WITH_PARENT,
* GTK_MESSAGE_ERROR,
* GTK_BUTTONS_CLOSE,
* "Error loading file '&percnt;s': &percnt;s",
* filename, g_strerror (errno));
* gtk_dialog_run (GTK_DIALOG (dialog));
* gtk_widget_destroy (dialog);
* </programlisting>
* </example>
* You might do a non-modal #GtkMessageDialog as follows:
* <example>
* <title>A non-modal dialog.</title>
* <programlisting>
* dialog = gtk_message_dialog_new (main_application_window,
* GTK_DIALOG_DESTROY_WITH_PARENT,
* GTK_MESSAGE_ERROR,
* GTK_BUTTONS_CLOSE,
* "Error loading file '&percnt;s': &percnt;s",
* filename, g_strerror (errno));
*
* /&ast; Destroy the dialog when the user responds to it (e.g. clicks a button) &ast;/
* g_signal_connect_swapped (dialog, "response",
* G_CALLBACK (gtk_widget_destroy),
* dialog);
* </programlisting>
* </example>
*/
#define GTK_MESSAGE_DIALOG_GET_PRIVATE(obj) (G_TYPE_INSTANCE_GET_PRIVATE ((obj), GTK_TYPE_MESSAGE_DIALOG, GtkMessageDialogPrivate))
typedef struct _GtkMessageDialogPrivate GtkMessageDialogPrivate;
......
......@@ -36,15 +36,6 @@
G_BEGIN_DECLS
typedef enum
{
GTK_BUTTONS_NONE,
GTK_BUTTONS_OK,
GTK_BUTTONS_CLOSE,
GTK_BUTTONS_CANCEL,
GTK_BUTTONS_YES_NO,
GTK_BUTTONS_OK_CANCEL
} GtkButtonsType;
#define GTK_TYPE_MESSAGE_DIALOG (gtk_message_dialog_get_type ())
#define GTK_MESSAGE_DIALOG(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), GTK_TYPE_MESSAGE_DIALOG, GtkMessageDialog))
......@@ -77,6 +68,34 @@ struct _GtkMessageDialogClass
void (*_gtk_reserved4) (void);
};
/**
* GtkButtonsType:
* @GTK_BUTTONS_NONE: no buttons at all
* @GTK_BUTTONS_OK: an OK button
* @GTK_BUTTONS_CLOSE: a Close button
* @GTK_BUTTONS_CANCEL: a Cancel button
* @GTK_BUTTONS_YES_NO: Yes and No buttons
* @GTK_BUTTONS_OK_CANCEL: OK and Cancel buttons
*
* Prebuilt sets of buttons for the dialog. If
* none of these choices are appropriate, simply use %GTK_BUTTONS_NONE
* then call gtk_dialog_add_buttons().
* <note>
* Please note that %GTK_BUTTONS_OK, %GTK_BUTTONS_YES_NO
* and %GTK_BUTTONS_OK_CANCEL are discouraged by the
* <ulink url="http://library.gnome.org/devel/hig-book/stable/">GNOME HIG</ulink>.
* </note>
*/
typedef enum
{
GTK_BUTTONS_NONE,
GTK_BUTTONS_OK,
GTK_BUTTONS_CLOSE,
GTK_BUTTONS_CANCEL,
GTK_BUTTONS_YES_NO,
GTK_BUTTONS_OK_CANCEL
} GtkButtonsType;
GType gtk_message_dialog_get_type (void) G_GNUC_CONST;
GtkWidget* gtk_message_dialog_new (GtkWindow *parent,
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment