:right-sidebar: True

Toast
===================================================================

.. currentmodule:: gi.repository.Adw





.. class:: Toast(**properties: ~typing.Any)
   :no-contents-entry:


Superclasses: :class:`~gi.repository.GObject.Object`





A helper object for :obj:`~gi.repository.Adw.ToastOverlay`\.

Toasts are meant to be passed into :obj:`~gi.repository.ToastOverlay.add_toast` as
follows:


.. code-block:: c
    :dedent:

    adw_toast_overlay_add_toast (overlay, adw_toast_new (_("Simple Toast")));

.. image:: https://gnome.pages.gitlab.gnome.org/libadwaita/doc/1-latest/toast-simple.png

Toasts always have a close button. They emit the :obj:`~gi.repository.Adw.Toast.signals.dismissed`
signal when disappearing.

:obj:`~gi.repository.Adw.Toast.props.timeout` determines how long the toast stays on screen, while
:obj:`~gi.repository.Adw.Toast.props.priority` determines how it behaves if another toast is
already being displayed.

Toast titles use Pango markup by default, set :obj:`~gi.repository.Adw.Toast.props.use_markup` to
``FALSE`` if this is unwanted.

:obj:`~gi.repository.Adw.Toast.props.custom_title` can be used to replace the title label with a
custom widget.

Actions
--------------------------------------------------------------------------------

Toasts can have one button on them, with a label and an attached
:obj:`~gi.repository.Gio.Action`\.


.. code-block:: c
    :dedent:

    AdwToast *toast = adw_toast_new (_("Toast with Action"));

    adw_toast_set_button_label (toast, _("_Example"));
    adw_toast_set_action_name (toast, "win.example");

    adw_toast_overlay_add_toast (overlay, toast);

.. image:: https://gnome.pages.gitlab.gnome.org/libadwaita/doc/1-latest/toast-action.png

Modifying toasts
--------------------------------------------------------------------------------

Toasts can be modified after they have been shown. For this, an ``AdwToast``
reference must be kept around while the toast is visible.

A common use case for this is using toasts as undo prompts that stack with
each other, allowing to batch undo the last deleted items:


.. code-block:: c
    :dedent:


    static void
    toast_undo_cb (GtkWidget  *sender,
                   const char *action,
                   GVariant   *param)
    {
      // Undo the deletion
    }

    static void
    dismissed_cb (MyWindow *self)
    {
      self->undo_toast = NULL;

      // Permanently delete the items
    }

    static void
    delete_item (MyWindow *self,
                 MyItem   *item)
    {
      g_autofree char *title = NULL;
      int n_items;

      // Mark the item as waiting for deletion
      n_items = ... // The number of waiting items

      if (!self->undo_toast) {
        self->undo_toast = adw_toast_new_format (_("‘%s’ deleted"), ...);

        adw_toast_set_priority (self->undo_toast, ADW_TOAST_PRIORITY_HIGH);
        adw_toast_set_button_label (self->undo_toast, _("_Undo"));
        adw_toast_set_action_name (self->undo_toast, "toast.undo");

        g_signal_connect_swapped (self->undo_toast, "dismissed",
                                  G_CALLBACK (dismissed_cb), self);

        adw_toast_overlay_add_toast (self->toast_overlay, self->undo_toast);

        return;
      }

      title =
        g_strdup_printf (ngettext ("<span font_features='tnum=1'>%d</span> item deleted",
                                   "<span font_features='tnum=1'>%d</span> items deleted",
                                   n_items), n_items);

      adw_toast_set_title (self->undo_toast, title);

      // Bump the toast timeout
      adw_toast_overlay_add_toast (self->toast_overlay, g_object_ref (self->undo_toast));
    }

    static void
    my_window_class_init (MyWindowClass *klass)
    {
      GtkWidgetClass *widget_class = GTK_WIDGET_CLASS (klass);

      gtk_widget_class_install_action (widget_class, "toast.undo", NULL, toast_undo_cb);
    }

.. image:: https://gnome.pages.gitlab.gnome.org/libadwaita/doc/1-latest/toast-undo.png


Constructors
------------

.. rst-class:: interim-class

.. class:: Toast
   :no-index:


   .. classmethod:: new(title: str) -> ~gi.repository.Adw.Toast

      Creates a new ``AdwToast``\.

      The toast will use ``title`` as its title.

      ``title`` can be marked up with the Pango text markup language.






      :param title: the title to be displayed








Methods
-------

.. rst-class:: interim-class

.. class:: Toast
   :no-index:


   .. method:: dismiss() -> None

      Dismisses ``self``\.

      Does nothing if ``self`` has already been dismissed, or hasn't been added to an
      :obj:`~gi.repository.Adw.ToastOverlay`\.










   .. method:: get_action_name() -> str | None

      Gets the name of the associated action.










   .. method:: get_action_target_value() -> ~gi.repository.GLib.Variant | None

      Gets the parameter for action invocations.










   .. method:: get_button_label() -> str | None

      Gets the label to show on the button.










   .. method:: get_custom_title() -> ~gi.repository.Gtk.Widget | None

      Gets the custom title widget of ``self``\.



      .. versionadded:: 1.2








   .. method:: get_priority() -> ~gi.repository.Adw.ToastPriority

      Gets priority for ``self``\.










   .. method:: get_timeout() -> int

      Gets timeout for ``self``\.










   .. method:: get_title() -> str | None

      Gets the title that will be displayed on the toast.

      If a custom title has been set with :obj:`~gi.repository.Adw.Toast.set_custom_title`
      the return value will be :const:`None`.










   .. method:: get_use_markup() -> bool

      Gets whether to use Pango markup for the toast title.



      .. versionadded:: 1.4








   .. method:: set_action_name(action_name: str | None = None) -> None

      Sets the name of the associated action.

      It will be activated when clicking the button.

      See :obj:`~gi.repository.Adw.Toast.props.action_target`\.







      :param action_name: the action name




   .. method:: set_action_target_value(action_target: ~gi.repository.GLib.Variant | None = None) -> None

      Sets the parameter for action invocations.

      If the ``action_target`` variant has a floating reference this function
      will sink it.







      :param action_target: the action target




   .. method:: set_button_label(button_label: str | None = None) -> None

      Sets the label to show on the button.

      Underlines in the button text can be used to indicate a mnemonic.

      If set to ``NULL``\, the button won't be shown.

      See :obj:`~gi.repository.Adw.Toast.props.action_name`\.







      :param button_label: a button label




   .. method:: set_custom_title(widget: ~gi.repository.Gtk.Widget | None = None) -> None

      Sets the custom title widget of ``self``\.

      It will be displayed instead of the title if set. In this case,
      :obj:`~gi.repository.Adw.Toast.props.title` is ignored.

      Setting a custom title will unset :obj:`~gi.repository.Adw.Toast.props.title`\.



      .. versionadded:: 1.2





      :param widget: the custom title widget




   .. method:: set_detailed_action_name(detailed_action_name: str | None = None) -> None

      Sets the action name and its parameter.

      ``detailed_action_name`` is a string in the format accepted by
      :obj:`~gi.repository.Gio.Action.parse_detailed_name`\.







      :param detailed_action_name: the detailed action name




   .. method:: set_priority(priority: ~gi.repository.Adw.ToastPriority) -> None

      Sets priority for ``self``\.

      Priority controls how the toast behaves when another toast is already
      being displayed.

      If ``priority`` is :obj:`~gi.repository.Adw.ToastPriority.normal`\, the toast will be queued.

      If ``priority`` is :obj:`~gi.repository.Adw.ToastPriority.high`\, the toast will be displayed
      immediately, pushing the previous toast into the queue instead.







      :param priority: the priority




   .. method:: set_timeout(timeout: int) -> None

      Sets timeout for ``self``\.

      If ``timeout`` is 0, the toast is displayed indefinitely until manually
      dismissed.

      Toasts cannot disappear while being hovered, pressed (on touchscreen), or
      have keyboard focus inside them.







      :param timeout: the timeout




   .. method:: set_title(title: str) -> None

      Sets the title that will be displayed on the toast.

      The title can be marked up with the Pango text markup language.

      Setting a title will unset :obj:`~gi.repository.Adw.Toast.props.custom_title`\.

      If :obj:`~gi.repository.Adw.Toast.props.custom_title` is set, it will be used instead.







      :param title: a title




   .. method:: set_use_markup(use_markup: bool) -> None

      Whether to use Pango markup for the toast title.

      See also :obj:`~gi.repository.Pango.parse_markup`\.



      .. versionadded:: 1.4





      :param use_markup: whether to use markup








Properties
----------

.. rst-class:: interim-class

.. class:: Toast
   :no-index:
   

   .. attribute:: props.action_name
      :type: str

      The name of the associated action.

      It will be activated when clicking the button.

      See :obj:`~gi.repository.Adw.Toast.props.action_target`\.






   .. attribute:: props.action_target
      :type: ~gi.repository.GLib.Variant

      The parameter for action invocations.






   .. attribute:: props.button_label
      :type: str

      The label to show on the button.

      Underlines in the button text can be used to indicate a mnemonic.

      If set to ``NULL``\, the button won't be shown.

      See :obj:`~gi.repository.Adw.Toast.props.action_name`\.






   .. attribute:: props.custom_title
      :type: ~gi.repository.Gtk.Widget

      The custom title widget.

      It will be displayed instead of the title if set. In this case,
      :obj:`~gi.repository.Adw.Toast.props.title` is ignored.

      Setting a custom title will unset :obj:`~gi.repository.Adw.Toast.props.title`\.


      .. versionadded:: 1.2





   .. attribute:: props.priority
      :type: ~gi.repository.Adw.ToastPriority

      The priority of the toast.

      Priority controls how the toast behaves when another toast is already
      being displayed.

      If the priority is :obj:`~gi.repository.Adw.ToastPriority.normal`\, the toast will be
      queued.

      If the priority is :obj:`~gi.repository.Adw.ToastPriority.high`\, the toast will be
      displayed immediately, pushing the previous toast into the queue instead.






   .. attribute:: props.timeout
      :type: int

      The timeout of the toast, in seconds.

      If timeout is 0, the toast is displayed indefinitely until manually
      dismissed.

      Toasts cannot disappear while being hovered, pressed (on touchscreen), or
      have keyboard focus inside them.






   .. attribute:: props.title
      :type: str

      The title of the toast.

      The title can be marked up with the Pango text markup language.

      Setting a title will unset :obj:`~gi.repository.Adw.Toast.props.custom_title`\.

      If :obj:`~gi.repository.Adw.Toast.props.custom_title` is set, it will be used instead.






   .. attribute:: props.use_markup
      :type: bool

      Whether to use Pango markup for the toast title.

      See also :obj:`~gi.repository.Pango.parse_markup`\.


      .. versionadded:: 1.4









Signals
-------

.. rst-class:: interim-class

.. class:: Toast.signals
   :no-index:
   

   .. method:: button_clicked() -> None

      Emitted after the button has been clicked.

      It can be used as an alternative to setting an action.


      .. versionadded:: 1.2








   .. method:: dismissed() -> None

      Emitted when the toast has been dismissed.