Documentation
¶
Overview ¶
Package toast bridges a decoded freedesktop github.com/go-freedesktop/notifications.Notification onto a github.com/go-widgets/toolkit.Toast widget, so a go-widgets desktop can render notification bubbles and act as the notification daemon.
ToToast is a pure function (no build tags, no I/O): it maps the notification's fields onto a Toast per the specification, wiring each action button to an emit callback. Daemon layers a small, platform-neutral stack manager and expiry tick loop on top, driving the two spec signals through an Emitter; the Linux D-Bus server (github.com/go-freedesktop/notifications.Server) satisfies Emitter.
Index ¶
Constants ¶
const ( // TickMS is the assumed interval between Tick calls, in milliseconds. TickMS = 100 // DefaultExpireMS is the lifetime used when the client asks for the // server default (a timeout of -1). DefaultExpireMS = 5000 )
Timing constants translating a notification timeout (in milliseconds) into a Toast Life budget (a count of toolkit.Toast.Tick calls). A daemon calls Tick every TickMS milliseconds, so Life = round(timeout / TickMS).
const DefaultCap = 100
DefaultCap is the default upper bound on the number of live notifications a Daemon keeps at once. When a new notification would exceed the cap the oldest live one is retired (closed, reason expired), so a flood of notifications can never grow the in-memory store without bound.
Variables ¶
This section is empty.
Functions ¶
func KindFor ¶
func KindFor(n *notifications.Notification) toolkit.ToastKind
KindFor maps a notification's urgency onto a Toast kind: Critical urgency is an error pill, everything else an info pill (matching the advertised capability set, which does not distinguish success/warning).
func LifeFor ¶
func LifeFor(n *notifications.Notification) int
LifeFor maps a notification's requested timeout onto a Toast Life budget: 0 (the sticky sentinel) when the notification should persist until dismissed, otherwise the number of Tick calls covering the timeout (at least 1).
func ToToast ¶
func ToToast(n *notifications.Notification, theme *toolkit.Theme, icons IconLookup, onAction ActionFunc) *toolkit.Toast
ToToast builds a Toast from a decoded notification. Summary and body become the Toast's stacked Lines (body markup stripped to plain text, honouring the advertised "body-markup" capability); urgency selects the Kind; the timeout (or resident/critical stickiness) sets Life; each non-default action becomes a right-edge button whose Callback emits ActionInvoked through onAction; and an inline image, image-path or app_icon (resolved through icons, in that order of preference) becomes the leading icon. The theme is accepted for API symmetry with the toolkit draw path and future themed tinting.
Types ¶
type ActionFunc ¶
ActionFunc receives the (notification id, action key) pair when a Toast action button is clicked. ToToast wires it to every rendered button's Callback so a click drives an ActionInvoked emission. A nil ActionFunc makes the buttons inert (they still dismiss the toast).
type Daemon ¶
type Daemon struct {
// Host is the rectangle the toast stack anchors inside; Corner is the
// corner it docks to. Both may be set before use (defaults: a 400x600
// region docked BottomRight).
Host toolkit.Rect
Corner toolkit.Corner
// Cap bounds the number of live notifications kept at once (default
// DefaultCap). A value <= 0 means unbounded. When a new notification
// would exceed Cap the oldest live one is retired.
Cap int
// contains filtered or unexported fields
}
Daemon is a platform-neutral notification-surface manager: it implements notifications.Handler, keeping a corner-anchored stack of Toasts, ticking their lifetimes and emitting NotificationClosed with the right reason -- expiry (1), dismissal (2) or a CloseNotification call (3, emitted by the server itself). It is safe for concurrent use.
A go-widgets desktop wires a Daemon to a notifications.Server as its Handler, calls Tick from its animation loop, renders Toasts, and routes pointer clicks into each Toast (whose action buttons call back into the Daemon to emit ActionInvoked). Host and Corner control where the stack anchors.
func NewDaemon ¶
func NewDaemon(emit Emitter, theme *toolkit.Theme, icons IconLookup) *Daemon
NewDaemon returns a Daemon that emits signals through emit, renders Toasts with theme, and resolves icons through icons (which may be nil).
func (*Daemon) Dismiss ¶
Dismiss retires the notification with id as a user dismissal, emitting NotificationClosed(dismissed). It is a no-op (no signal) if no such notification is live.
func (*Daemon) OnClose ¶
func (d *Daemon) OnClose(id uint32, reason notifications.CloseReason)
OnClose removes the notification's surface. The reason is ignored here because the only path that reaches OnClose -- a CloseNotification call -- has the server emit NotificationClosed(closed) itself; expiry and dismissal go through Tick and Dismiss, which emit their own reasons. It implements notifications.Handler.
func (*Daemon) OnNotify ¶
func (d *Daemon) OnNotify(n *notifications.Notification) uint32
OnNotify renders n into a Toast and adds it to the stack (replacing an existing entry with the same id), then returns n.ID. If adding it would push the live count past Cap, the oldest notifications are retired to make room (each closed with reason expired). It implements notifications.Handler.
func (*Daemon) SetEmitter ¶
SetEmitter installs (or replaces) the Emitter the Daemon drives. It exists to break the construction cycle between a Daemon (which needs a server to emit through) and a server (which needs the Daemon as its Handler): build the Daemon with a nil Emitter, hand it to the server, then call SetEmitter with the server.
type Emitter ¶
type Emitter interface {
EmitClosed(id uint32, reason notifications.CloseReason) error
EmitActionInvoked(id uint32, key string) error
}
Emitter is the subset of the notification server the Daemon drives: emitting the two spec signals. github.com/go-freedesktop/notifications.Server satisfies it on Linux (and its non-Linux stub satisfies it too), so a Daemon stays platform-neutral and unit-testable with a fake Emitter.
type IconLookup ¶
IconLookup resolves an icon name or file path to raster pixels for a Toast icon. It returns the tightly packed RGBA buffer (w*h*4 bytes) with its dimensions, and ok == false when the name cannot be resolved (the Toast then renders without an icon). It is the seam a daemon plugs an icon-theme lookup (github.com/go-freedesktop/icontheme + notifications.LoadImagePath) into; a nil IconLookup resolves nothing.
Source Files