diff options
| -rw-r--r-- | docs/reference/gtk/tmpl/.gitignore | 2 | ||||
| -rw-r--r-- | docs/reference/gtk/tmpl/gtkdialog.sgml | 406 | ||||
| -rw-r--r-- | gtk/gtkdialog.c | 134 | ||||
| -rw-r--r-- | gtk/gtkdialog.h | 83 |
4 files changed, 183 insertions, 442 deletions
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 @@ -<!-- ##### SECTION Title ##### --> -GtkDialog - -<!-- ##### SECTION Short_Description ##### --> -Create popup windows - -<!-- ##### SECTION Long_Description ##### --> - -<para> -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. -</para> - -<para> -GTK+ treats a dialog as a window split vertically. The top section is a -#GtkVBox known as the <structfield>content_area</structfield>, and is -where widgets such as a #GtkLabel or a #GtkEntry should be packed. -The bottom area is known as the <structfield>action_area</structfield>. -This is generally used for packing buttons into the dialog which may -perform functions such as cancel, ok, or apply. -</para> - -<para> -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. -</para> - -<para> -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. -</para> - -<para> -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. -</para> - -<para> -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. -</para> - - -<para> -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. -</para> - -<para> -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. -<example> -<title>Simple <structname>GtkDialog</structname> usage.</title> -<programlisting> - -/* 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); -} - -</programlisting> -</example> -</para> - -<refsect2 id="GtkDialog-BUILDER-UI"><title>GtkDialog as GtkBuildable</title> -<para> -The GtkDialog implementation of the GtkBuildable interface exposes the -@vbox and @action_area as internal children with the names "vbox" and -"action_area". -</para> -<para> -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). -</para> -<example> -<title>A <structname>GtkDialog</structname> UI definition fragment.</title> -<programlisting><![CDATA[ -<object class="GtkDialog" id="dialog1"> - <child internal-child="vbox">" - <object class="GtkVBox" id="vbox"> - <child internal-child="action_area"> - <object class="GtkHButtonBox" id="button_box"> - <child> - <object class="GtkButton" id="button_cancel"/> - </child> - <child> - <object class="GtkButton" id="button_ok"/> - </child> - </object> - </child> - </object> - </child> - <action-widgets> - <action-widget response="3">button_ok</action-widget> - <action-widget response="-5">button_cancel</action-widget> - </action-widgets> -</object> -]]></programlisting> -</example> -</refsect2> - -<!-- ##### SECTION See_Also ##### --> - -<para> -<variablelist> -<varlistentry> -<term>#GtkVBox</term> -<listitem><para>Pack widgets vertically.</para></listitem> -</varlistentry> -<varlistentry> -<term>#GtkWindow</term> -<listitem><para>Alter the properties of your dialog box.</para></listitem> -</varlistentry> -<varlistentry> -<term>#GtkButton</term> -<listitem><para>Add them to the <structfield>action_area</structfield> to get a -response from the user.</para></listitem> -</varlistentry> -</variablelist> -</para> - -<!-- ##### SECTION Stability_Level ##### --> - - -<!-- ##### SECTION Image ##### --> - - -<!-- ##### STRUCT GtkDialog ##### --> -<para> -<structfield>vbox</structfield> is a #GtkVBox - the main part of the -dialog box. -</para> - -<para> -<structfield>action_area</structfield> is a #GtkHButtonBox packed below the -dividing #GtkHSeparator in the dialog. It is treated exactly the same -as any other #GtkHButtonBox. -</para> - - -<!-- ##### SIGNAL GtkDialog::close ##### --> -<para> - -</para> - -@dialog: the object which received the signal. - -<!-- ##### SIGNAL GtkDialog::response ##### --> -<para> - -</para> - -@dialog: -@arg1: - -<!-- ##### ARG GtkDialog:action-area-border ##### --> -<para> - -</para> - -<!-- ##### ARG GtkDialog:button-spacing ##### --> -<para> - -</para> - -<!-- ##### ARG GtkDialog:content-area-border ##### --> -<para> - -</para> - -<!-- ##### ARG GtkDialog:content-area-spacing ##### --> -<para> - -</para> - -<!-- ##### ENUM GtkDialogFlags ##### --> -<para> -Flags used to influence dialog construction. -</para> - -@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(). - -<!-- ##### ENUM GtkResponseType ##### --> -<para> -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. -</para> - -@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. - -<!-- ##### FUNCTION gtk_dialog_new ##### --> -<para> -Creates a new dialog box. Widgets should not be packed into this #GtkWindow -directly, but into the @vbox and @action_area, as described above. -</para> - -@void: -@Returns: a new #GtkDialog. - - -<!-- ##### FUNCTION gtk_dialog_new_with_buttons ##### --> -<para> - -</para> - -@title: -@parent: -@flags: -@first_button_text: -@Varargs: -@Returns: - - -<!-- ##### FUNCTION gtk_dialog_run ##### --> -<para> - -</para> - -@dialog: -@Returns: - - -<!-- ##### FUNCTION gtk_dialog_response ##### --> -<para> - -</para> - -@dialog: -@response_id: - - -<!-- ##### FUNCTION gtk_dialog_add_button ##### --> -<para> - -</para> - -@dialog: -@button_text: -@response_id: -@Returns: - - -<!-- ##### FUNCTION gtk_dialog_add_buttons ##### --> -<para> - -</para> - -@dialog: -@first_button_text: -@Varargs: - - -<!-- ##### FUNCTION gtk_dialog_add_action_widget ##### --> -<para> - -</para> - -@dialog: -@child: -@response_id: - - -<!-- ##### FUNCTION gtk_dialog_set_default_response ##### --> -<para> - -</para> - -@dialog: -@response_id: - - -<!-- ##### FUNCTION gtk_dialog_set_response_sensitive ##### --> -<para> - -</para> - -@dialog: -@response_id: -@setting: - - -<!-- ##### FUNCTION gtk_dialog_get_response_for_widget ##### --> -<para> - -</para> - -@dialog: -@widget: -@Returns: - - -<!-- ##### FUNCTION gtk_dialog_get_widget_for_response ##### --> -<para> - -</para> - -@dialog: -@response_id: -@Returns: - - -<!-- ##### FUNCTION gtk_dialog_get_action_area ##### --> -<para> - -</para> - -@dialog: -@Returns: - - -<!-- ##### FUNCTION gtk_dialog_get_content_area ##### --> -<para> - -</para> - -@dialog: -@Returns: - - -<!-- ##### FUNCTION gtk_alternative_dialog_button_order ##### --> -<para> - -</para> - -@screen: -@Returns: - - -<!-- ##### FUNCTION gtk_dialog_set_alternative_button_order ##### --> -<para> - -</para> - -@dialog: -@first_response_id: -@Varargs: - - -<!-- ##### FUNCTION gtk_dialog_set_alternative_button_order_from_array ##### --> -<para> - -</para> - -@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 + * <structfield>action_area</structfield>. 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. + * <example> + * <title>Simple GtkDialog usage</title> + * <programlisting> + * /* 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); + * } + * </programlisting> + * </example> + * + * <refsect2 id="GtkDialog-BUILDER-UI"><title>GtkDialog as GtkBuildable</title> + * <para> + * The GtkDialog implementation of the #GtkBuildable interface exposes the + * @vbox and @action_area as internal children with the names "vbox" and + * "action_area". + * </para> + * <para> + * 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). + * </para> + * <example> + * <title>A <structname>GtkDialog</structname> UI definition fragment.</title> + * <programlisting><![CDATA[ + * <object class="GtkDialog" id="dialog1"> + * <child internal-child="vbox">" + * <object class="GtkVBox" id="vbox"> + * <child internal-child="action_area"> + * <object class="GtkHButtonBox" id="button_box"> + * <child> + * <object class="GtkButton" id="button_cancel"/> + * </child> + * <child> + * <object class="GtkButton" id="button_ok"/> + * </child> + * </object> + * </child> + * </object> + * </child> + * <action-widgets> + * <action-widget response="3">button_ok</action-widget> + * <action-widget response="-5">button_cancel</action-widget> + * </action-widgets> + * </object> + * ]]></programlisting> + * </example> + * </refsect2> + */ 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 */ +/** + * 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() + * + * Flags used to influence 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 () */ + GTK_DIALOG_MODAL = 1 << 0, + GTK_DIALOG_DESTROY_WITH_PARENT = 1 << 1 } 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. +/** + * 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 * - * Typical usage is: - * if (gtk_dialog_run(dialog) == GTK_RESPONSE_ACCEPT) - * blah(); + * 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 returns this if a response widget has no response_id, - * or if the dialog gets programmatically hidden or destroyed. - */ - GTK_RESPONSE_NONE = -1, - - /* 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. */ + 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); |