Package ch.bailu.gtk.adw

Class MessageDialog

java.lang.Object
ch.bailu.gtk.type.Type
ch.bailu.gtk.type.Pointer
ch.bailu.gtk.gobject.Object
ch.bailu.gtk.gobject.InitiallyUnowned
ch.bailu.gtk.gtk.Widget
ch.bailu.gtk.gtk.Window
ch.bailu.gtk.adw.MessageDialog
All Implemented Interfaces:
PointerInterface
public class MessageDialog extends Window
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::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, `AdwMessageDialog` is closed automatically.

An example of using a message dialog:

```c
GtkWidget *dialog;

dialog = adw_message_dialog_new (parent, _("Replace File?"), NULL);

adw_message_dialog_format_body (ADW_MESSAGE_DIALOG (dialog),
_("A file named “%s” already exists. Do you want to replace it?"),
filename);

adw_message_dialog_add_responses (ADW_MESSAGE_DIALOG (dialog),
"cancel", _("_Cancel"),
"replace", _("_Replace"),
NULL);

adw_message_dialog_set_response_appearance (ADW_MESSAGE_DIALOG (dialog), "replace", ADW_RESPONSE_DESTRUCTIVE);

adw_message_dialog_set_default_response (ADW_MESSAGE_DIALOG (dialog), "cancel");
adw_message_dialog_set_close_response (ADW_MESSAGE_DIALOG (dialog), "cancel");

g_signal_connect (dialog, "response", G_CALLBACK (response_cb), self);

gtk_window_present (GTK_WINDOW (dialog));
```

## AdwMessageDialog as GtkBuildable

`AdwMessageDialog` 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 `AdwMessageDialog` UI definition:

```xml
<object class="AdwMessageDialog" 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

`AdwMessageDialog` uses the `GTK_ACCESSIBLE_ROLE_DIALOG` role.

https://gnome.pages.gitlab.gnome.org/libadwaita/doc/main/class.MessageDialog.html

  • Field Details

  • Constructor Details

    • MessageDialog

      public MessageDialog(PointerContainer pointer)

    • MessageDialog

      public MessageDialog(@Nullable Window parent, @Nullable Str heading, @Nullable Str body)
      Creates a new `AdwMessageDialog`.

      @heading and @body can be set to `NULL`. This can be useful if they need to
      be formatted or use markup. In that case, set them to `NULL` and call
      [method@MessageDialog.format_body] or similar methods afterwards:

      ```c
      GtkWidget *dialog;

      dialog = adw_message_dialog_new (parent, _("Replace File?"), NULL);
      adw_message_dialog_format_body (ADW_MESSAGE_DIALOG (dialog),
      _("A file named “%s” already exists. Do you want to replace it?"),
      filename);
      ```
      Parameters:
      parent - transient parent
      heading - the heading
      body - the body text

    • MessageDialog

      public MessageDialog(@Nullable Window parent, String heading, String body)
      Creates a new `AdwMessageDialog`.

      @heading and @body can be set to `NULL`. This can be useful if they need to
      be formatted or use markup. In that case, set them to `NULL` and call
      [method@MessageDialog.format_body] or similar methods afterwards:

      ```c
      GtkWidget *dialog;

      dialog = adw_message_dialog_new (parent, _("Replace File?"), NULL);
      adw_message_dialog_format_body (ADW_MESSAGE_DIALOG (dialog),
      _("A file named “%s” already exists. Do you want to replace it?"),
      filename);
      ```
      Parameters:
      parent - transient parent
      heading - the heading
      body - the body text

  • Method Details

    • getClassHandler

      public static ClassHandler getClassHandler()

    • addResponse

      public void addResponse(@Nonnull Str id, @Nonnull Str label)
      Adds a response with @id and @label to @self.

      Responses are represented as buttons in the dialog.

      Response ID must be unique. It will be used in
      [signal@MessageDialog::response] to tell which response had been activated,
      as well as to inspect and modify the response later.

      An embedded underline in @label indicates a mnemonic.

      [method@MessageDialog.set_response_label] can be used to change the response
      label after it had been added.

      [method@MessageDialog.set_response_enabled] and
      [method@MessageDialog.set_response_appearance] can be used to customize the
      responses further.
      Parameters:
      id - the response ID
      label - the response label

    • addResponse

      public void addResponse(String id, String label)
      Adds a response with @id and @label to @self.

      Responses are represented as buttons in the dialog.

      Response ID must be unique. It will be used in
      [signal@MessageDialog::response] to tell which response had been activated,
      as well as to inspect and modify the response later.

      An embedded underline in @label indicates a mnemonic.

      [method@MessageDialog.set_response_label] can be used to change the response
      label after it had been added.

      [method@MessageDialog.set_response_enabled] and
      [method@MessageDialog.set_response_appearance] can be used to customize the
      responses further.
      Parameters:
      id - the response ID
      label - the response label

    • addResponses

      public void addResponses(@Nonnull Str first_id, Object... _elipse)
      Adds multiple responses to @self.

      This is the same as calling [method@MessageDialog.add_response] repeatedly.
      The variable argument list should be `NULL`-terminated list of response IDs
      and labels.

      Example:

      ```c
      adw_message_dialog_add_responses (dialog,
      "cancel", _("_Cancel"),
      "discard", _("_Discard"),
      "save", _("_Save"),
      NULL);
      ```
      Parameters:
      first_id - response id
      _elipse - label for first response, then more id-label pairs

    • addResponses

      public void addResponses(String first_id, Object... _elipse)
      Adds multiple responses to @self.

      This is the same as calling [method@MessageDialog.add_response] repeatedly.
      The variable argument list should be `NULL`-terminated list of response IDs
      and labels.

      Example:

      ```c
      adw_message_dialog_add_responses (dialog,
      "cancel", _("_Cancel"),
      "discard", _("_Discard"),
      "save", _("_Save"),
      NULL);
      ```
      Parameters:
      first_id - response id
      _elipse - label for first response, then more id-label pairs

    • formatBody

      public void formatBody(@Nonnull Str format, Object... _elipse)
      Sets the formatted body text of @self.

      See [property@MessageDialog:body].
      Parameters:
      format - the formatted string for the body text
      _elipse - the parameters to insert into @format

    • formatBody

      public void formatBody(String format, Object... _elipse)
      Sets the formatted body text of @self.

      See [property@MessageDialog:body].
      Parameters:
      format - the formatted string for the body text
      _elipse - the parameters to insert into @format

    • formatBodyMarkup

      public void formatBodyMarkup(@Nonnull Str format, Object... _elipse)
      Sets the formatted body text of @self with Pango markup.

      The @format is assumed to contain Pango markup.

      Special XML characters in the `printf()` arguments passed to this function
      will automatically be escaped as necessary, see
      [func@GLib.markup_printf_escaped].

      See [property@MessageDialog:body].
      Parameters:
      format - the formatted string for the body text with Pango markup
      _elipse - the parameters to insert into @format

    • formatBodyMarkup

      public void formatBodyMarkup(String format, Object... _elipse)
      Sets the formatted body text of @self with Pango markup.

      The @format is assumed to contain Pango markup.

      Special XML characters in the `printf()` arguments passed to this function
      will automatically be escaped as necessary, see
      [func@GLib.markup_printf_escaped].

      See [property@MessageDialog:body].
      Parameters:
      format - the formatted string for the body text with Pango markup
      _elipse - the parameters to insert into @format

    • formatHeading

      public void formatHeading(@Nonnull Str format, Object... _elipse)
      Sets the formatted heading of @self.

      See [property@MessageDialog:heading].
      Parameters:
      format - the formatted string for the heading
      _elipse - the parameters to insert into @format

    • formatHeading

      public void formatHeading(String format, Object... _elipse)
      Sets the formatted heading of @self.

      See [property@MessageDialog:heading].
      Parameters:
      format - the formatted string for the heading
      _elipse - the parameters to insert into @format

    • formatHeadingMarkup

      public void formatHeadingMarkup(@Nonnull Str format, Object... _elipse)
      Sets the formatted heading of @self with Pango markup.

      The @format is assumed to contain Pango markup.

      Special XML characters in the `printf()` arguments passed to this function
      will automatically be escaped as necessary, see
      [func@GLib.markup_printf_escaped].

      See [property@MessageDialog:heading].
      Parameters:
      format - the formatted string for the heading with Pango markup
      _elipse - the parameters to insert into @format

    • formatHeadingMarkup

      public void formatHeadingMarkup(String format, Object... _elipse)
      Sets the formatted heading of @self with Pango markup.

      The @format is assumed to contain Pango markup.

      Special XML characters in the `printf()` arguments passed to this function
      will automatically be escaped as necessary, see
      [func@GLib.markup_printf_escaped].

      See [property@MessageDialog:heading].
      Parameters:
      format - the formatted string for the heading with Pango markup
      _elipse - the parameters to insert into @format

    • getBody

      public Str getBody()
      Gets the body text of @self.
      Returns:
      the body of @self.

    • getBodyUseMarkup

      public boolean getBodyUseMarkup()
      Gets whether the body text of @self includes Pango markup.
      Returns:
      whether @self uses markup for body text

    • getCloseResponse

      public Str getCloseResponse()
      Gets the ID of the close response of @self.
      Returns:
      the close response ID

    • getDefaultResponse

      public Str getDefaultResponse()
      Gets the ID of the default response of @self.
      Returns:
      the default response ID

    • getExtraChild

      public Widget getExtraChild()
      Gets the child widget of @self.
      Returns:
      the child widget of @self.

    • getHeading

      public Str getHeading()
      Gets the heading of @self.
      Returns:
      the heading of @self.

    • getHeadingUseMarkup

      public boolean getHeadingUseMarkup()
      Gets whether the heading of @self includes Pango markup.
      Returns:
      whether @self uses markup for heading

    • getResponseAppearance

      public int getResponseAppearance(@Nonnull Str response)
      Gets the appearance of @response.

      See [method@MessageDialog.set_response_appearance].
      Parameters:
      response - a response ID
      Returns:
      the appearance of @response

    • getResponseAppearance

      public int getResponseAppearance(String response)
      Gets the appearance of @response.

      See [method@MessageDialog.set_response_appearance].
      Parameters:
      response - a response ID
      Returns:
      the appearance of @response

    • getResponseEnabled

      public boolean getResponseEnabled(@Nonnull Str response)
      Gets whether @response is enabled.

      See [method@MessageDialog.set_response_enabled].
      Parameters:
      response - a response ID
      Returns:
      whether @response is enabled

    • getResponseEnabled

      public boolean getResponseEnabled(String response)
      Gets whether @response is enabled.

      See [method@MessageDialog.set_response_enabled].
      Parameters:
      response - a response ID
      Returns:
      whether @response is enabled

    • getResponseLabel

      public Str getResponseLabel(@Nonnull Str response)
      Gets the label of @response.

      See [method@MessageDialog.set_response_label].
      Parameters:
      response - a response ID
      Returns:
      the label of @response

    • getResponseLabel

      public Str getResponseLabel(String response)
      Gets the label of @response.

      See [method@MessageDialog.set_response_label].
      Parameters:
      response - a response ID
      Returns:
      the label of @response

    • hasResponse

      public boolean hasResponse(@Nonnull Str response)
      Gets whether @self has a response with the ID @response.
      Parameters:
      response - response ID
      Returns:
      whether @self has a response with the ID @response.

    • hasResponse

      public boolean hasResponse(String response)
      Gets whether @self has a response with the ID @response.
      Parameters:
      response - response ID
      Returns:
      whether @self has a response with the ID @response.

    • response

      public void response(@Nonnull Str response)
      Emits the [signal@MessageDialog::response] signal with the given response ID.

      Used to indicate that the user has responded to the dialog in some way.
      Parameters:
      response - response ID

    • response

      public void response(String response)
      Emits the [signal@MessageDialog::response] signal with the given response ID.

      Used to indicate that the user has responded to the dialog in some way.
      Parameters:
      response - response ID

    • setBody

      public void setBody(@Nonnull Str body)
      Sets the body text of @self.
      Parameters:
      body - the body of @self

    • setBody

      public void setBody(String body)
      Sets the body text of @self.
      Parameters:
      body - the body of @self

    • setBodyUseMarkup

      public void setBodyUseMarkup(boolean use_markup)
      Sets whether the body text of @self includes Pango markup.

      See [func@Pango.parse_markup].
      Parameters:
      use_markup - whether to use markup for body text

    • setCloseResponse

      public void setCloseResponse(@Nonnull Str response)
      Sets the ID of the close response of @self.

      It will be passed to [signal@MessageDialog::response] if the window is
      closed by pressing <kbd>Escape</kbd> or with a system action.

      It doesn't have to correspond to any of the responses in the dialog.

      The default close response is `close`.
      Parameters:
      response - the close response ID

    • setCloseResponse

      public void setCloseResponse(String response)
      Sets the ID of the close response of @self.

      It will be passed to [signal@MessageDialog::response] if the window is
      closed by pressing <kbd>Escape</kbd> or with a system action.

      It doesn't have to correspond to any of the responses in the dialog.

      The default close response is `close`.
      Parameters:
      response - the close response ID

    • setDefaultResponse

      public void setDefaultResponse(@Nullable Str response)
      Sets the ID of the default response of @self.

      If set, pressing <kbd>Enter</kbd> will activate the corresponding button.

      If set to `NULL` or to a non-existent response ID, pressing <kbd>Enter</kbd>
      will do nothing.
      Parameters:
      response - the default response ID

    • setDefaultResponse

      public void setDefaultResponse(String response)
      Sets the ID of the default response of @self.

      If set, pressing <kbd>Enter</kbd> will activate the corresponding button.

      If set to `NULL` or to a non-existent response ID, pressing <kbd>Enter</kbd>
      will do nothing.
      Parameters:
      response - the default response ID

    • setExtraChild

      public void setExtraChild(@Nullable Widget child)
      Sets the child widget of @self.

      The child widget is displayed below the heading and body.
      Parameters:
      child - the child widget

    • setHeading

      public void setHeading(@Nullable Str heading)
      Sets the heading of @self.
      Parameters:
      heading - the heading of @self

    • setHeading

      public void setHeading(String heading)
      Sets the heading of @self.
      Parameters:
      heading - the heading of @self

    • setHeadingUseMarkup

      public void setHeadingUseMarkup(boolean use_markup)
      Sets whether the heading of @self includes Pango markup.

      See [func@Pango.parse_markup].
      Parameters:
      use_markup - whether to use markup for heading

    • setResponseAppearance

      public void setResponseAppearance(@Nonnull Str response, int appearance)
      Sets the appearance for @response.

      <picture>
      <source srcset="message-dialog-appearance-dark.png" media="(prefers-color-scheme: dark)">
      <img src="message-dialog-appearance.png" alt="message-dialog-appearance">
      </picture>

      Use `ADW_RESPONSE_SUGGESTED` to mark important responses such as the
      affirmative action, like the Save button in the example.

      Use `ADW_RESPONSE_DESTRUCTIVE` to draw attention to the potentially damaging
      consequences of using @response. This appearance acts as a warning to the
      user. The Discard button in the example is using this appearance.

      The default appearance is `ADW_RESPONSE_DEFAULT`.

      Negative responses like Cancel or Close should use the default appearance.
      Parameters:
      response - a response ID
      appearance - appearance for @response

    • setResponseAppearance

      public void setResponseAppearance(String response, int appearance)
      Sets the appearance for @response.

      <picture>
      <source srcset="message-dialog-appearance-dark.png" media="(prefers-color-scheme: dark)">
      <img src="message-dialog-appearance.png" alt="message-dialog-appearance">
      </picture>

      Use `ADW_RESPONSE_SUGGESTED` to mark important responses such as the
      affirmative action, like the Save button in the example.

      Use `ADW_RESPONSE_DESTRUCTIVE` to draw attention to the potentially damaging
      consequences of using @response. This appearance acts as a warning to the
      user. The Discard button in the example is using this appearance.

      The default appearance is `ADW_RESPONSE_DEFAULT`.

      Negative responses like Cancel or Close should use the default appearance.
      Parameters:
      response - a response ID
      appearance - appearance for @response

    • setResponseEnabled

      public void setResponseEnabled(@Nonnull Str response, boolean enabled)
      Sets whether @response is enabled.

      If @response is not enabled, the corresponding button will have
      [property@Gtk.Widget:sensitive] set to `FALSE` and it can't be activated as
      a default response.

      @response can still be used as [property@MessageDialog:close-response] while
      it's not enabled.

      Responses are enabled by default.
      Parameters:
      response - a response ID
      enabled - whether to enable @response

    • setResponseEnabled

      public void setResponseEnabled(String response, boolean enabled)
      Sets whether @response is enabled.

      If @response is not enabled, the corresponding button will have
      [property@Gtk.Widget:sensitive] set to `FALSE` and it can't be activated as
      a default response.

      @response can still be used as [property@MessageDialog:close-response] while
      it's not enabled.

      Responses are enabled by default.
      Parameters:
      response - a response ID
      enabled - whether to enable @response

    • setResponseLabel

      public void setResponseLabel(@Nonnull Str response, @Nonnull Str label)
      Sets the label of @response to @label.

      Labels are displayed on the dialog buttons. An embedded underline in @label
      indicates a mnemonic.
      Parameters:
      response - a response ID
      label - the label of @response

    • setResponseLabel

      public void setResponseLabel(String response, String label)
      Sets the label of @response to @label.

      Labels are displayed on the dialog buttons. An embedded underline in @label
      indicates a mnemonic.
      Parameters:
      response - a response ID
      label - the label of @response

    • onResponse

      public SignalHandler onResponse(MessageDialog.OnResponse signal)
      Connect to signal "response".
      See MessageDialog.OnResponse.onResponse(ch.bailu.gtk.type.Str) for signal description.
      Field SIGNAL_ON_RESPONSE contains original signal name and can be used as resource reference.
      Parameters:
      signal - callback function (lambda).
      Returns:
      SignalHandler. Can be used to disconnect signal and to release callback function.

    • asAccessible

      public Accessible asAccessible()
      Implements interface Accessible. Call this to get access to interface functions.
      Overrides:
      asAccessible in class Window
      Returns:
      Accessible

    • asBuildable

      public Buildable asBuildable()
      Implements interface Buildable. Call this to get access to interface functions.
      Overrides:
      asBuildable in class Window
      Returns:
      Buildable

    • asConstraintTarget

      public ConstraintTarget asConstraintTarget()
      Implements interface ConstraintTarget. Call this to get access to interface functions.
      Overrides:
      asConstraintTarget in class Window
      Returns:
      ConstraintTarget

    • asNative

      public Native asNative()
      Implements interface Native. Call this to get access to interface functions.
      Overrides:
      asNative in class Window
      Returns:
      Native

    • asRoot

      public Root asRoot()
      Implements interface Root. Call this to get access to interface functions.
      Overrides:
      asRoot in class Window
      Returns:
      Root

    • asShortcutManager

      public ShortcutManager asShortcutManager()
      Implements interface ShortcutManager. Call this to get access to interface functions.
      Overrides:
      asShortcutManager in class Window
      Returns:
      ShortcutManager

    • getTypeID

      public static long getTypeID()

    • getParentTypeID

      public static long getParentTypeID()

    • getTypeSize

      public static TypeSystem.TypeSize getTypeSize()

    • getParentTypeSize

      public static TypeSystem.TypeSize getParentTypeSize()

    • getInstanceSize

      public static int getInstanceSize()