A dialog presenting a message or a question.
<picture> <source srcset="message-dialog-dark.png" media="(prefers-color-scheme: dark)"> <img src="message-dialog.png"
alt="message-dialog"> </picture>
Message dialogs have a heading, a body, an optional child widget, and one or multiple responses, each presented as a button.
Each response has a unique string ID, and a button label. Additionally, each response can be enabled or disabled, and can have a
suggested or destructive appearance.
When one of the responses is activated, or the dialog is closed, the [signal@MessageDialog:AdapMessageDialog:response]
signal will be emitted. This signal is detailed, and the detail, as well as the `response` parameter will be set to the ID of the
activated response, or to the value of the [property@MessageDialog:close-response] property if the dialog had been closed without
activating any of the responses.
Response buttons can be presented horizontally or vertically depending on available space.
When a response is activated, `AdapMessageDialog` is closed automatically.
An example of using a message dialog:
```c GtkWidget *dialog;
dialog = adap_message_dialog_new (parent, _("Replace File?"), NULL);
adap_message_dialog_format_body (ADAP_MESSAGE_DIALOG (dialog), _("A file named “s” already exists.
Do you want to replace it?"), filename);
adap_message_dialog_add_responses (ADAP_MESSAGE_DIALOG (dialog), "cancel", _("_Cancel"), "replace", _("_Replace"), NULL);
adap_message_dialog_set_response_appearance (ADAP_MESSAGE_DIALOG (dialog), "replace", ADAP_RESPONSE_DESTRUCTIVE);
adap_message_dialog_set_default_response (ADAP_MESSAGE_DIALOG (dialog), "cancel"); adap_message_dialog_set_close_response (
ADAP_MESSAGE_DIALOG (dialog), "cancel");
g_signal_connect (dialog, "response", G_CALLBACK (response_cb), self);
gtk_window_present (GTK_WINDOW (dialog)); ```
Async API
`AdapMessageDialog` can also be used via the [method@MessageDialog.choose] method. This API follows the GIO async pattern, and the result
can be obtained by calling [method@MessageDialog.choose_finish], for example:
```c static void dialog_cb (AdapMessageDialog *dialog, GAsyncResult *result, MyWindow *self) { const char *response =
adap_message_dialog_choose_finish (dialog, result);
// ... }
static void show_dialog (MyWindow *self) { GtkWidget *dialog;
dialog = adap_message_dialog_new (GTK_WINDOW (self), _("Replace File?"), NULL);
adap_message_dialog_format_body (ADAP_MESSAGE_DIALOG (dialog), _("A file named “s” already exists.
Do you want to replace it?"), filename);
adap_message_dialog_add_responses (ADAP_MESSAGE_DIALOG (dialog), "cancel", _("_Cancel"), "replace", _("_Replace"), NULL);
adap_message_dialog_set_response_appearance (ADAP_MESSAGE_DIALOG (dialog), "replace", ADAP_RESPONSE_DESTRUCTIVE);
adap_message_dialog_set_default_response (ADAP_MESSAGE_DIALOG (dialog), "cancel"); adap_message_dialog_set_close_response (
ADAP_MESSAGE_DIALOG (dialog), "cancel");
adap_message_dialog_choose (ADAP_MESSAGE_DIALOG (dialog), NULL, (GAsyncReadyCallback) dialog_cb, self); } ```
AdapMessageDialog as GtkBuildable
`AdapMessageDialog` supports adding responses in UI definitions by via the `<responses>` element that may contain multiple `<
response>` elements, each respresenting a response.
Each of the `<response>` elements must have the `id` attribute specifying the response ID. The contents of the element are used as
the response label.
Response labels can be translated with the usual `translatable`, `context` and `comments` attributes.
The `<response>` elements can also have `enabled` and/or `appearance` attributes. See [method@MessageDialog.set_response_enabled]
and [method@MessageDialog.set_response_appearance] for details.
Example of an `AdapMessageDialog` UI definition:
```xml <object class="AdapMessageDialog" id="dialog"> <property name="heading" translatable="yes">Save Changes?</property
> <property name="body" translatable="yes">Open documents contain unsaved changes. Changes which are not saved will be
permanently lost.</property> <property name="default-response">save</property> <property name="close-response">
cancel</property> <signal name="response" handler="response_cb"/> <responses> <response id="cancel"
translatable="yes">_Cancel</response> <response id="discard" translatable="yes" appearance="destructive">_Discard<
/response> <response id="save" translatable="yes" appearance="suggested" enabled="false">_Save</response> </responses
> </object> ```
Accessibility
`AdapMessageDialog` uses the `GTK_ACCESSIBLE_ROLE_DIALOG` role.
