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.

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.

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

==(other : self) ==, 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) | Nil data, finalize finalize, freeze_notify : Nil freeze_notify, getv(names : Enumerable(String), values : Enumerable(_)) : Nil getv, hash(hasher) hash, 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) | Nil qdata, ref_count : UInt32 ref_count, run_dispose : Nil run_dispose, set_data(key : String, data : Pointer(Void) | Nil) : Nil set_data, set_property(property_name : String, value : _) : Nil set_property, steal_data(key : String) : Pointer(Void) | Nil steal_data, steal_qdata(quark : UInt32) : Pointer(Void) | Nil 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, 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

cast?(obj : GObject::Object) : self | Nil cast?, compat_control(what : UInt64, data : Pointer(Void) | Nil) : 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

Macros inherited from class GObject::Object

previous_vfunc(*args) previous_vfunc, previous_vfunc!(*args) previous_vfunc!, signal(signature) signal

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 = nil, action_target : GLib::Variant | Nil = nil, button_label : String | Nil = nil, custom_title : Gtk::Widget | Nil = nil, priority : Adw::ToastPriority | Nil = nil, timeout : UInt32 | Nil = nil, title : String | Nil = nil, use_markup : Bool | Nil = nil) #

Class Method Detail

def self.g_type : UInt64 #

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


Instance Method Detail

def ==(other : self) #
Description copied from class Reference

Returns true if this reference is the same as other. Invokes same?.


def action_name : String | Nil #

Gets the name of the associated action.


def action_name=(value : String) : String #

def action_name=(value : Nil) : Nil #

Set #action_name property to nil.


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

Sets the name of the associated action.

It will be activated when clicking the button.

See [property@Toast:action-target].


def action_name? : String | Nil #

Same as #action_name, but can return nil.


def action_target : GLib::Variant | Nil #

def action_target=(value : GLib::Variant | Nil) : GLib::Variant | Nil #

def action_target_value : GLib::Variant | Nil #

Gets the parameter for action invocations.


def action_target_value=(action_target : _ | Nil) : 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 | Nil #

Gets the label to show on the button.


def button_label=(value : String) : String #

def button_label=(value : Nil) : Nil #

Set #button_label property to nil.


def button_label=(button_label : String | Nil) : 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 button_label? : String | Nil #

Same as #button_label, but can return nil.


def custom_title : Gtk::Widget | Nil #

Gets the custom title widget of self.


def custom_title=(widget : Gtk::Widget | Nil) : 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) : 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 hash(hasher) #
Description copied from class Reference

See Object#hash(hasher)


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 | Nil #

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.


def title=(value : Nil) : Nil #

Set #title property to nil.


def title? : String | Nil #

Same as #title, but can return nil.


def use_markup : Bool #

Gets whether to use Pango markup for the toast title.


def use_markup=(use_markup : Bool) : Nil #

Whether to use Pango markup for the toast title.

See also Pango::parse_markup.


def use_markup? : Bool #