GI.Adw.Objects.Toast

A helper object for [classtoastOverlay].

Toasts are meant to be passed into [methodtoastOverlay.add_toast] as follows:

c code

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 signaltoast[dismissed] signal when disappearing.

propertytoast:timeout

determines how long the toast stays on screen, while

propertytoast:priority

determines how it behaves if another toast is already being displayed.

propertytoast: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 Action.

c code

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 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 code

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

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

Exported types

newtype Toast

Memory-managed wrapper type.

Constructors

Toast (ManagedPtr Toast)

Instances

Eq Toast

Defined in GI.Adw.Objects.Toast

Methods

(==) :: Toast -> Toast -> Bool

(/=) :: Toast -> Toast -> Bool

GObject Toast

Defined in GI.Adw.Objects.Toast

ManagedPtrNewtype Toast

Defined in GI.Adw.Objects.Toast

Methods

toManagedPtr :: Toast -> ManagedPtr Toast

TypedObject Toast

Defined in GI.Adw.Objects.Toast

Methods

glibType :: IO GType

HasParentTypes Toast

Defined in GI.Adw.Objects.Toast

IsGValue (Maybe Toast)

Convert Toast to and from GValue. See toGValue and fromGValue.

Defined in GI.Adw.Objects.Toast

Methods

gvalueGType_ :: IO GType

gvalueSet_ :: Ptr GValue -> Maybe Toast -> IO ()

gvalueGet_ :: Ptr GValue -> IO (Maybe Toast)

type ParentTypes Toast

Defined in GI.Adw.Objects.Toast

type ParentTypes Toast = '[Object]

class (GObject o, IsDescendantOf Toast o) => IsToast o

Type class for types which can be safely cast to Toast, for instance with toToast.

Instances

(GObject o, IsDescendantOf Toast o) => IsToast o

Defined in GI.Adw.Objects.Toast

toToast :: (MonadIO m, IsToast o) => o -> m Toast

Cast to Toast, for types for which this is known to be safe. For general casts, use castTo.

Methods

Click to display all available methods, including inherited ones

Methods

bindProperty, bindPropertyFull, dismiss, forceFloating, freezeNotify, getv, isFloating, notify, notifyByPspec, ref, refSink, runDispose, stealData, stealQdata, thawNotify, unref, watchClosure.

Getters

getActionName, getActionTargetValue, getButtonLabel, getCustomTitle, getData, getPriority, getProperty, getQdata, getTimeout, getTitle.

Setters

setActionName, setActionTargetValue, setButtonLabel, setCustomTitle, setData, setDataFull, setDetailedActionName, setPriority, setProperty, setTimeout, setTitle.

dismiss

toastDismiss

Arguments

:: (HasCallStack, MonadIO m, IsToast a)

=> a

self: a toast

-> m ()

Dismisses self.

Does nothing if self has already been dismissed, or hasn't been added to an [classtoastOverlay].

getActionName

toastGetActionName

Arguments

:: (HasCallStack, MonadIO m, IsToast a)

=> a

self: a toast

-> m (Maybe Text)

Returns: the action name

Gets the name of the associated action.

getActionTargetValue

toastGetActionTargetValue

Arguments

:: (HasCallStack, MonadIO m, IsToast a)

=> a

self: a toast

-> m (Maybe GVariant)

Returns: the action target

Gets the parameter for action invocations.

getButtonLabel

toastGetButtonLabel

Arguments

:: (HasCallStack, MonadIO m, IsToast a)

=> a

self: a toast

-> m (Maybe Text)

Returns: the button label

Gets the label to show on the button.

getCustomTitle

toastGetCustomTitle

Arguments

:: (HasCallStack, MonadIO m, IsToast a)

=> a

self: a toast

-> m (Maybe Widget)

Returns: the custom title widget

Gets the custom title widget of self.

Since: 1.2

getPriority

toastGetPriority

Arguments

:: (HasCallStack, MonadIO m, IsToast a)

=> a

self: a toast

-> m ToastPriority

Returns: the priority

Gets priority for self.

getTimeout

toastGetTimeout

Arguments

:: (HasCallStack, MonadIO m, IsToast a)

=> a

self: a toast

-> m Word32

Returns: the timeout

Gets timeout for self.

getTitle

toastGetTitle

Arguments

:: (HasCallStack, MonadIO m, IsToast a)

=> a

self: a toast

-> m (Maybe Text)

Returns: the title

Gets the title that will be displayed on the toast.

If a custom title has been set with toastSetCustomTitle the return value will be Nothing.

new

toastNew

Arguments

:: (HasCallStack, MonadIO m)

=> Text

title: the title to be displayed

-> m Toast

Returns: the new created AdwToast

Creates a new AdwToast.

The toast will use title as its title.

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

setActionName

toastSetActionName

Arguments

:: (HasCallStack, MonadIO m, IsToast a)

=> a

self: a toast

-> Maybe Text

actionName: the action name

-> m ()

Sets the name of the associated action.

It will be activated when clicking the button.

See [propertytoast:action-target].

setActionTargetValue

toastSetActionTargetValue

Arguments

:: (HasCallStack, MonadIO m, IsToast a)

=> a

self: a toast

-> Maybe GVariant

actionTarget: the action target

-> m ()

Sets the parameter for action invocations.

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

setButtonLabel

toastSetButtonLabel

Arguments

:: (HasCallStack, MonadIO m, IsToast a)

=> a

self: a toast

-> Maybe Text

buttonLabel: a button label

-> m ()

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

setCustomTitle

toastSetCustomTitle

Arguments

:: (HasCallStack, MonadIO m, IsToast a, IsWidget b)

=> a

self: a toast

-> Maybe b

widget: the custom title widget

-> m ()

Sets the custom title widget of self.

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

Setting a custom title will unset [propertytoast:title].

Since: 1.2

setDetailedActionName

toastSetDetailedActionName

Arguments

:: (HasCallStack, MonadIO m, IsToast a)

=> a

self: a toast

-> Maybe Text

detailedActionName: the detailed action name

-> m ()

Sets the action name and its parameter.

detailedActionName is a string in the format accepted by [funcgio.Action.parse_detailed_name].

setPriority

toastSetPriority

Arguments

:: (HasCallStack, MonadIO m, IsToast a)

=> a

self: a toast

-> ToastPriority

priority: the priority

-> m ()

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.

setTimeout

toastSetTimeout

Arguments

:: (HasCallStack, MonadIO m, IsToast a)

=> a

self: a toast

-> Word32

timeout: the timeout

-> m ()

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.

setTitle

toastSetTitle

Arguments

:: (HasCallStack, MonadIO m, IsToast a)

=> a

self: a toast

-> Text

title: a title

-> m ()

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

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

Properties

actionName

The name of the associated action.

It will be activated when clicking the button.

See [propertytoast:action-target].

clearToastActionName :: (MonadIO m, IsToast o) => o -> m ()

Set the value of the “action-name” property to Nothing. When overloading is enabled, this is equivalent to

clear #actionName

constructToastActionName :: (IsToast o, MonadIO m) => Text -> m (GValueConstruct o)

Construct a GValueConstruct with valid value for the “action-name” property. This is rarely needed directly, but it is used by new.

getToastActionName :: (MonadIO m, IsToast o) => o -> m (Maybe Text)

Get the value of the “action-name” property. When overloading is enabled, this is equivalent to

get toast #actionName

setToastActionName :: (MonadIO m, IsToast o) => o -> Text -> m ()

Set the value of the “action-name” property. When overloading is enabled, this is equivalent to

set toast [ #actionName := value ]

actionTarget

The parameter for action invocations.

clearToastActionTarget :: (MonadIO m, IsToast o) => o -> m ()

Set the value of the “action-target” property to Nothing. When overloading is enabled, this is equivalent to

clear #actionTarget

constructToastActionTarget :: (IsToast o, MonadIO m) => GVariant -> m (GValueConstruct o)

Construct a GValueConstruct with valid value for the “action-target” property. This is rarely needed directly, but it is used by new.

getToastActionTarget :: (MonadIO m, IsToast o) => o -> m (Maybe GVariant)

Get the value of the “action-target” property. When overloading is enabled, this is equivalent to

get toast #actionTarget

setToastActionTarget :: (MonadIO m, IsToast o) => o -> GVariant -> m ()

Set the value of the “action-target” property. When overloading is enabled, this is equivalent to

set toast [ #actionTarget := value ]

buttonLabel

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

clearToastButtonLabel :: (MonadIO m, IsToast o) => o -> m ()

Set the value of the “button-label” property to Nothing. When overloading is enabled, this is equivalent to

clear #buttonLabel

constructToastButtonLabel :: (IsToast o, MonadIO m) => Text -> m (GValueConstruct o)

Construct a GValueConstruct with valid value for the “button-label” property. This is rarely needed directly, but it is used by new.

getToastButtonLabel :: (MonadIO m, IsToast o) => o -> m (Maybe Text)

Get the value of the “button-label” property. When overloading is enabled, this is equivalent to

get toast #buttonLabel

setToastButtonLabel :: (MonadIO m, IsToast o) => o -> Text -> m ()

Set the value of the “button-label” property. When overloading is enabled, this is equivalent to

set toast [ #buttonLabel := value ]

customTitle

The custom title widget.

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

Setting a custom title will unset [propertytoast:title].

Since: 1.2

clearToastCustomTitle :: (MonadIO m, IsToast o) => o -> m ()

Set the value of the “custom-title” property to Nothing. When overloading is enabled, this is equivalent to

clear #customTitle

constructToastCustomTitle :: (IsToast o, MonadIO m, IsWidget a) => a -> m (GValueConstruct o)

Construct a GValueConstruct with valid value for the “custom-title” property. This is rarely needed directly, but it is used by new.

getToastCustomTitle :: (MonadIO m, IsToast o) => o -> m (Maybe Widget)

Get the value of the “custom-title” property. When overloading is enabled, this is equivalent to

get toast #customTitle

setToastCustomTitle :: (MonadIO m, IsToast o, IsWidget a) => o -> a -> m ()

Set the value of the “custom-title” property. When overloading is enabled, this is equivalent to

set toast [ #customTitle := value ]

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.

constructToastPriority :: (IsToast o, MonadIO m) => ToastPriority -> m (GValueConstruct o)

Construct a GValueConstruct with valid value for the “priority” property. This is rarely needed directly, but it is used by new.

getToastPriority :: (MonadIO m, IsToast o) => o -> m ToastPriority

Get the value of the “priority” property. When overloading is enabled, this is equivalent to

get toast #priority

setToastPriority :: (MonadIO m, IsToast o) => o -> ToastPriority -> m ()

Set the value of the “priority” property. When overloading is enabled, this is equivalent to

set toast [ #priority := value ]

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.

constructToastTimeout :: (IsToast o, MonadIO m) => Word32 -> m (GValueConstruct o)

Construct a GValueConstruct with valid value for the “timeout” property. This is rarely needed directly, but it is used by new.

getToastTimeout :: (MonadIO m, IsToast o) => o -> m Word32

Get the value of the “timeout” property. When overloading is enabled, this is equivalent to

get toast #timeout

setToastTimeout :: (MonadIO m, IsToast o) => o -> Word32 -> m ()

Set the value of the “timeout” property. When overloading is enabled, this is equivalent to

set toast [ #timeout := value ]

title

The title of the toast.

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

Setting a title will unset [propertytoast:custom-title].

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

constructToastTitle :: (IsToast o, MonadIO m) => Text -> m (GValueConstruct o)

Construct a GValueConstruct with valid value for the “title” property. This is rarely needed directly, but it is used by new.

getToastTitle :: (MonadIO m, IsToast o) => o -> m (Maybe Text)

Get the value of the “title” property. When overloading is enabled, this is equivalent to

get toast #title

setToastTitle :: (MonadIO m, IsToast o) => o -> Text -> m ()

Set the value of the “title” property. When overloading is enabled, this is equivalent to

set toast [ #title := value ]

Signals

buttonClicked

type ToastButtonClickedCallback = IO ()

Emitted after the button has been clicked.

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

Since: 1.2

afterToastButtonClicked :: (IsToast a, MonadIO m) => a -> ((?self :: a) => ToastButtonClickedCallback) -> m SignalHandlerId

Connect a signal handler for the buttonClicked signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after toast #buttonClicked callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit ?self parameter. Note that this requires activating the ImplicitParams GHC extension.

onToastButtonClicked :: (IsToast a, MonadIO m) => a -> ((?self :: a) => ToastButtonClickedCallback) -> m SignalHandlerId

Connect a signal handler for the buttonClicked signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on toast #buttonClicked callback

dismissed

type ToastDismissedCallback = IO ()

Emitted when the toast has been dismissed.

afterToastDismissed :: (IsToast a, MonadIO m) => a -> ((?self :: a) => ToastDismissedCallback) -> m SignalHandlerId

Connect a signal handler for the dismissed signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after toast #dismissed callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit ?self parameter. Note that this requires activating the ImplicitParams GHC extension.

onToastDismissed :: (IsToast a, MonadIO m) => a -> ((?self :: a) => ToastDismissedCallback) -> m SignalHandlerId

Connect a signal handler for the dismissed signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on toast #dismissed callback