Next: , Previous: Overview, Up: Top

2 GtkDialog

Create popup windows

2.1 Overview

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 <gtk-vbox>, and is where widgets such as a <gtk-label> or a <gtk-entry> should be packed. The bottom area is known as the . 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 <gtk-hseparator>.

<gtk-dialog> 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 as ‘GTK_DIALOG(dialog)->vbox’ and ‘GTK_DIALOG(dialog)->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 <gtk-window>. 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 <gtk-dialog> 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 <gtk-response-type> 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 <gtk-message-dialog> 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. 

     
     
     /* Function to open a dialog box displaying the message provided. */
     
     void quick_message (gchar *message) {
     
        GtkWidget *dialog, *label;
     
        /* 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);
        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 (GTK_DIALOG(dialog)->vbox),
                           label);
        gtk_widget_show_all (dialog);
     }

2.2 Usage

— Class: <gtk-dialog>

Derives from <gtk-window>.

This class defines the following slots:

has-separator
The dialog has a separator bar above its buttons
— Signal on <gtk-dialog>: response (arg0 <gint>)

Emitted when an action widget is clicked, the dialog receives a delete event, or the application programmer calls gtk-dialog-response. On a delete event, the response ID is <gtk-response-none>. Otherwise, it depends on which action widget was clicked.

— Signal on <gtk-dialog>: close
— Function: gtk-dialog-run (self <gtk-dialog>) ⇒  (ret int)
— Method: run

Blocks in a recursive main loop until the dialog either emits the response signal, or is destroyed. If the dialog is destroyed during the call to gtk-dialog-run, gtk_dialog_returns <gtk-response-none>. Otherwise, it returns the response ID from the "response" signal emission. Before entering the recursive main loop, gtk-dialog-run calls gtk-widget-show on the dialog for you. Note that you still need to show any children of the dialog yourself.

During gtk-dialog-run, the default behavior of "delete_event" is disabled; if the dialog receives "delete_event", it will not be destroyed as windows usually are, and gtk-dialog-run will return <gtk-response-delete-event>. Also, during gtk-dialog-run the dialog will be modal. You can force gtk-dialog-run to return at any time by calling gtk-dialog-response to emit the "response" signal. Destroying the dialog during gtk-dialog-run is a very bad idea, because your post-run code won't know whether the dialog was destroyed or not.

After gtk-dialog-run returns, you are responsible for hiding or destroying the dialog if you wish to do so.

Typical usage of this function might be: 

          
            gint result = gtk_dialog_run (GTK_DIALOG (dialog));
            switch (result)
              {
                case GTK_RESPONSE_ACCEPT:
                   do_application_specific_something ();
                   break;
                default:
                   do_nothing_since_dialog_was_cancelled ();
                   break;
              }
            gtk_widget_destroy (dialog);

Note that even though the recursive main loop gives the effect of a modal dialog (it prevents the user from interacting with other windows in the same window group while the dialog is run), callbacks such as timeouts, IO channel watches, DND drops, etc, will be triggered during a gtk-dialog-run call.

dialog
a <gtk-dialog>
ret
response ID
— Function: gtk-dialog-response (self <gtk-dialog>) (response_id int)
— Method: response

Emits the "response" signal with the given response ID. Used to indicate that the user has responded to the dialog in some way; typically either you or gtk-dialog-run will be monitoring the "response" signal and take appropriate action.

dialog
a <gtk-dialog>
response-id
response ID
— Function: gtk-dialog-add-button (self <gtk-dialog>) (button_text mchars) (response_id int) ⇒  (ret <gtk-widget>)
— Method: add-button

Adds a button with the given text (or a stock button, if button-text is a stock ID) and sets things up so that clicking the button will emit the "response" signal with the given response-id. The button is appended to the end of the dialog's action area. The button widget is returned, but usually you don't need it.

dialog
a <gtk-dialog>
button-text
text of button, or stock ID
response-id
response ID for the button
ret
the button widget that was added
— Function: gtk-dialog-add-action-widget (self <gtk-dialog>) (child <gtk-widget>) (response_id int)
— Method: add-action-widget

Adds an activatable widget to the action area of a <gtk-dialog>, connecting a signal handler that will emit the "response" signal on the dialog when the widget is activated. The widget is appended to the end of the dialog's action area. If you want to add a non-activatable widget, simply pack it into the ‘action_area’ field of the <gtk-dialog> struct.

dialog
a <gtk-dialog>
child
an activatable widget
response-id
response ID for child
— Function: gtk-dialog-get-has-separator (self <gtk-dialog>) ⇒  (ret bool)
— Method: get-has-separator

Accessor for whether the dialog has a separator.

dialog
a <gtk-dialog>
ret
‘#t’ if the dialog has a separator
— Function: gtk-dialog-set-default-response (self <gtk-dialog>) (response_id int)
— Method: set-default-response

Sets the last widget in the dialog's action area with the given response-id as the default widget for the dialog. Pressing "Enter" normally activates the default widget.

dialog
a <gtk-dialog>
response-id
a response ID
— Function: gtk-dialog-set-has-separator (self <gtk-dialog>) (setting bool)
— Method: set-has-separator

Sets whether the dialog has a separator above the buttons. ‘#t’ by default.

dialog
a <gtk-dialog>
setting
‘#t’ to have a separator
— Function: gtk-dialog-set-response-sensitive (self <gtk-dialog>) (response_id int) (setting bool)
— Method: set-response-sensitive

Calls ‘gtk_widget_set_sensitive (widget, setting)’ for each widget in the dialog's action area with the given response-id. A convenient way to sensitize/desensitize dialog buttons.

dialog
a <gtk-dialog>
response-id
a response ID
setting
‘#t’ for sensitive
— Function: gtk-dialog-get-response-for-widget (self <gtk-dialog>) (widget <gtk-widget>) ⇒  (ret int)
— Method: get-response-for-widget

Gets the response id of a widget in the action area of a dialog.

dialog
a <gtk-dialog>
widget
a widget in the action area of dialog
ret
the response id of widget, or ‘GTK_RESPONSE_NONE’ if widget doesn't have a response id set.

Since 2.8

— Function: gtk-alternative-dialog-button-order (screen <gdk-screen>) ⇒  (ret bool)

Returns ‘#t’ if dialogs are expected to use an alternative button order on the screen screen. See gtk-dialog-set-alternative-button-order for more details about alternative button order.

If you need to use this function, you should probably connect to the ::notify:gtk-alternative-button-order signal on the <gtk-settings> object associated to screen, in order to be notified if the button order setting changes.

screen
a <gdk-screen>, or ‘#f’ to use the default screen
ret
Whether the alternative button order should be used

Since 2.6