shout

README

shout

A library for sending notifications via the D-BUS XDG Notification APIs.

Goals

This library should examine the available notification APIs and choose the most expressive API available. If the application is confined such that only the XDG Desktop Portals API is available, that API should be used automatically.

Current State

The library uses the XDG Desktop Portals API when confined within a flatpak, and the org.freedesktop.Notifications API when not confined. Ideally we'd use the portal API outside of the sandbox too (it's more powerful), but right now we can't actually do that reliably.

Example

The ./example/ directory contains a small, self-contained application that can build itself for flatpak.

Prerequisites:

• Go 1.23
• flatpak-builder
• flatpak

Just invoke the makefile with:

pushd example; make; popd

The application will send a few different kinds of notification for you to interact with.

Why is it a flatpak? Shouldn't the portal API be available without that? You would think. Some desktops need applications to run within a flatpak in order to determine their AppID, which is necessary for some D-BUS activiation features. Notifications through this API can be silently dropped when not issued from within a flatpak.

Documentation

Overview

Package shout implements rich desktop notifications atop the XDG Desktop Portal notification API and the org.freedesktop.Notifications API.

This package only does anything on Linux.

Index

• type Button
• type Notification
• type Notifier
  • func NewNotifier(conn *dbus.Conn, appName, appIcon string, ...) (Notifier, error)
• type Priority
  • func (p Priority) String() string

Types

type Button

type Button struct {
	// Name of an exported action to take when pressing this button.
	Action string
	// Target data to send to the exported application when pressing this button.
	Target string
	// Label to display for the user atop the button.
	Label string
}

type Notification

type Notification struct {
	// Title is the short, emphasized text of a notification.
	Title string
	// Body is the long-form text content of a notification.
	Body string
	// ReplaceID is the optional ID of a notification that should be updated/replaced
	// with the contents of this notification. Leave empty if not applicable.
	// Some platforms may not support replacement.
	ReplaceID string
	// Markup indicates whether the text in Body contains HTML-like
	// formatting.
	Markup bool
	// IconPath to an icon to display alongside the notification. Must be either a path
	// containing at least one path separator element (/) or a comma-delimited list of
	// icon names in a freedesktop.org-compliant icon theme. Names will be tried in order.
	// IconPath may point to a JPEG, PNG, or SVG image.
	// IconPath takes precedence over Icon.
	IconPath string
	// Icon image for the notification. IconPath takes precedence over Icon.
	// NOTE: Icon image data frequently gets passed over the bus, which is slow and expensive.
	// Using a path to an image is much more efficient.
	Icon image.Image
	// Priority of the notification.
	Priority Priority
	// DefaultAction is the name of a default action exported by the application
	// that is invoked when the notification is clicked. Executing an exported
	// action is not supported on some platforms, in which case DefaultAction will
	// revert to the string "default".
	DefaultAction string
	// User-facing label for the default action, if any.
	DefaultActionLabel string
	// DefaultActionTarget is application data to send along when the default
	// action is activated.
	DefaultActionTarget dbus.Variant
	// Buttons to present to the user, if any.
	Buttons []Button
	// How long to show the notification for; zero means indefinitely.
	// Some platforms may not support expiry.
	ExpirationTimeout time.Duration
}

Notification describes the contents of the notification to be displayed. Depending on the underlying API in use, some options may not be supported.

type Notifier

type Notifier interface {
	Send(id string, not Notification) error
	Remove(id string) error
}

Notifier can send and remove notifications from the desktop.

func NewNotifier

func NewNotifier(conn *dbus.Conn, appName, appIcon string, actionInvokedHandler func(notificationID, action string, platformData map[string]dbus.Variant, target, response dbus.Variant, err error)) (Notifier, error)

NewNotifier builds a notifier atop the provided bus connection. If a actionInvokedHandler is provided, it will be invoked with each org.freedesktop.portal.Notification.ActionInvoked signal received over the bus connection. Note that each invocation to actionInvokedHandler is blocking, so long-running implementations may delay subsequent signal delivery. The actionInvokedHandler may be invoked asynchronously at any time until the provided bus connection is closed.

type Priority

type Priority uint8

const (
	Low Priority = iota
	Normal
	High
	Urgent
)

func (Priority) String

func (p Priority) String() string