: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 ``ADW_TOAST_PRIORITY_NORMAL``\, the toast will be queued.

      If ``priority`` is ``ADW_TOAST_PRIORITY_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 type of the None singleton.







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

      The type of the None singleton.







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

      The type of the None singleton.







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

      The type of the None singleton.



      .. versionadded:: 1.2





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

      The type of the None singleton.







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

      The type of the None singleton.







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

      The type of the None singleton.







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

      The type of the None singleton.



      .. versionadded:: 1.4









Signals
-------

.. rst-class:: interim-class

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

   .. method:: button_clicked() -> None

      The type of the None singleton.



      .. versionadded:: 1.2








   .. method:: dismissed() -> None

      The type of the None singleton.