: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 :obj:`~gi.repository.Gtk.AccessibleRole.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(self) -> str :async: This is the `awaitable `_ version of :meth:`choose`. .. versionadded:: 1.3 .. deprecated:: 1.6 Use :obj:`~gi.repository.Adw.AlertDialog`\. .. method:: choose(cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~collections.abc.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``\. The button corresponding to this response will be set as the default widget of ``self``\. If not set, the default widget will not be set, and the last added response will be focused by default. See :obj:`~gi.repository.Gtk.Window.props.default_widget`\. .. 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 :obj:`~gi.repository.Adw.ResponseAppearance.suggested` to mark important responses such as the affirmative action, like the Save button in the example. Use :obj:`~gi.repository.Adw.ResponseAppearance.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 :obj:`~gi.repository.Adw.ResponseAppearance.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 body text of the dialog. .. versionadded:: 1.2 .. deprecated:: 1.6 Use :obj:`~gi.repository.Adw.AlertDialog`\. .. attribute:: props.body_use_markup :type: bool Whether the body text includes Pango markup. See :obj:`~gi.repository.Pango.parse_markup`\. .. versionadded:: 1.2 .. deprecated:: 1.6 Use :obj:`~gi.repository.Adw.AlertDialog`\. .. attribute:: props.close_response :type: str The ID of the close response. 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`\. .. attribute:: props.default_response :type: str The response ID of the default response. The button corresponding to this response will be set as the default widget of the dialog. If not set, the default widget will not be set, and the last added response will be focused by default. See :obj:`~gi.repository.Gtk.Window.props.default_widget`\. .. versionadded:: 1.2 .. deprecated:: 1.6 Use :obj:`~gi.repository.Adw.AlertDialog`\. .. attribute:: props.extra_child :type: ~gi.repository.Gtk.Widget The child widget. Displayed below the heading and body. .. versionadded:: 1.2 .. deprecated:: 1.6 Use :obj:`~gi.repository.Adw.AlertDialog`\. .. attribute:: props.heading :type: str The heading of the dialog. .. versionadded:: 1.2 .. deprecated:: 1.6 Use :obj:`~gi.repository.Adw.AlertDialog`\. .. attribute:: props.heading_use_markup :type: bool Whether the heading includes Pango markup. See :obj:`~gi.repository.Pango.parse_markup`\. .. 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