class Adw::Toast

Overview

A helper object for #ToastOverlay.

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

WARNING ⚠️ The following code is in c ⚠️

adw_toast_overlay_add_toast (overlay, adw_toast_new (_("Simple Toast")));
toast-simple

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

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

[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.

WARNING ⚠️ The following code is in 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_toast_overlay_add_toast (overlay, toast);
toast-action

Modifying toasts

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

WARNING ⚠️ The following code is in c ⚠️


static void
toast_undo_cb (Gtk::Widget  *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)
{
  Gtk::WidgetClass *widget_class = GTK_WIDGET_CLASS (klass);

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

Defined in:

lib/gi-crystal/src/auto/adw-1/toast.cr

Constructors

Class Method Summary

Instance Method Summary

Instance methods inherited from class GObject::Object

bind_property(source_property : String, target : GObject::Object, target_property : String, flags : GObject::BindingFlags) : GObject::Binding bind_property, bind_property_full(source_property : String, target : GObject::Object, target_property : String, flags : GObject::BindingFlags, transform_to : GObject::Closure, transform_from : GObject::Closure) : GObject::Binding bind_property_full, data(key : String) : Pointer(Void)? data, finalize finalize, freeze_notify : Nil freeze_notify, getv(names : Enumerable(String), values : Enumerable(_)) : Nil getv, notify(property_name : String) : Nil notify, notify_by_pspec(pspec : GObject::ParamSpec) : Nil notify_by_pspec, notify_signal notify_signal, property(property_name : String, value : _) : Nil property, qdata(quark : UInt32) : Pointer(Void)? qdata, ref_count : UInt32 ref_count, run_dispose : Nil run_dispose, set_data(key : String, data : Pointer(Void)?) : Nil set_data, set_property(property_name : String, value : _) : Nil set_property, steal_data(key : String) : Pointer(Void)? steal_data, steal_qdata(quark : UInt32) : Pointer(Void)? steal_qdata, thaw_notify : Nil thaw_notify, to_unsafe : Pointer(Void) to_unsafe, watch_closure(closure : GObject::Closure) : Nil watch_closure

Constructor methods inherited from class GObject::Object

cast(obj : GObject::Object) : self cast, cast?(obj : GObject::Object) : self? cast?, new(pointer : Pointer(Void), transfer : GICrystal::Transfer)
new new, newv(object_type : UInt64, parameters : Enumerable(GObject::Parameter)) : self newv

Class methods inherited from class GObject::Object

compat_control(what : UInt64, data : Pointer(Void)?) : UInt64 compat_control, g_type : UInt64 g_type, interface_find_property(g_iface : GObject::TypeInterface, property_name : String) : GObject::ParamSpec interface_find_property, interface_list_properties(g_iface : GObject::TypeInterface) : Enumerable(GObject::ParamSpec) interface_list_properties

Constructor Detail

def self.new(title : String) : self #

Creates a new Adw::Toast.

The toast will use @title as its title.

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


def self.new #

Initialize a new Toast.


def self.new(*, action_name : String? = nil, action_target : GLib::Variant? = nil, button_label : String? = nil, custom_title : Gtk::Widget? = nil, priority : Adw::ToastPriority? = nil, timeout : UInt32? = nil, title : String? = nil) #

Class Method Detail

def self.g_type : UInt64 #

Returns the type id (GType) registered in GLib type system.


Instance Method Detail

def action_name : String? #

Gets the name of the associated action.


def action_name=(value : String) : String #

def action_name=(action_name : String?) : Nil #

Sets the name of the associated action.

It will be activated when clicking the button.

See [property@Toast:action-target].


def action_target : GLib::Variant? #

def action_target=(value : GLib::Variant?) : GLib::Variant? #

def action_target_value : GLib::Variant? #

Gets the parameter for action invocations.


def action_target_value=(action_target : _?) : Nil #

Sets the parameter for action invocations.

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


def button_clicked_signal #

def button_label : String? #

Gets the label to show on the button.


def button_label=(value : String) : String #

def button_label=(button_label : String?) : Nil #

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


def custom_title : Gtk::Widget? #

Gets the custom title widget of @self.


def custom_title=(widget : Gtk::Widget?) : Nil #

Sets the custom title widget of @self.

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

Setting a custom title will unset Toast::title.


def detailed_action_name=(detailed_action_name : String?) : Nil #

Sets the action name and its parameter.

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


def dismiss : Nil #

Dismisses @self.

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


def dismissed_signal #

def priority : Adw::ToastPriority #

Gets priority for @self.


def priority=(priority : Adw::ToastPriority) : Nil #

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.


def timeout : UInt32 #

Gets timeout for @self.


def timeout=(timeout : UInt32) : Nil #

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.


def title : String? #

Gets the title that will be displayed on the toast.

If a custom title has been set with Adw::Toast#custom_title= the return value will be nil.


def title=(title : String) : Nil #

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

If [property@Toast:custom-title] is set, it will be used instead.