Dialog

open class Dialog : Window, DialogProtocol

Dialogs are a convenient way to prompt the user for a small amount of input.

An example GtkDialog

Typical uses are to display a message, ask a question, or anything else that does not require extensive effort on the user’s part.

The main area of a GtkDialog is called the “content area”, and is yours to populate with widgets such a GtkLabel or GtkEntry, to present your information, questions, or tasks to the user.

In addition, dialogs allow you to add “action widgets”. Most commonly, action widgets are buttons. Depending on the platform, action widgets may be presented in the header bar at the top of the window, or at the bottom of the window. To add action widgets, create your GtkDialog using [ctorGtk.Dialog.new_with_buttons], or use [methodGtk.Dialog.add_button], [methodGtk.Dialog.add_buttons], or [methodGtk.Dialog.add_action_widget].

GtkDialogs uses some heuristics to decide whether to add a close button to the window decorations. If any of the action buttons use the response ID GTK_RESPONSE_CLOSE or GTK_RESPONSE_CANCEL, the close button is omitted.

Clicking a button that was added as an action widget will emit the [signalGtk.Dialog::response] signal 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 [enumGtk.ResponseType] enumeration (these all have values less than zero). If a dialog receives a delete event, the [signalGtk.Dialog::response] signal will be emitted with the GTK_RESPONSE_DELETE_EVENT response ID.

Dialogs are created with a call to [ctorGtk.Dialog.new] or [ctorGtk.Dialog.new_with_buttons]. The latter is recommended; it allows you to set the dialog title, some convenient flags, and add buttons.

A “modal” dialog (that is, one which freezes the rest of the application from user input), can be created by calling [methodGtk.Window.set_modal] on the dialog. When using [ctorGtk.Dialog.new_with_buttons], you can also pass the GTK_DIALOG_MODAL flag to make a dialog modal.

For the simple dialog in the following example, a [classGtk.MessageDialog] would save some effort. But you’d need to create the dialog contents manually if you had more than a simple message in the dialog.

An example for simple GtkDialog usage:

// Function to open a dialog box with a message
void
quick_message (GtkWindow *parent, char *message)
{
 GtkWidget *dialog, *label, *content_area;
 GtkDialogFlags flags;

 // Create the widgets
 flags = GTK_DIALOG_DESTROY_WITH_PARENT;
 dialog = gtk_dialog_new_with_buttons ("Message",
                                       parent,
                                       flags,
                                       `_("_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_window_destroy),
                           dialog);

 // Add the label, and show everything we’ve added

 gtk_box_append (GTK_BOX (content_area), label);
 gtk_widget_show (dialog);
}

GtkDialog as GtkBuildable

The GtkDialog implementation of the GtkBuildable interface exposes the content_area as an internal child with the name “content_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). To mark a response as default, set the “default” attribute of the <action-widget> element to true.

GtkDialog supports adding action widgets by specifying “action” as the “type” attribute of a <child> element. The widget will be added either to the action area or the headerbar of the dialog, depending on the “use-header-bar” property. The response id has to be associated with the action widget using the <action-widgets> element.

An example of a GtkDialog UI definition fragment:

&lt;object class="GtkDialog" id="dialog1"&gt;
  &lt;child type="action"&gt;
    &lt;object class="GtkButton" id="button_cancel"/&gt;
  &lt;/child&gt;
  &lt;child type="action"&gt;
    &lt;object class="GtkButton" id="button_ok"&gt;
    &lt;/object&gt;
  &lt;/child&gt;
  &lt;action-widgets&gt;
    &lt;action-widget response="cancel"&gt;button_cancel&lt;/action-widget&gt;
    &lt;action-widget response="ok" default="true"&gt;button_ok&lt;/action-widget&gt;
  &lt;/action-widgets&gt;
&lt;/object&gt;

Accessibility

GtkDialog uses the GTK_ACCESSIBLE_ROLE_DIALOG role.

The Dialog type acts as a reference-counted owner of an underlying GtkDialog instance. It provides the methods that can operate on this data type through DialogProtocol conformance. Use Dialog as a strong reference or owner of a GtkDialog instance.

Show on GitHub


                    
                    
                    init(_:)

Designated initialiser from the underlying `C` data type.

This creates an instance without performing an unbalanced retain i.e., ownership is transferred to the Dialog instance.

Declaration

Swift

@inlinable
public init(_ op: UnsafeMutablePointer<GtkDialog>)

Parameters

`op`	pointer to the underlying object

Show on GitHub


                    
                    
                    init(_:)

Designated initialiser from a constant pointer to the underlying C data type. This creates an instance without performing an unbalanced retain i.e., ownership is transferred to the Dialog instance.

Declaration

Swift

@inlinable
public init(_ op: UnsafePointer<GtkDialog>)

Parameters

`op`	pointer to the underlying object

Show on GitHub


                    
                    
                    init(gpointer:)

Optional initialiser from a non-mutating gpointer to the underlying C data type. This creates an instance without performing an unbalanced retain i.e., ownership is transferred to the Dialog instance.

Declaration

Swift

@inlinable
override public init!(gpointer op: gpointer?)

Parameters

`op`	gpointer to the underlying object

Show on GitHub


                    
                    
                    init(gconstpointer:)

Optional initialiser from a non-mutating gconstpointer to the underlying C data type. This creates an instance without performing an unbalanced retain i.e., ownership is transferred to the Dialog instance.

Declaration

Swift

@inlinable
override public init!(gconstpointer op: gconstpointer?)

Parameters

`op`	pointer to the underlying object

Show on GitHub


                    
                    
                    init(_:)

Optional initialiser from a constant pointer to the underlying C data type. This creates an instance without performing an unbalanced retain i.e., ownership is transferred to the Dialog instance.

Declaration

Swift

@inlinable
public init!(_ op: UnsafePointer<GtkDialog>?)

Parameters

`op`	pointer to the underlying object

Show on GitHub


                    
                    
                    init(_:)

Optional initialiser from the underlying C data type. This creates an instance without performing an unbalanced retain i.e., ownership is transferred to the Dialog instance.

Declaration

Swift

@inlinable
public init!(_ op: UnsafeMutablePointer<GtkDialog>?)

Parameters

`op`	pointer to the underlying object

Show on GitHub


                    
                    
                    init(retaining:)

Designated initialiser from the underlying C data type. Will retain GtkDialog. i.e., ownership is transferred to the Dialog instance.

Declaration

Swift

@inlinable
public init(retaining op: UnsafeMutablePointer<GtkDialog>)

Parameters

`op`	pointer to the underlying object

Show on GitHub


                    
                    
                    init(dialog:)

Reference intialiser for a related type that implements DialogProtocol Will retain GtkDialog.

Declaration

Swift

@inlinable
public init<T>(dialog other: T) where T : DialogProtocol

Parameters


                                other

an instance of a related type that implements DialogProtocol

Show on GitHub


                    
                    
                    init(cPointer:)

Unsafe typed initialiser. Do not use unless you know the underlying data type the pointer points to conforms to DialogProtocol.

Declaration

Swift

@inlinable
override public init<T>(cPointer p: UnsafeMutablePointer<T>)

Parameters


                                cPointer

pointer to the underlying object

Show on GitHub


                    
                    
                    init(retainingCPointer:)

Unsafe typed, retaining initialiser. Do not use unless you know the underlying data type the pointer points to conforms to DialogProtocol.

Declaration

Swift

@inlinable
override public init<T>(retainingCPointer cPointer: UnsafeMutablePointer<T>)

Parameters


                                cPointer

pointer to the underlying object

Show on GitHub


                    
                    
                    init(raw:)

Unsafe untyped initialiser. Do not use unless you know the underlying data type the pointer points to conforms to DialogProtocol.

Declaration

Swift

@inlinable
override public init(raw p: UnsafeRawPointer)

Parameters

`p`	raw pointer to the underlying object

Show on GitHub

init(retainingRaw:)
Unsafe untyped, retaining initialiser. Do not use unless you know the underlying data type the pointer points to conforms to DialogProtocol.
Declaration
Swift

@inlinable override public init(retainingRaw raw: UnsafeRawPointer)
Show on GitHub


                    
                    
                    init(raw:)

Unsafe untyped initialiser. Do not use unless you know the underlying data type the pointer points to conforms to DialogProtocol.

Declaration

Swift

@inlinable
public required init(raw p: UnsafeMutableRawPointer)

Parameters

`p`	mutable raw pointer to the underlying object

Show on GitHub


                    
                    
                    init(retainingRaw:)

Unsafe untyped, retaining initialiser. Do not use unless you know the underlying data type the pointer points to conforms to DialogProtocol.

Declaration

Swift

@inlinable
required public init(retainingRaw raw: UnsafeMutableRawPointer)

Parameters

raw

mutable raw pointer to the underlying object

Show on GitHub


                    
                    
                    init(opaquePointer:)

Unsafe untyped initialiser. Do not use unless you know the underlying data type the pointer points to conforms to DialogProtocol.

Declaration

Swift

@inlinable
override public init(opaquePointer p: OpaquePointer)

Parameters

`p`	opaque pointer to the underlying object

Show on GitHub


                    
                    
                    init(retainingOpaquePointer:)

Unsafe untyped, retaining initialiser. Do not use unless you know the underlying data type the pointer points to conforms to DialogProtocol.

Declaration

Swift

@inlinable
override public init(retainingOpaquePointer p: OpaquePointer)

Parameters

`p`	opaque pointer to the underlying object

Show on GitHub

init()
Creates a new dialog box.

Widgets should not be packed into the GtkWindow directly, but into the content_area and action_area, as described above.
Declaration
Swift

@inlinable override public init()
Show on GitHub


                    
                    
                    init(title:flags:text:responseType:)

Convenience constructor to create a dialog with a single button. This creates a new GtkDialog with title title (or NULL for the default title; see gtk_window_set_title()). The flags argument can be used to make the dialog modal (GTK_DIALOG_MODAL) and/or to have it destroyed along with its transient parent (GTK_DIALOG_DESTROY_WITH_PARENT). After flags, the button text and response ID pairs should be listed. The button text can be an arbitrary text. If the user clicks the dialog button, GtkDialog will emit the “response” signal with the corresponding response ID. If a GtkDialog receives the “delete-event” signal, it will emit ::response with a response ID of GTK_RESPONSE_DELETE_EVENT. However, destroying a dialog does not emit the ::response signal; so be careful relying on ::response when using the GTK_DIALOG_DESTROY_WITH_PARENT flag. Buttons are from left to right, so the first button in the list will be the leftmost button in the dialog. @param title Title of the dialog @param parent parent window @param flags flags to use such as GTK_DIALOG_MODAL @param first_button_text text to display for the button @param response_type any positive number, or one of the values in the GtkResponseType enumeration.

Declaration

Swift

@inlinable
convenience init(title: UnsafePointer<gchar>! = nil, flags: DialogFlags = .modal, text: String, responseType: ResponseType = .ok)

Parameters

`title`	Title of the dialog
`flags`	flags to use such as `.modal` (default) or `.destroy_with_parent`
`text`	title of the button
`responseType`	response type for the button (default: `.accept`)

Show on GitHub


                    
                    
                    init(title:parent:flags:text:responseType:)

Convenience constructor to create a dialog with a single button. This creates a new GtkDialog with title title (or NULL for the default title; see gtk_window_set_title()) and transient parent parent. The flags argument can be used to make the dialog modal (GTK_DIALOG_MODAL) and/or to have it destroyed along with its transient parent (GTK_DIALOG_DESTROY_WITH_PARENT). After flags, the button text and response ID pairs should be listed. The button text can be an arbitrary text. If the user clicks the dialog button, GtkDialog will emit the “response” signal with the corresponding response ID. If a GtkDialog receives the “delete-event” signal, it will emit ::response with a response ID of GTK_RESPONSE_DELETE_EVENT. However, destroying a dialog does not emit the ::response signal; so be careful relying on ::response when using the GTK_DIALOG_DESTROY_WITH_PARENT flag. Buttons are from left to right, so the first button in the list will be the leftmost button in the dialog. @param title @param parent @param flags flags to use such as GTK_DIALOG_MODAL @param first_button_text text to display for the button @param response_type any positive number, or one of the values in the GtkResponseType enumeration.

Declaration

Swift

@inlinable
convenience init<W>(title: UnsafePointer<gchar>! = nil, parent: W, flags: DialogFlags = .modal, text: String, responseType: ResponseType = .ok) where W : WindowProtocol

Parameters

`title`	Title of the dialog
`parent`	parent window
`flags`	flags to use such as `.modal` (default) or `.destroy_with_parent`
`text`	title of the button
`responseType`	response type for the button

Show on GitHub


                    
                    
                    init(title:flags:firstText:firstResponseType:secondText:secondResponseType:)

Convenience constructor to create a dialog with two buttons. This creates a new GtkDialog with title title (or NULL for the default title; see gtk_window_set_title()) and transient parent parent. The flags argument can be used to make the dialog modal (GTK_DIALOG_MODAL) and/or to have it destroyed along with its transient parent (GTK_DIALOG_DESTROY_WITH_PARENT). After flags, the button text and response ID pairs should be listed. Each button text can be an arbitrary text. If the user clicks the dialog button, GtkDialog will emit the “response” signal with the corresponding response ID. If a GtkDialog receives the “delete-event” signal, it will emit ::response with a response ID of GTK_RESPONSE_DELETE_EVENT. However, destroying a dialog does not emit the ::response signal; so be careful relying on ::response when using the GTK_DIALOG_DESTROY_WITH_PARENT flag. Buttons are from left to right, so the first button in the list will be the leftmost button in the dialog.

Declaration

Swift

@inlinable
convenience init(title: UnsafePointer<gchar>! = nil, flags: DialogFlags = .modal, firstText: String, firstResponseType: ResponseType = .cancel, secondText: String, secondResponseType: ResponseType = .ok)

Parameters

`title`	Title of the dialog
`flags`	flags to use such as `.modal` (default) or `.destroy_with_parent`
`firstText`	title of the first button
`firstResponseType`	response type for the first button
`secondText`	title of the second button
`secondResponseType`	response type for the second button

Show on GitHub


                    
                    
                    init(title:parent:flags:firstText:firstResponseType:secondText:secondResponseType:)

Declaration

Swift

@inlinable
convenience init<W>(title: UnsafePointer<gchar>! = nil, parent: W, flags: DialogFlags = .modal, firstText: String, firstResponseType: ResponseType = .cancel, secondText: String, secondResponseType: ResponseType = .ok) where W : WindowProtocol

Parameters

`title`	Title of the dialog
`parent`	parent window
`flags`	flags to use such as `.modal` (default) or `.destroy_with_parent`
`firstText`	title of the first button
`firstResponseType`	response type for the first button
`secondText`	title of the second button
`secondResponseType`	response type for the second button

Show on GitHub


                    
                    
                    init(title:flags:firstText:firstResponseType:secondText:secondResponseType:thirdText:thirdResponseType:)

Convenience constructor to create a dialog with three buttons. This creates a new GtkDialog with title title (or NULL for the default title; see gtk_window_set_title()) and transient parent parent. The flags argument can be used to make the dialog modal (GTK_DIALOG_MODAL) and/or to have it destroyed along with its transient parent (GTK_DIALOG_DESTROY_WITH_PARENT). After flags, the button text and response ID pairs should be listed. Each button text can be an arbitrary text. If the user clicks the dialog button, GtkDialog will emit the “response” signal with the corresponding response ID. If a GtkDialog receives the “delete-event” signal, it will emit ::response with a response ID of GTK_RESPONSE_DELETE_EVENT. However, destroying a dialog does not emit the ::response signal; so be careful relying on ::response when using the GTK_DIALOG_DESTROY_WITH_PARENT flag. Buttons are from left to right, so the first button in the list will be the leftmost button in the dialog.

Declaration

Swift

@inlinable
convenience init(title: UnsafePointer<gchar>! = nil, flags: DialogFlags = .modal, firstText: String, firstResponseType: ResponseType = .help, secondText: String, secondResponseType: ResponseType = .cancel, thirdText: String, thirdResponseType: ResponseType = .ok)

Parameters

`title`	Title of the dialog
`flags`	flags to use such as `.modal` (default) or `.destroy_with_parent`
`firstText`	title of the first button
`firstResponseType`	response type for the first button
`secondText`	title of the second button
`secondResponseType`	response type for the second button
`thirdText`	title of the third button
`thirdResponseType`	response type for the third button

Show on GitHub


                    
                    
                    init(title:parent:flags:firstText:firstResponseType:secondText:secondResponseType:thirdText:thirdResponseType:)

Declaration

Swift

@inlinable
convenience init<W>(title: UnsafePointer<gchar>! = nil, parent: W, flags: DialogFlags = .modal, firstText: String, firstResponseType: ResponseType = .help, secondText: String, secondResponseType: ResponseType = .cancel, thirdText: String, thirdResponseType: ResponseType = .ok) where W : WindowProtocol

Parameters

`title`	Title of the dialog
`parent`	parent window
`flags`	flags to use such as `.modal` (default) or `.destroy_with_parent`
`firstText`	title of the first button
`firstResponseType`	response type for the first button
`secondText`	title of the second button
`secondResponseType`	response type for the second button
`thirdText`	title of the third button
`thirdResponseType`	response type for the third button

Show on GitHub