:right-sidebar: True MessageDialog =================================================================== .. currentmodule:: gi.repository.Adw .. versionadded:: 1.2 .. 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` :Constructors: :: MessageDialog(**properties) new(parent:Gtk.Window=None, heading:str=None, body:str=None) -> Gtk.Widget 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 :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 :param id: the response ID :param label: the response label .. method:: choose(cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[...], None] | None = None, *user_data: ~typing.Any) -> None This function shows ``self`` to the user. The ``callback`` will be called when the alert is dismissed. It should call :obj:`~gi.repository.MessageDialog.choose_finish` to obtain the result. .. versionadded:: 1.3 :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 :param result: a ``GAsyncResult`` .. method:: get_body() -> str Gets the body text of ``self``. .. versionadded:: 1.2 .. method:: get_body_use_markup() -> bool Gets whether the body text of ``self`` includes Pango markup. .. versionadded:: 1.2 .. method:: get_close_response() -> str Gets the ID of the close response of ``self``. .. versionadded:: 1.2 .. method:: get_default_response() -> str | None Gets the ID of the default response of ``self``. .. versionadded:: 1.2 .. method:: get_extra_child() -> ~gi.repository.Gtk.Widget | None Gets the child widget of ``self``. .. versionadded:: 1.2 .. method:: get_heading() -> str | None Gets the heading of ``self``. .. versionadded:: 1.2 .. method:: get_heading_use_markup() -> bool Gets whether the heading of ``self`` includes Pango markup. .. versionadded:: 1.2 .. 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 :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 :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 :param response: a response ID .. method:: has_response(response: str) -> bool Gets whether ``self`` has a response with the ID ``response``. .. versionadded:: 1.2 :param response: response ID .. method:: remove_response(id: str) -> None Removes a response from ``self``. .. versionadded:: 1.5 :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 :param response: response ID .. method:: set_body(body: str) -> None Sets the body text of ``self``. .. versionadded:: 1.2 :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 :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 :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 :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 :param child: the child widget .. method:: set_heading(heading: str | None = None) -> None Sets the heading of ``self``. .. versionadded:: 1.2 :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 :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 :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 :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 :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 .. attribute:: props.body_use_markup :type: bool Whether the body text includes Pango markup. See :obj:`~gi.repository.Pango.parse_markup`. .. versionadded:: 1.2 .. 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 .. attribute:: props.default_response :type: str The response ID of the default response. If set, pressing :kbd:`Enter` will activate the corresponding button. If set to ``NULL`` or a non-existent response ID, pressing :kbd:`Enter` will do nothing. .. versionadded:: 1.2 .. attribute:: props.extra_child :type: ~gi.repository.Gtk.Widget The child widget. Displayed below the heading and body. .. versionadded:: 1.2 .. attribute:: props.heading :type: str The heading of the dialog. .. versionadded:: 1.2 .. attribute:: props.heading_use_markup :type: bool Whether the heading includes Pango markup. See :obj:`~gi.repository.Pango.parse_markup`. .. versionadded:: 1.2 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 :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 :param response: response ID Fields ------ .. rst-class:: interim-class .. class:: MessageDialog :no-index: .. attribute:: parent_instance