GTK+ Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# GtkDialog

## Name

GtkDialog -- create popup windows.

## Synopsis

    #include <gtk/gtk.h>

    struct      GtkDialog;
    struct      GtkDialogButton;
    GtkWidget*  gtk_dialog_new                  (void);

## Object Hierarchy

      GtkObject
       +----GtkWidget
             +----GtkContainer
                   +----GtkBin
                         +----GtkWindow
                               +----GtkDialog

## Description

Dialog boxes are a convenient way to prompt the user for a small amount of input, eg. 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 horizontally. The top section is a GtkVBox, and is where widgets such as a GtkLabel or a GtkEntry should be packed. The second 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().

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 GtkWindow.

Example 1. Using a GtkDialog to keep the user informed.

    /* Function to open a dialog box displaying the message provided. */

    void quick_message(gchar *message) {

       GtkWidget *dialog, *label, *okay_button;

       /* Create the widgets */

       dialog = gtk_dialog_new();
       label = gtk_label_new (message);
       okay_button = gtk_button_new_with_label("Okay");

       /* Ensure that the dialog box is destroyed when the user clicks ok. */

       gtk_signal_connect_object (GTK_OBJECT (okay_button), "clicked",
                                  GTK_SIGNAL_FUNC (gtk_widget_destroy), dialog);
       gtk_container_add (GTK_CONTAINER (GTK_DIALOG(dialog)->action_area),
                          okay_button);

       /* 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);
    }

## Details

### struct GtkDialog

    struct GtkDialog;

`window` is a GtkWindow, but should not be modified directly, (use the functions provided, such as gtk_window_set_title(). See the GtkWindow section for more).

`vbox` is a GtkVBox - the main part of the dialog box.

`action_area` is a GtkHBox packed below the dividing GtkHSeparator in the dialog. It is treated exactly the same as any other GtkHBox.

### struct GtkDialogButton

    struct GtkDialogButton;

Deprecated.

### gtk_dialog_new ()

    GtkWidget*  gtk_dialog_new                  (void);

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 : | a GtkWidget - the newly created dialog box.

## See Also

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.

<<< Previous Page | Home | Up | Next Page >>>
GtkData | GtkDrawingArea