From c00914967081d1f040a3e15f0aeb3067f8191632 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Tue, 4 Jan 2011 12:51:11 -0500 Subject: [PATCH] Move GtkDialog docs inline Based on a patch by Garrett Regier. https://bugzilla.gnome.org/show_bug.cgi?id=617312 --- docs/reference/gtk/tmpl/.gitignore | 2 + docs/reference/gtk/tmpl/gtkdialog.sgml | 406 ------------------------- gtk/gtkdialog.c | 134 ++++++++ gtk/gtkdialog.h | 89 +++--- 4 files changed, 186 insertions(+), 445 deletions(-) delete mode 100644 docs/reference/gtk/tmpl/gtkdialog.sgml diff --git a/docs/reference/gtk/tmpl/.gitignore b/docs/reference/gtk/tmpl/.gitignore index 24771fefd3..c3acd48305 100644 --- a/docs/reference/gtk/tmpl/.gitignore +++ b/docs/reference/gtk/tmpl/.gitignore @@ -16,9 +16,11 @@ gtkcolorsel.sgml gtkcombobox.sgml gtkcomboboxentry.sgml gtkcontainer.sgml +gtkdialog.sgml gtkeditable.sgml gtkentry.sgml gtkentrybuffer.sgml +gtkeventbox.sgml gtkhbox.sgml gtkiconview.sgml gtkimcontextsimple.sgml diff --git a/docs/reference/gtk/tmpl/gtkdialog.sgml b/docs/reference/gtk/tmpl/gtkdialog.sgml deleted file mode 100644 index 13c902f2ca..0000000000 --- a/docs/reference/gtk/tmpl/gtkdialog.sgml +++ /dev/null @@ -1,406 +0,0 @@ - -GtkDialog - - -Create popup windows - - - - -Dialog boxes are a convenient way to prompt the user for a small amount of -input, e.g. to display a message, ask a question, or anything else that does -not require extensive effort on the user's part. - - - -GTK+ treats a dialog as a window split vertically. The top section is a -#GtkVBox known as the content_area, and is -where widgets such as a #GtkLabel or a #GtkEntry should be packed. -The bottom area is known as the action_area. -This is generally used for packing buttons into the dialog which may -perform functions such as cancel, ok, or apply. - - - -GtkDialog boxes are created with a call to gtk_dialog_new() or -gtk_dialog_new_with_buttons(). gtk_dialog_new_with_buttons() is recommended; -it allows you to set the dialog title, some convenient flags, and add simple -buttons. - - - -If 'dialog' is a newly created dialog, the two primary areas of the window -can be accessed through gtk_dialog_get_content_area() and -gtk_dialog_get_action_area(), as can be seen from the example, below. - - - -A 'modal' dialog (that is, one which freezes the rest of the application from -user input), can be created by calling gtk_window_set_modal() on the dialog. Use -the GTK_WINDOW() macro to cast the widget returned from gtk_dialog_new() into a -#GtkWindow. When using gtk_dialog_new_with_buttons() you can also pass the -#GTK_DIALOG_MODAL flag to make a dialog modal. - - - -If you add buttons to #GtkDialog using gtk_dialog_new_with_buttons(), -gtk_dialog_add_button(), gtk_dialog_add_buttons(), or -gtk_dialog_add_action_widget(), clicking the button will emit a signal called -"response" with a response ID that you specified. GTK+ will never assign a -meaning to positive response IDs; these are entirely user-defined. But for -convenience, you can use the response IDs in the #GtkResponseType enumeration -(these all have values less than zero). If a dialog receives a delete event, -the "response" signal will be emitted with a response ID of #GTK_RESPONSE_DELETE_EVENT. - - - - -If you want to block waiting for a dialog to return before returning control -flow to your code, you can call gtk_dialog_run(). This function enters a -recursive main loop and waits for the user to respond to the dialog, returning the -response ID corresponding to the button the user clicked. - - - -For the simple dialog in the following example, in reality you'd probably use -#GtkMessageDialog to save yourself some effort. But you'd need to create the -dialog contents manually if you had more than a simple message in the dialog. - -Simple <structname>GtkDialog</structname> usage. - - -/* Function to open a dialog box displaying the message provided. */ - -void quick_message (gchar *message) { - - GtkWidget *dialog, *label, *content_area; - - /* Create the widgets */ - - dialog = gtk_dialog_new_with_buttons ("Message", - main_application_window, - GTK_DIALOG_DESTROY_WITH_PARENT, - GTK_STOCK_OK, - GTK_RESPONSE_NONE, - NULL); - content_area = gtk_dialog_get_content_area (GTK_DIALOG (dialog)); - label = gtk_label_new (message); - - /* Ensure that the dialog box is destroyed when the user responds. */ - - g_signal_connect_swapped (dialog, - "response", - G_CALLBACK (gtk_widget_destroy), - dialog); - - /* Add the label, and show everything we've added to the dialog. */ - - gtk_container_add (GTK_CONTAINER (content_area), label); - gtk_widget_show_all (dialog); -} - - - - - -GtkDialog as GtkBuildable - -The GtkDialog implementation of the GtkBuildable interface exposes the -@vbox and @action_area as internal children with the names "vbox" and -"action_area". - - -GtkDialog supports a custom <action-widgets> element, which -can contain multiple <action-widget> elements. The "response" -attribute specifies a numeric response, and the content of the element -is the id of widget (which should be a child of the dialogs @action_area). - - -A <structname>GtkDialog</structname> UI definition fragment. - - " - - - - - - - - - - - - - - - button_ok - button_cancel - - -]]> - - - - - - - - -#GtkVBox -Pack widgets vertically. - - -#GtkWindow -Alter the properties of your dialog box. - - -#GtkButton -Add them to the action_area to get a -response from the user. - - - - - - - - - - - - -vbox is a #GtkVBox - the main part of the -dialog box. - - - -action_area is a #GtkHButtonBox packed below the -dividing #GtkHSeparator in the dialog. It is treated exactly the same -as any other #GtkHButtonBox. - - - - - - - - -@dialog: the object which received the signal. - - - - - - -@dialog: -@arg1: - - - - - - - - - - - - - - - - - - - - - - - -Flags used to influence dialog construction. - - -@GTK_DIALOG_MODAL: Make the constructed dialog modal, - see gtk_window_set_modal(). -@GTK_DIALOG_DESTROY_WITH_PARENT: Destroy the dialog when its - parent is destroyed, see gtk_window_set_destroy_with_parent(). - - - -Predefined values for use as response ids in gtk_dialog_add_button(). -All predefined values are negative, GTK+ leaves positive values for -application-defined response ids. - - -@GTK_RESPONSE_NONE: Returned if an action widget has no response id, or if - the dialog gets programmatically hidden or destroyed. -@GTK_RESPONSE_REJECT: Generic response id, not used by GTK+ dialogs. -@GTK_RESPONSE_ACCEPT: Generic response id, not used by GTK+ dialogs. -@GTK_RESPONSE_DELETE_EVENT: Returned if the dialog is deleted. -@GTK_RESPONSE_OK: Returned by OK buttons in GTK+ dialogs. -@GTK_RESPONSE_CANCEL: Returned by Cancel buttons in GTK+ dialogs. -@GTK_RESPONSE_CLOSE: Returned by Close buttons in GTK+ dialogs. -@GTK_RESPONSE_YES: Returned by Yes buttons in GTK+ dialogs. -@GTK_RESPONSE_NO: Returned by No buttons in GTK+ dialogs. -@GTK_RESPONSE_APPLY: Returned by Apply buttons in GTK+ dialogs. -@GTK_RESPONSE_HELP: Returned by Help buttons in GTK+ dialogs. - - - -Creates a new dialog box. Widgets should not be packed into this #GtkWindow -directly, but into the @vbox and @action_area, as described above. - - -@void: -@Returns: a new #GtkDialog. - - - - - - - -@title: -@parent: -@flags: -@first_button_text: -@Varargs: -@Returns: - - - - - - - -@dialog: -@Returns: - - - - - - - -@dialog: -@response_id: - - - - - - - -@dialog: -@button_text: -@response_id: -@Returns: - - - - - - - -@dialog: -@first_button_text: -@Varargs: - - - - - - - -@dialog: -@child: -@response_id: - - - - - - - -@dialog: -@response_id: - - - - - - - -@dialog: -@response_id: -@setting: - - - - - - - -@dialog: -@widget: -@Returns: - - - - - - - -@dialog: -@response_id: -@Returns: - - - - - - - -@dialog: -@Returns: - - - - - - - -@dialog: -@Returns: - - - - - - - -@screen: -@Returns: - - - - - - - -@dialog: -@first_response_id: -@Varargs: - - - - - - - -@dialog: -@n_params: -@new_order: - - diff --git a/gtk/gtkdialog.c b/gtk/gtkdialog.c index 1011848a48..424b2d232e 100644 --- a/gtk/gtkdialog.c +++ b/gtk/gtkdialog.c @@ -41,6 +41,130 @@ #include "gtkprivate.h" #include "gtkbuildable.h" +/** + * SECTION:gtkdialog + * @Short_description: Create popup windows + * @Title: GtkDialog + * @See_also: #GtkVBox, #GtkWindow, #GtkButton + * + * Dialog boxes are a convenient way to prompt the user for a small amount + * of input, e.g. to display a message, ask a question, or anything else + * that does not require extensive effort on the user's part. + * + * GTK+ treats a dialog as a window split vertically. The top section is a + * #GtkVBox, and is where widgets such as a #GtkLabel or a #GtkEntry should + * be packed. The bottom area is known as the + * action_area. This is generally used for + * packing buttons into the dialog which may perform functions such as + * cancel, ok, or apply. The two areas are separated by a #GtkHSeparator. + * + * #GtkDialog boxes are created with a call to gtk_dialog_new() or + * gtk_dialog_new_with_buttons(). gtk_dialog_new_with_buttons() is + * recommended; it allows you to set the dialog title, some convenient flags, + * and add simple buttons. + * + * If 'dialog' is a newly created dialog, the two primary areas of the + * window can be accessed through gtk_dialog_get_content_area() and + * gtk_dialog_get_action_area(), as can be seen from the example below. + * + * A 'modal' dialog (that is, one which freezes the rest of the application + * from user input), can be created by calling gtk_window_set_modal() on the + * dialog. Use the GTK_WINDOW() macro to cast the widget returned from + * gtk_dialog_new() into a #GtkWindow. When using gtk_dialog_new_with_buttons() + * you can also pass the #GTK_DIALOG_MODAL flag to make a dialog modal. + * + * If you add buttons to #GtkDialog using gtk_dialog_new_with_buttons(), + * gtk_dialog_add_button(), gtk_dialog_add_buttons(), or + * gtk_dialog_add_action_widget(), clicking the button will emit a signal + * called #GtkDialog::response with a response ID that you specified. GTK+ + * will never assign a meaning to positive response IDs; these are entirely + * user-defined. But for convenience, you can use the response IDs in the + * #GtkResponseType enumeration (these all have values less than zero). If + * a dialog receives a delete event, the #GtkDialog::response signal will + * be emitted with a response ID of #GTK_RESPONSE_DELETE_EVENT. + * + * If you want to block waiting for a dialog to return before returning + * control flow to your code, you can call gtk_dialog_run(). This function + * enters a recursive main loop and waits for the user to respond to the + * dialog, returning the response ID corresponding to the button the user + * clicked. + * + * For the simple dialog in the following example, in reality you'd probably + * use #GtkMessageDialog to save yourself some effort. But you'd need to + * create the dialog contents manually if you had more than a simple message + * in the dialog. + * + * Simple GtkDialog usage + * + * /* Function to open a dialog box displaying the message provided. */ + * void + * quick_message (gchar *message) + * { + * GtkWidget *dialog, *label, *content_area; + * + * /* Create the widgets */ + * dialog = gtk_dialog_new_with_buttons ("Message", + * main_application_window, + * GTK_DIALOG_DESTROY_WITH_PARENT, + * GTK_STOCK_OK, + * GTK_RESPONSE_NONE, + * NULL); + * content_area = gtk_dialog_get_content_area (GTK_DIALOG (dialog)); + * label = gtk_label_new (message); + * + * /* Ensure that the dialog box is destroyed when the user responds */ + * g_signal_connect_swapped (dialog, + * "response", + * G_CALLBACK (gtk_widget_destroy), + * dialog); + * + * /* Add the label, and show everything we've added to the dialog */ + * + * gtk_container_add (GTK_CONTAINER (content_area), label); + * gtk_widget_show_all (dialog); + * } + * + * + * + * GtkDialog as GtkBuildable + * + * The GtkDialog implementation of the #GtkBuildable interface exposes the + * @vbox and @action_area as internal children with the names "vbox" and + * "action_area". + * + * + * GtkDialog supports a custom <action-widgets> element, which + * can contain multiple <action-widget> elements. The "response" + * attribute specifies a numeric response, and the content of the element + * is the id of widget (which should be a child of the dialogs @action_area). + * + * + * A <structname>GtkDialog</structname> UI definition fragment. + * + * " + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * button_ok + * button_cancel + * + * + * ]]> + * + * + */ struct _GtkDialogPrivate { @@ -430,6 +554,16 @@ gtk_dialog_close (GtkDialog *dialog) gdk_event_free (event); } +/** + * gtk_dialog_new: + * + * Creates a new dialog box. + * + * Widgets should not be packed into this #GtkWindow + * directly, but into the @vbox and @action_area, as described above. + * + * Returns: the new dialog as a #GtkWidget + */ GtkWidget* gtk_dialog_new (void) { diff --git a/gtk/gtkdialog.h b/gtk/gtkdialog.h index 9069d22fc8..ab1d143e2d 100644 --- a/gtk/gtkdialog.h +++ b/gtk/gtkdialog.h @@ -37,48 +37,53 @@ G_BEGIN_DECLS -/* Parameters for dialog construction */ -typedef enum -{ - GTK_DIALOG_MODAL = 1 << 0, /* call gtk_window_set_modal (win, TRUE) */ - GTK_DIALOG_DESTROY_WITH_PARENT = 1 << 1 /* call gtk_window_set_destroy_with_parent () */ -} GtkDialogFlags; - -/* Convenience enum to use for response_id's. Positive values are - * totally user-interpreted. GTK will sometimes return - * GTK_RESPONSE_NONE if no response_id is available. +/** + * GtkDialogFlags: + * @GTK_DIALOG_MODAL: Make the constructed dialog modal, + * see gtk_window_set_modal() + * @GTK_DIALOG_DESTROY_WITH_PARENT: Destroy the dialog when its + * parent is destroyed, see gtk_window_set_destroy_with_parent() * - * Typical usage is: - * if (gtk_dialog_run(dialog) == GTK_RESPONSE_ACCEPT) - * blah(); + * Flags used to influence dialog construction. */ typedef enum { - /* GTK returns this if a response widget has no response_id, - * or if the dialog gets programmatically hidden or destroyed. - */ - GTK_RESPONSE_NONE = -1, + GTK_DIALOG_MODAL = 1 << 0, + GTK_DIALOG_DESTROY_WITH_PARENT = 1 << 1 +} GtkDialogFlags; - /* GTK won't return these unless you pass them in - * as the response for an action widget. They are - * for your convenience. - */ - GTK_RESPONSE_REJECT = -2, - GTK_RESPONSE_ACCEPT = -3, - - /* If the dialog is deleted. */ +/** + * GtkResponseType: + * @GTK_RESPONSE_NONE: Returned if an action widget has no response id, + * or if the dialog gets programmatically hidden or destroyed + * @GTK_RESPONSE_REJECT: Generic response id, not used by GTK+ dialogs + * @GTK_RESPONSE_ACCEPT: Generic response id, not used by GTK+ dialogs + * @GTK_RESPONSE_DELETE_EVENT: Returned if the dialog is deleted + * @GTK_RESPONSE_OK: Returned by OK buttons in GTK+ dialogs + * @GTK_RESPONSE_CANCEL: Returned by Cancel buttons in GTK+ dialogs + * @GTK_RESPONSE_CLOSE: Returned by Close buttons in GTK+ dialogs + * @GTK_RESPONSE_YES: Returned by Yes buttons in GTK+ dialogs + * @GTK_RESPONSE_NO: Returned by No buttons in GTK+ dialogs + * @GTK_RESPONSE_APPLY: Returned by Apply buttons in GTK+ dialogs + * @GTK_RESPONSE_HELP: Returned by Help buttons in GTK+ dialogs + * + * Predefined values for use as response ids in gtk_dialog_add_button(). + * All predefined values are negative, GTK+ leaves positive values for + * application-defined response ids. + */ +typedef enum +{ + GTK_RESPONSE_NONE = -1, + GTK_RESPONSE_REJECT = -2, + GTK_RESPONSE_ACCEPT = -3, GTK_RESPONSE_DELETE_EVENT = -4, - - /* These are returned from GTK dialogs, and you can also use them - * yourself if you like. - */ - GTK_RESPONSE_OK = -5, - GTK_RESPONSE_CANCEL = -6, - GTK_RESPONSE_CLOSE = -7, - GTK_RESPONSE_YES = -8, - GTK_RESPONSE_NO = -9, - GTK_RESPONSE_APPLY = -10, - GTK_RESPONSE_HELP = -11 + GTK_RESPONSE_OK = -5, + GTK_RESPONSE_CANCEL = -6, + GTK_RESPONSE_CLOSE = -7, + GTK_RESPONSE_YES = -8, + GTK_RESPONSE_NO = -9, + GTK_RESPONSE_APPLY = -10, + GTK_RESPONSE_HELP = -11 } GtkResponseType; @@ -94,6 +99,12 @@ typedef struct _GtkDialog GtkDialog; typedef struct _GtkDialogPrivate GtkDialogPrivate; typedef struct _GtkDialogClass GtkDialogClass; +/** + * GtkDialog: + * + * The GtkDialog struct contains only private fields + * and should not be directly accessed. + */ struct _GtkDialog { GtkWindow window; @@ -147,12 +158,12 @@ void gtk_dialog_set_default_response (GtkDialog *dialog, GtkWidget* gtk_dialog_get_widget_for_response (GtkDialog *dialog, gint response_id); gint gtk_dialog_get_response_for_widget (GtkDialog *dialog, - GtkWidget *widget); + GtkWidget *widget); gboolean gtk_alternative_dialog_button_order (GdkScreen *screen); void gtk_dialog_set_alternative_button_order (GtkDialog *dialog, - gint first_response_id, - ...); + gint first_response_id, + ...); void gtk_dialog_set_alternative_button_order_from_array (GtkDialog *dialog, gint n_params, gint *new_order);