Struct libadwaita::Toast

pub struct Toast { /* private fields */ }

A helper object for ToastOverlay.

Toasts are meant to be passed into ToastOverlay::add_toast() as follows:

⚠️ The following code is in c ⚠️

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

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

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

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

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.

⚠️ The following code is in c ⚠️

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

Modifying toasts

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

⚠️ The following code is in c ⚠️

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

Properties

action-name

The name of the associated action.

It will be activated when clicking the button.

See action-target.

Readable | Writeable

action-target

The parameter for action invocations.

Readable | Writeable

button-label

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 action-name.

Readable | Writeable

custom-title

The custom title widget.

It will be displayed instead of the title if set. In this case, title is ignored.

Setting a custom title will unset title.

Readable | Writeable

priority

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.

Readable | Writeable

timeout

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.

Readable | Writeable

title

The title of the toast.

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

Setting a title will unset custom-title.

If custom-title is set, it will be used instead.

Readable | Writeable

use-markup

Whether to use Pango markup for the toast title.

See also parse_markup().

Readable | Writeable

Signals

button-clicked

Emitted after the button has been clicked.

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

dismissed

Emitted when the toast has been dismissed.

Implements

[trait@glib::ObjectExt]

Implementations

impl Toast

pub fn new(title: &str) -> Toast

Creates a new Toast.

The toast will use @title as its title.

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

title

the title to be displayed

Returns

the new created Toast

pub fn builder() -> ToastBuilder

Creates a new builder-pattern struct instance to construct Toast objects.

This method returns an instance of ToastBuilder which can be used to create Toast objects.

pub fn dismiss(&self)

Dismisses @self.

Does nothing if @self has already been dismissed, or hasn’t been added to an ToastOverlay.

pub fn action_name(&self) -> Option<GString>

Gets the name of the associated action.

Returns

the action name

pub fn action_target_value(&self) -> Option<Variant>

Gets the parameter for action invocations.

Returns

the action target

pub fn button_label(&self) -> Option<GString>

Gets the label to show on the button.

Returns

the button label

pub fn custom_title(&self) -> Option<Widget>

Available on crate feature v1_2 only.

Gets the custom title widget of @self.

Returns

the custom title widget

pub fn priority(&self) -> ToastPriority

Gets priority for @self.

Returns

the priority

pub fn timeout(&self) -> u32

Gets timeout for @self.

Returns

the timeout

pub fn title(&self) -> Option<GString>

Gets the title that will be displayed on the toast.

If a custom title has been set with set_custom_title() the return value will be None.

Returns

the title

pub fn uses_markup(&self) -> bool

Available on crate feature v1_4 only.

Gets whether to use Pango markup for the toast title.

Returns

whether the toast uses markup

pub fn set_action_name(&self, action_name: Option<&str>)

Sets the name of the associated action.

It will be activated when clicking the button.

See action-target.

action_name

the action name

pub fn set_action_target_value(&self, action_target: Option<&Variant>)

Sets the parameter for action invocations.

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

action_target

the action target

pub fn set_button_label(&self, button_label: Option<&str>)

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 action-name.

button_label

a button label

pub fn set_custom_title(&self, widget: Option<&impl IsA<Widget>>)

Available on crate feature v1_2 only.

Sets the custom title widget of @self.

It will be displayed instead of the title if set. In this case, title is ignored.

Setting a custom title will unset title.

widget

the custom title widget

pub fn set_detailed_action_name(&self, detailed_action_name: Option<&str>)

Sets the action name and its parameter.

@detailed_action_name is a string in the format accepted by Gio::Action::parse_detailed_name().

detailed_action_name

the detailed action name

pub fn set_priority(&self, priority: ToastPriority)

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.

priority

the priority

pub fn set_timeout(&self, timeout: u32)

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.

timeout

the timeout

pub fn set_title(&self, title: &str)

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 custom-title.

If custom-title is set, it will be used instead.

title

a title

pub fn set_use_markup(&self, use_markup: bool)

Available on crate feature v1_4 only.

Whether to use Pango markup for the toast title.

See also parse_markup().

use_markup

whether to use markup

pub fn connect_button_clicked<F: Fn(&Self) + 'static>( &self, f: F ) -> SignalHandlerId

Available on crate feature v1_2 only.

Emitted after the button has been clicked.

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

pub fn connect_dismissed<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId

Emitted when the toast has been dismissed.

pub fn connect_action_name_notify<F: Fn(&Self) + 'static>( &self, f: F ) -> SignalHandlerId

pub fn connect_action_target_notify<F: Fn(&Self) + 'static>( &self, f: F ) -> SignalHandlerId

pub fn connect_button_label_notify<F: Fn(&Self) + 'static>( &self, f: F ) -> SignalHandlerId

pub fn connect_custom_title_notify<F: Fn(&Self) + 'static>( &self, f: F ) -> SignalHandlerId

Available on crate feature v1_2 only.

pub fn connect_priority_notify<F: Fn(&Self) + 'static>( &self, f: F ) -> SignalHandlerId

pub fn connect_timeout_notify<F: Fn(&Self) + 'static>( &self, f: F ) -> SignalHandlerId

pub fn connect_title_notify<F: Fn(&Self) + 'static>( &self, f: F ) -> SignalHandlerId

pub fn connect_use_markup_notify<F: Fn(&Self) + 'static>( &self, f: F ) -> SignalHandlerId

Available on crate feature v1_4 only.

impl Toast

pub fn set_action_target(&self, target: Option<&impl ToVariant>)

Sets the parameter for action invocations.

This is a convenience function that calls GLib::Variant::new() for @format_string and uses the result to call set_action_target_value().

If you are setting a string-valued target and want to set the action name at the same time, you can use set_detailed_action_name().

format_string

a variant format string

Trait Implementations

impl Clone for Toast

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Toast

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Toast

fn default() -> Self

Returns the “default value” for a type.

impl HasParamSpec for Toast

type ParamSpec = ParamSpecObject

type SetValue = Toast

Preferred value to be used as setter for the associated ParamSpec.

type BuilderFn = fn(_: &str) -> ParamSpecObjectBuilder<'_, Toast>

fn param_spec_builder() -> Self::BuilderFn

impl Hash for Toast

fn hash<H>(&self, state: &mut H)

where H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for Toast

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized + PartialOrd,

Restrict a value to a certain interval.

impl ParentClassIs for Toast

type Parent = Object

impl<OT: ObjectType> PartialEq<OT> for Toast

fn eq(&self, other: &OT) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<OT: ObjectType> PartialOrd<OT> for Toast

fn partial_cmp(&self, other: &OT) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl StaticType for Toast

fn static_type() -> Type

Returns the type identifier of Self.

impl Eq for Toast