Adw.Toast¶

Subclasses:: None

Methods¶

Inherited:: GObject.Object (37)
Structs:: GObject.ObjectClass (5)

class	`new` (title)
	`dismiss` ()
	`get_action_name` ()
	`get_action_target_value` ()
	`get_button_label` ()
	`get_custom_title` ()
	`get_priority` ()
	`get_timeout` ()
	`get_title` ()
	`get_use_markup` ()
	`set_action_name` (action_name)
	`set_action_target_value` (action_target)
	`set_button_label` (button_label)
	`set_custom_title` (widget)
	`set_detailed_action_name` (detailed_action_name)
	`set_priority` (priority)
	`set_timeout` (timeout)
	`set_title` (title)
	`set_use_markup` (use_markup)

Virtual Methods¶

Inherited:: GObject.Object (7)

Properties¶

Name	Type	Flags
`action-name`	`str`	r/w/en
`action-target`	`GLib.Variant`	r/w/en
`button-label`	`str`	r/w/en
`custom-title`	`Gtk.Widget`	r/w/en
`priority`	`Adw.ToastPriority`	r/w/en
`timeout`	`int`	r/w/en
`title`	`str`	r/w/en
`use-markup`	`bool`	r/w/en

Signals¶

Inherited:: GObject.Object (1)

Name	Short Description
`button-clicked`	Emitted after the button has been clicked.
`dismissed`	Emitted when the toast has been dismissed.

Fields¶

Inherited:: GObject.Object (1)

Class Details¶

class Adw.Toast(**kwargs)¶

Bases:: GObject.Object
Abstract:: No
Structure:: Adw.ToastClass

A helper object for [class`ToastOverlay`].

Toasts are meant to be passed into [method`ToastOverlay`.add_toast] as follows:

``c adw_toast_overlay_add_toast (overlay, adw_toast_new (_(“Simple Toast”))); ``

Toasts always have a close button. They emit the [signal`Toast`:py:func:::dismissed<Adw.Toast.signals.dismissed>] signal when disappearing.

[property`Toast`:py:data::timeout<Adw.Toast.props.timeout>] determines how long the toast stays on screen, while [property`Toast`:py:data::priority<Adw.Toast.props.priority>] determines how it behaves if another toast is already being displayed.

Toast titles use Pango markup by default, set [property`Toast`:py:data::use-markup<Adw.Toast.props.use_markup>] to FALSE if this is unwanted.

[property`Toast`:py:data::custom-title<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 [iface`Gio`.Action].

```c Adw.Toast *toast = Adw.Toast.new (_(“Toast with Action”));

Adw.Toast.set_button_label (toast, _(”_Example”)); Adw.Toast.set_action_name (toast, “win.example”);

Adw.ToastOverlay.add_toast (overlay, toast); ```

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:

```c

static void toast_undo_cb (Gtk.Widget *sender, const str *action, GLib.Variant *param) { // Undo the deletion }

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

// Permanently delete the items }

static void delete_item (MyWindow *self, MyItem *item) { g_autofree str *title = None; 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.ToastPriority.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.ToastOverlay.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.ToastOverlay.add_toast (self->toast_overlay, GObject.Object.ref (self->undo_toast)); }

static void my_window_class_init (MyWindowClass *klass) { Gtk.WidgetClass *widget_class = GTK_WIDGET_CLASS (klass);

Gtk.WidgetClass.install_action (widget_class, “toast.undo”, None, toast_undo_cb); } ```

classmethod new(title)¶

Parameters:: title (str) – the title to be displayed
Returns:: the new created AdwToast
Return type:: 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.

dismiss()¶

Dismisses self.

Does nothing if self has already been dismissed, or hasn’t been added to an [class`ToastOverlay`].

get_action_name()¶

Returns:: the action name
Return type:: str or None

Gets the name of the associated action.

get_action_target_value()¶

Returns:: the action target
Return type:: GLib.Variant or None

Gets the parameter for action invocations.

get_button_label()¶

Returns:: the button label
Return type:: str or None

Gets the label to show on the button.

get_custom_title()¶

Returns:: the custom title widget
Return type:: Gtk.Widget or None

Gets the custom title widget of self.

New in version 1.2.

get_priority()¶

Returns:: the priority
Return type:: Adw.ToastPriority

Gets priority for self.

get_timeout()¶

Returns:: the timeout
Return type:: int

Gets timeout for self.

get_title()¶

Returns:: the title
Return type:: str or None

Gets the title that will be displayed on the toast.

If a custom title has been set with [method`Adw`.Toast.set_custom_title] the return value will be None.

get_use_markup()¶

Returns:: whether the toast uses markup
Return type:: bool

Gets whether to use Pango markup for the toast title.

New in version 1.4.

set_action_name(action_name)¶

Parameters:: action_name (str or None) – the action name

Sets the name of the associated action.

It will be activated when clicking the button.

See [property`Toast`:py:data::action-target<Adw.Toast.props.action_target>].

set_action_target_value(action_target)¶

Parameters:: action_target (GLib.Variant or None) – the action target

Sets the parameter for action invocations.

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

set_button_label(button_label)¶

Parameters:: button_label (str or None) – a button label

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 [property`Toast`:py:data::action-name<Adw.Toast.props.action_name>].

set_custom_title(widget)¶

Parameters:: widget (Gtk.Widget or None) – the custom title widget

Sets the custom title widget of self.

It will be displayed instead of the title if set. In this case, [property`Toast`:py:data::title<Adw.Toast.props.title>] is ignored.

Setting a custom title will unset [property`Toast`:py:data::title<Adw.Toast.props.title>].

New in version 1.2.

set_detailed_action_name(detailed_action_name)¶

Parameters:: detailed_action_name (str or None) – the detailed action name

Sets the action name and its parameter.

detailed_action_name is a string in the format accepted by [func`Gio`.Action.parse_detailed_name].

set_priority(priority)¶

Parameters:: priority (Adw.ToastPriority) – the priority

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.

set_timeout(timeout)¶

Parameters:: timeout (int) – the timeout

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.

set_title(title)¶

Parameters:: title (str) – a title

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 [property`Toast`:py:data::custom-title<Adw.Toast.props.custom_title>].

If [property`Toast`:py:data::custom-title<Adw.Toast.props.custom_title>] is set, it will be used instead.

set_use_markup(use_markup)¶

Parameters:: use_markup (bool) – whether to use markup

Whether to use Pango markup for the toast title.

Signal Details¶

Adw.Toast.signals.button_clicked(toast)¶

Signal Name:: button-clicked
Flags:: RUN_LAST
Parameters:: toast (Adw.Toast) – The object which received the signal

Emitted after the button has been clicked.

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

New in version 1.2.

Adw.Toast.signals.dismissed(toast)¶

Signal Name:: dismissed
Flags:: RUN_FIRST
Parameters:: toast (Adw.Toast) – The object which received the signal

Emitted when the toast has been dismissed.

Property Details¶

Adw.Toast.props.action_name¶

Name:: action-name
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

The name of the associated action.

It will be activated when clicking the button.

See [property`Toast`:py:data::action-target<Adw.Toast.props.action_target>].

Adw.Toast.props.action_target¶

Name:: action-target
Type:: GLib.Variant
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

The parameter for action invocations.

Adw.Toast.props.button_label¶

Name:: button-label
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

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 [property`Toast`:py:data::action-name<Adw.Toast.props.action_name>].

Adw.Toast.props.custom_title¶

Name:: custom-title
Type:: Gtk.Widget
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

The custom title widget.

It will be displayed instead of the title if set. In this case, [property`Toast`:py:data::title<Adw.Toast.props.title>] is ignored.

Setting a custom title will unset [property`Toast`:py:data::title<Adw.Toast.props.title>].

New in version 1.2.

Adw.Toast.props.priority¶

Name:: priority
Type:: Adw.ToastPriority
Default Value:: Adw.ToastPriority.NORMAL
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

The priority of the toast.

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

If the priority is ADW_TOAST_PRIORITY_NORMAL, the toast will be queued.

If the priority is ADW_TOAST_PRIORITY_HIGH, the toast will be displayed immediately, pushing the previous toast into the queue instead.

Adw.Toast.props.timeout¶

Name:: timeout
Type:: int
Default Value:: 5
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

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.

Adw.Toast.props.title¶

Name:: title
Type:: str
Default Value:: ''
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

The title of the toast.

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

Setting a title will unset [property`Toast`:py:data::custom-title<Adw.Toast.props.custom_title>].

If [property`Toast`:py:data::custom-title<Adw.Toast.props.custom_title>] is set, it will be used instead.

Adw.Toast.props.use_markup¶

Name:: use-markup
Type:: bool
Default Value:: True
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Whether to use Pango markup for the toast title.