:right-sidebar: True MessageDialog =================================================================== .. currentmodule:: gi.repository.Adw .. versionadded:: 1.2 .. deprecated:: 1.6 Use :obj:`~gi.repository.Adw.AlertDialog`\. .. class:: MessageDialog(*args, **kwargs) :no-contents-entry: Superclasses: :class:`~gi.repository.Gtk.Window`, :class:`~gi.repository.Gtk.Widget`, :class:`~gi.repository.GObject.InitiallyUnowned`, :class:`~gi.repository.GObject.Object` Implemented Interfaces: :class:`~gi.repository.Gtk.Accessible`, :class:`~gi.repository.Gtk.Buildable`, :class:`~gi.repository.Gtk.ConstraintTarget`, :class:`~gi.repository.Gtk.Native`, :class:`~gi.repository.Gtk.Root`, :class:`~gi.repository.Gtk.ShortcutManager` A dialog presenting a message or a question. .. image:: https://gnome.pages.gitlab.gnome.org/libadwaita/doc/1-latest/message-dialog.png 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 :obj:`~gi.repository.Adw.MessageDialog.signals.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 :obj:`~gi.repository.Adw.MessageDialog.props.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: .. code-block:: c :dedent: 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)); Async API -------------------------------------------------------------------------------- ``AdwMessageDialog`` can also be used via the :obj:`~gi.repository.MessageDialog.choose` method. This API follows the GIO async pattern, for example: .. code-block:: c :dedent: static void dialog_cb (AdwMessageDialog *dialog, GAsyncResult *result, MyWindow *self) { const char *response = adw_message_dialog_choose_finish (dialog, result); // ... } static void show_dialog (MyWindow *self) { GtkWidget *dialog; dialog = adw_message_dialog_new (GTK_WINDOW (self), _("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"); adw_message_dialog_choose (ADW_MESSAGE_DIALOG (dialog), NULL, (GAsyncReadyCallback) dialog_cb, self); } AdwMessageDialog as GtkBuildable -------------------------------------------------------------------------------- ``AdwMessageDialog`` supports adding responses in UI definitions by via the ```` element that may contain multiple ```` elements, each representing a response. Each of the ```` 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 ```` elements can also have ``enabled`` and/or ``appearance`` attributes. See :obj:`~gi.repository.MessageDialog.set_response_enabled` and :obj:`~gi.repository.MessageDialog.set_response_appearance` for details. Example of an ``AdwMessageDialog`` UI definition: .. code-block:: xml :dedent: Save Changes? Open documents contain unsaved changes. Changes which are not saved will be permanently lost. save cancel _Cancel _Discard _Save Accessibility -------------------------------------------------------------------------------- ``AdwMessageDialog`` uses the ``GTK_ACCESSIBLE_ROLE_DIALOG`` role. Constructors ------------ .. rst-class:: interim-class .. class:: MessageDialog :no-index: .. classmethod:: new(parent: ~gi.repository.Gtk.Window | None = None, heading: str | None = None, body: str | None = None) -> ~gi.repository.Gtk.Widget 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 :obj:`~gi.repository.MessageDialog.format_body` or similar methods afterwards: .. code-block:: c :dedent: 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); .. versionadded:: 1.2 .. deprecated:: 1.6 Use :obj:`~gi.repository.Adw.AlertDialog`\. :param parent: transient parent :param heading: the heading :param body: the body text Methods ------- .. rst-class:: interim-class .. class:: MessageDialog :no-index: .. method:: add_response(id: str, label: str) -> None 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 :obj:`~gi.repository.Adw.MessageDialog.signals.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. :obj:`~gi.repository.MessageDialog.set_response_label` can be used to change the response label after it had been added. :obj:`~gi.repository.MessageDialog.set_response_enabled` and :obj:`~gi.repository.MessageDialog.set_response_appearance` can be used to customize the responses further. .. versionadded:: 1.2 .. deprecated:: 1.6 Use :obj:`~gi.repository.Adw.AlertDialog`\. :param id: the response ID :param label: the response label .. method:: choose(cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> None This function shows ``self`` to the user. .. versionadded:: 1.3 .. deprecated:: 1.6 Use :obj:`~gi.repository.Adw.AlertDialog`\. :param cancellable: a ``GCancellable`` to cancel the operation :param callback: a callback to call when the operation is complete :param user_data: data to pass to ``callback`` .. method:: choose_finish(result: ~gi.repository.Gio.AsyncResult) -> str Finishes the :obj:`~gi.repository.MessageDialog.choose` call and returns the response ID. .. versionadded:: 1.3 .. deprecated:: 1.6 Use :obj:`~gi.repository.Adw.AlertDialog`\. :param result: a ``GAsyncResult`` .. method:: do_response(self, response: str) -> None :param response: .. method:: get_body() -> str Gets the body text of ``self``\. .. versionadded:: 1.2 .. deprecated:: 1.6 Use :obj:`~gi.repository.Adw.AlertDialog`\. .. method:: get_body_use_markup() -> bool Gets whether the body text of ``self`` includes Pango markup. .. versionadded:: 1.2 .. deprecated:: 1.6 Use :obj:`~gi.repository.Adw.AlertDialog`\. .. method:: get_close_response() -> str Gets the ID of the close response of ``self``\. .. versionadded:: 1.2 .. deprecated:: 1.6 Use :obj:`~gi.repository.Adw.AlertDialog`\. .. method:: get_default_response() -> str | None Gets the ID of the default response of ``self``\. .. versionadded:: 1.2 .. deprecated:: 1.6 Use :obj:`~gi.repository.Adw.AlertDialog`\. .. method:: get_extra_child() -> ~gi.repository.Gtk.Widget | None Gets the child widget of ``self``\. .. versionadded:: 1.2 .. deprecated:: 1.6 Use :obj:`~gi.repository.Adw.AlertDialog`\. .. method:: get_heading() -> str | None Gets the heading of ``self``\. .. versionadded:: 1.2 .. deprecated:: 1.6 Use :obj:`~gi.repository.Adw.AlertDialog`\. .. method:: get_heading_use_markup() -> bool Gets whether the heading of ``self`` includes Pango markup. .. versionadded:: 1.2 .. deprecated:: 1.6 Use :obj:`~gi.repository.Adw.AlertDialog`\. .. method:: get_response_appearance(response: str) -> ~gi.repository.Adw.ResponseAppearance Gets the appearance of ``response``\. See :obj:`~gi.repository.MessageDialog.set_response_appearance`\. .. versionadded:: 1.2 .. deprecated:: 1.6 Use :obj:`~gi.repository.Adw.AlertDialog`\. :param response: a response ID .. method:: get_response_enabled(response: str) -> bool Gets whether ``response`` is enabled. See :obj:`~gi.repository.MessageDialog.set_response_enabled`\. .. versionadded:: 1.2 .. deprecated:: 1.6 Use :obj:`~gi.repository.Adw.AlertDialog`\. :param response: a response ID .. method:: get_response_label(response: str) -> str Gets the label of ``response``\. See :obj:`~gi.repository.MessageDialog.set_response_label`\. .. versionadded:: 1.2 .. deprecated:: 1.6 Use :obj:`~gi.repository.Adw.AlertDialog`\. :param response: a response ID .. method:: has_response(response: str) -> bool Gets whether ``self`` has a response with the ID ``response``\. .. versionadded:: 1.2 .. deprecated:: 1.6 Use :obj:`~gi.repository.Adw.AlertDialog`\. :param response: response ID .. method:: remove_response(id: str) -> None Removes a response from ``self``\. .. versionadded:: 1.5 .. deprecated:: 1.6 Use :obj:`~gi.repository.Adw.AlertDialog`\. :param id: the response ID .. method:: response(response: str) -> None Emits the :obj:`~gi.repository.Adw.MessageDialog.signals.response` signal with the given response ID. Used to indicate that the user has responded to the dialog in some way. .. versionadded:: 1.2 .. deprecated:: 1.6 Use :obj:`~gi.repository.Adw.AlertDialog`\. :param response: response ID .. method:: set_body(body: str) -> None Sets the body text of ``self``\. .. versionadded:: 1.2 .. deprecated:: 1.6 Use :obj:`~gi.repository.Adw.AlertDialog`\. :param body: the body of ``self`` .. method:: set_body_use_markup(use_markup: bool) -> None Sets whether the body text of ``self`` includes Pango markup. See :obj:`~gi.repository.Pango.parse_markup`\. .. versionadded:: 1.2 .. deprecated:: 1.6 Use :obj:`~gi.repository.Adw.AlertDialog`\. :param use_markup: whether to use markup for body text .. method:: set_close_response(response: str) -> None Sets the ID of the close response of ``self``\. It will be passed to :obj:`~gi.repository.Adw.MessageDialog.signals.response` if the window is closed by pressing :kbd:`Escape` 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``\. .. versionadded:: 1.2 .. deprecated:: 1.6 Use :obj:`~gi.repository.Adw.AlertDialog`\. :param response: the close response ID .. method:: set_default_response(response: str | None = None) -> None Sets the ID of the default response of ``self``\. If set, pressing :kbd:`Enter` will activate the corresponding button. If set to ``NULL`` or to a non-existent response ID, pressing :kbd:`Enter` will do nothing. .. versionadded:: 1.2 .. deprecated:: 1.6 Use :obj:`~gi.repository.Adw.AlertDialog`\. :param response: the default response ID .. method:: set_extra_child(child: ~gi.repository.Gtk.Widget | None = None) -> None Sets the child widget of ``self``\. The child widget is displayed below the heading and body. .. versionadded:: 1.2 .. deprecated:: 1.6 Use :obj:`~gi.repository.Adw.AlertDialog`\. :param child: the child widget .. method:: set_heading(heading: str | None = None) -> None Sets the heading of ``self``\. .. versionadded:: 1.2 .. deprecated:: 1.6 Use :obj:`~gi.repository.Adw.AlertDialog`\. :param heading: the heading of ``self`` .. method:: set_heading_use_markup(use_markup: bool) -> None Sets whether the heading of ``self`` includes Pango markup. See :obj:`~gi.repository.Pango.parse_markup`\. .. versionadded:: 1.2 .. deprecated:: 1.6 Use :obj:`~gi.repository.Adw.AlertDialog`\. :param use_markup: whether to use markup for heading .. method:: set_response_appearance(response: str, appearance: ~gi.repository.Adw.ResponseAppearance) -> None Sets the appearance for ``response``\. .. image:: https://gnome.pages.gitlab.gnome.org/libadwaita/doc/1-latest/message-dialog-appearance.png 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. .. versionadded:: 1.2 .. deprecated:: 1.6 Use :obj:`~gi.repository.Adw.AlertDialog`\. :param response: a response ID :param appearance: appearance for ``response`` .. method:: set_response_enabled(response: str, enabled: bool) -> None Sets whether ``response`` is enabled. If ``response`` is not enabled, the corresponding button will have :obj:`~gi.repository.Gtk.Widget.props.sensitive` set to ``FALSE`` and it can't be activated as a default response. ``response`` can still be used as :obj:`~gi.repository.Adw.MessageDialog.props.close_response` while it's not enabled. Responses are enabled by default. .. versionadded:: 1.2 .. deprecated:: 1.6 Use :obj:`~gi.repository.Adw.AlertDialog`\. :param response: a response ID :param enabled: whether to enable ``response`` .. method:: set_response_label(response: str, label: str) -> None Sets the label of ``response`` to ``label``\. Labels are displayed on the dialog buttons. An embedded underline in ``label`` indicates a mnemonic. .. versionadded:: 1.2 .. deprecated:: 1.6 Use :obj:`~gi.repository.Adw.AlertDialog`\. :param response: a response ID :param label: the label of ``response`` Properties ---------- .. rst-class:: interim-class .. class:: MessageDialog :no-index: .. attribute:: props.body :type: str The type of the None singleton. .. versionadded:: 1.2 .. deprecated:: 1.6 Use :obj:`~gi.repository.Adw.AlertDialog`\. .. attribute:: props.body_use_markup :type: bool The type of the None singleton. .. versionadded:: 1.2 .. deprecated:: 1.6 Use :obj:`~gi.repository.Adw.AlertDialog`\. .. attribute:: props.close_response :type: str The type of the None singleton. .. versionadded:: 1.2 .. deprecated:: 1.6 Use :obj:`~gi.repository.Adw.AlertDialog`\. .. attribute:: props.default_response :type: str The type of the None singleton. .. versionadded:: 1.2 .. deprecated:: 1.6 Use :obj:`~gi.repository.Adw.AlertDialog`\. .. attribute:: props.extra_child :type: ~gi.repository.Gtk.Widget The type of the None singleton. .. versionadded:: 1.2 .. deprecated:: 1.6 Use :obj:`~gi.repository.Adw.AlertDialog`\. .. attribute:: props.heading :type: str The type of the None singleton. .. versionadded:: 1.2 .. deprecated:: 1.6 Use :obj:`~gi.repository.Adw.AlertDialog`\. .. attribute:: props.heading_use_markup :type: bool The type of the None singleton. .. versionadded:: 1.2 .. deprecated:: 1.6 Use :obj:`~gi.repository.Adw.AlertDialog`\. Signals ------- .. rst-class:: interim-class .. class:: MessageDialog.signals :no-index: .. method:: response(response: str) -> None This signal is emitted when the dialog is closed. ``response`` will be set to the response ID of the button that had been activated. if the dialog was closed by pressing :kbd:`Escape` or with a system action, ``response`` will be set to the value of :obj:`~gi.repository.Adw.MessageDialog.props.close_response`\. .. versionadded:: 1.2 .. deprecated:: 1.6 Use :obj:`~gi.repository.Adw.AlertDialog`\. :param response: the response ID Virtual Methods --------------- .. rst-class:: interim-class .. class:: MessageDialog :no-index: .. method:: do_response(response: str) -> None Emits the :obj:`~gi.repository.Adw.MessageDialog.signals.response` signal with the given response ID. Used to indicate that the user has responded to the dialog in some way. .. versionadded:: 1.2 .. deprecated:: 1.6 Use :obj:`~gi.repository.Adw.AlertDialog`\. :param response: response ID Fields ------ .. rst-class:: interim-class .. class:: MessageDialog :no-index: .. attribute:: parent_instance