gi-adwaita-1.0.7: Adwaita bindings
CopyrightWill Thompson and Iñaki García Etxebarria
LicenseLGPL-2.1
MaintainerIñaki García Etxebarria
Safe HaskellSafe-Inferred
LanguageHaskell2010

GI.Adw.Objects.Toast

Description

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.

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

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>

Synopsis

Exported types

newtype Toast Source #

Memory-managed wrapper type.

Constructors

Toast (ManagedPtr Toast) 

Instances

Instances details
Eq Toast Source # 
Instance details

Defined in GI.Adw.Objects.Toast

Methods

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

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

GObject Toast Source # 
Instance details

Defined in GI.Adw.Objects.Toast

ManagedPtrNewtype Toast Source # 
Instance details

Defined in GI.Adw.Objects.Toast

Methods

toManagedPtr :: Toast -> ManagedPtr Toast

TypedObject Toast Source # 
Instance details

Defined in GI.Adw.Objects.Toast

Methods

glibType :: IO GType

HasParentTypes Toast Source # 
Instance details

Defined in GI.Adw.Objects.Toast

IsGValue (Maybe Toast) Source #

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

Instance details

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 Source # 
Instance details

Defined in GI.Adw.Objects.Toast

type ParentTypes Toast = '[Object]

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

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

Instances

Instances details
(GObject o, IsDescendantOf Toast o) => IsToast o Source # 
Instance details

Defined in GI.Adw.Objects.Toast

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

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

Methods

dismiss

toastDismiss Source #

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

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

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

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

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

Arguments

:: (HasCallStack, MonadIO m, IsToast a) 
=> a

self: a toast

-> m ToastPriority

Returns: the priority

Gets priority for self.

getTimeout

toastGetTimeout Source #

Arguments

:: (HasCallStack, MonadIO m, IsToast a) 
=> a

self: a toast

-> m Word32

Returns: the timeout

Gets timeout for self.

getTitle

toastGetTitle Source #

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.

getUseMarkup

toastGetUseMarkup Source #

Arguments

:: (HasCallStack, MonadIO m, IsToast a) 
=> a

self: a toast

-> m Bool

Returns: whether the toast uses markup

Gets whether to use Pango markup for the toast title.

Since: 1.4

new

toastNew Source #

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

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

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

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

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

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

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

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

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.

setUseMarkup

toastSetUseMarkup Source #

Arguments

:: (HasCallStack, MonadIO m, IsToast a) 
=> a

self: a toast

-> Bool

useMarkup: whether to use markup

-> m () 

Whether to use Pango markup for the toast title.

See also parseMarkup.

Since: 1.4

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 () Source #

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) Source #

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) Source #

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 () Source #

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 () Source #

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) Source #

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) Source #

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 () Source #

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 () Source #

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) Source #

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) Source #

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 () Source #

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 () Source #

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) Source #

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) Source #

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 () Source #

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) Source #

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

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 () Source #

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) Source #

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

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 () Source #

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) Source #

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) Source #

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 () Source #

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

set toast [ #title := value ]

useMarkup

Whether to use Pango markup for the toast title.

See also parseMarkup.

Since: 1.4

constructToastUseMarkup :: (IsToast o, MonadIO m) => Bool -> m (GValueConstruct o) Source #

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

getToastUseMarkup :: (MonadIO m, IsToast o) => o -> m Bool Source #

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

get toast #useMarkup

setToastUseMarkup :: (MonadIO m, IsToast o) => o -> Bool -> m () Source #

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

set toast [ #useMarkup := value ]

Signals

buttonClicked

type ToastButtonClickedCallback = IO () Source #

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

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

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 () Source #

Emitted when the toast has been dismissed.

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

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

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