AdwToast

A helper object for class@ToastOverlay.

Toasts are meant to be passed into adw.toast_overlay.ToastOverlay.addToast as follows:

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

<picture> <source srcset="toast-simple-dark.png" media="(prefers-color-scheme: dark)"> <img src="toast-simple.png" alt="toast-simple"> </picture>

Toasts always have a close button. They emit the signal@Toast::dismissed signal when disappearing.

property@Toast:timeout determines how long the toast stays on screen, while property@Toast:priority determines how it behaves if another toast is already being displayed.

Toast titles use Pango markup by default, set property@Toast:use-markup to FALSE if this is unwanted.

property@Toast: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 gio.action.Action.

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);

<picture> <source srcset="toast-action-dark.png" media="(prefers-color-scheme: dark)"> <img src="toast-action.png" alt="toast-action"> </picture>

Modifying toasts

Toasts can be modified after they have been shown. For this, an adw.toast.Toast 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:

1 
2 static void
3 toast_undo_cb (GtkWidget  *sender,
4                const char *action,
5                GVariant   *param)
6 {
7   // Undo the deletion
8 }
9 
10 static void
11 dismissed_cb (MyWindow *self)
12 {
13   self->undo_toast = NULL;
14 
15   // Permanently delete the items
16 }
17 
18 static void
19 delete_item (MyWindow *self,
20              MyItem   *item)
21 {
22   g_autofree char *title = NULL;
23   int n_items;
24 
25   // Mark the item as waiting for deletion
26   n_items = ... // The number of waiting items
27 
28   if (!self->undo_toast) {
29     self->undo_toast = adw_toast_new_format (_("‘%s’ deleted"), ...);
30 
31     adw_toast_set_priority (self->undo_toast, ADW_TOAST_PRIORITY_HIGH);
32     adw_toast_set_button_label (self->undo_toast, _("_Undo"));
33     adw_toast_set_action_name (self->undo_toast, "toast.undo");
34 
35     g_signal_connect_swapped (self->undo_toast, "dismissed",
36                               G_CALLBACK (dismissed_cb), self);
37 
38     adw_toast_overlay_add_toast (self->toast_overlay, self->undo_toast);
39 
40     return;
41   }
42 
43   title =
44     g_strdup_printf (ngettext ("<span font_features='tnum=1'>%d</span> item deleted",
45                                "<span font_features='tnum=1'>%d</span> items deleted",
46                                n_items), n_items);
47 
48   adw_toast_set_title (self->undo_toast, title);
49 
50   // Bump the toast timeout
51   adw_toast_overlay_add_toast (self->toast_overlay, g_object_ref (self->undo_toast));
52 }
53 
54 static void
55 my_window_class_init (MyWindowClass *klass)
56 {
57   GtkWidgetClass *widget_class = GTK_WIDGET_CLASS (klass);
58 
59   gtk_widget_class_install_action (widget_class, "toast.undo", NULL, toast_undo_cb);
60 }

<picture> <source srcset="toast-undo-dark.png" media="(prefers-color-scheme: dark)"> <img src="toast-undo.png" alt="toast-undo"> </picture>