notify

package module
v0.13.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 9, 2024 License: BSD-3-Clause Imports: 7 Imported by: 46

README

notify

go.dev reference Go Report Card Build

Notify is a go library for interacting with the dbus notification service defined by freedesktop.org: https://developer.gnome.org/notification-spec/

notify can deliver desktop notifications over dbus, ala how libnotify does it.

Please note notify is still in motion and APIs are not locked until a 1.0 is released.

More testers are very welcome =)

Depends on:

Changelog

  • v0.11.2: Introduce helpers ExpireTimeoutSetByNotificationServer, ExpireTimeoutNever
  • v0.11.1: Fix a race during Close() #11
  • v0.11.0: re-release under BSD license
  • v0.10.0: stricter types: some breaking changes
  • v0.9.0: some breaking changes
  • v0.2.1: dbus: gomod: lock to dbus v5
  • v0.2.0: Notifier.Close() no longer calls .Close() on the underlying dbus.Conn

Quick intro

See example: main.go.

Clone repo and go to examples folder:

go run main.go

TODO

  • Add callback support aka dbus signals.
  • Tests. I am very interested in any ideas for writing some (useful) tests for this.

See also

The Gnome notification spec https://developer.gnome.org/notification-spec/.

Contributors

Thanks to user emersion for great ideas on receiving signals.

Thanks to Merovius for fixing race during Close().

License

BSD 3-Clause

Documentation

Overview

Package notify is a wrapper around godbus for dbus notification interface See: https://developer.gnome.org/notification-spec/ and https://github.com/godbus/dbus

The package provides exported methods for simple usage, e.g. just show a notification. It also provides the interface Notifier that includes signal delivery for notifications on the system.

Each notification created is allocated a unique ID by the server (see Notification). This ID is unique within the dbus session, and is an increasing number. While the notification server is running, the ID will not be recycled unless the capacity of a uint32 is exceeded.

The ID can be used to hide the notification before the expiration timeout is reached (see CloseNotification).

The ID can also be used to atomically replace the notification with another (Notification.ReplaceID). This allows you to (for instance) modify the contents of a notification while it's on-screen.

Index

Constants

View Source 
const ExpireTimeoutNever time.Duration = 0
View Source 
const ExpireTimeoutSetByNotificationServer = time.Millisecond * -1

ExpireTimeoutSetByNotificationServer used as ExpireTimeout to leave expiration up to the notification server. Expiration is sent as number of millis. When -1, the notification's expiration time is dependent on the notification server's settings, and may vary for the type of notification. If 0, never expire.

Variables

This section is empty.

Functions

func GetCapabilities 

func GetCapabilities(conn *dbus.Conn) ([]string, error)

GetCapabilities gets the capabilities of the notification server. This call takes no parameters. It returns an array of strings. Each string describes an optional capability implemented by the server.

See also: https://developer.gnome.org/notification-spec/ GetCapabilities provide an exported method for this operation

func SendNotification 

func SendNotification(conn *dbus.Conn, note Notification) (uint32, error)

SendNotification is provided for convenience. Use if you only want to deliver a notification and do not care about actions or events.

func WithLogger added in v0.9.0 

func WithLogger(logz logger) option

WithLogger sets a new logger func

func WithOnAction added in v0.9.0 

func WithOnAction(h ActionInvokedHandler) option

WithOnAction sets ActionInvokedHandler handler

func WithOnClosed added in v0.9.0 

func WithOnClosed(h NotificationClosedHandler) option

WithOnClosed sets NotificationClosed handler

Types

type Action added in v0.11.0 

type Action struct {
	// Key is the identifier for the action, used for signaling back which action was selected
	Key string
	// Label is the localized string that will be displayed to the user
	Label string
}

Action holds key and label for user action buttons.

func NewDefaultAction added in v0.13.3 

func NewDefaultAction(label string) Action

NewDefaultAction creates a new default action. The default action is usually invoked by clicking on the notification. The label can be anything, but implementations are free whether to display it.

type ActionInvokedHandler added in v0.9.0 

type ActionInvokedHandler func(*ActionInvokedSignal)

ActionInvokedHandler is called when we receive a signal that one of the action_keys was invoked.

Note that invoking an action often also produces a NotificationClosedSignal, so you might receive both a Closed signal and a ActionInvoked signal.

I suspect this detail is implementation specific for the UI interaction, and does at least happen on XFCE4.

type ActionInvokedSignal 

type ActionInvokedSignal struct {
	// ID of the Notification the action was invoked for
	ID uint32
	// Key from the tuple (action_key, label)
	ActionKey string
}

ActionInvokedSignal holds data from any signal received regarding Actions invoked

type Hint added in v0.12.0 

type Hint struct {
	ID      string
	Variant dbus.Variant
}

See: https://specifications.freedesktop.org/notification-spec/latest/ar01s08.html

func HintImageDataRGBA added in v0.13.0 

func HintImageDataRGBA(img *image.RGBA) Hint

func HintImageFilePath added in v0.13.0 

func HintImageFilePath(imageAbsolutePath string) Hint

HintImageFilePath sends a filepath to the notification server as the file of the icon. See also: https://specifications.freedesktop.org/notification-spec/latest/ar01s05.html

func HintSoundWithName added in v0.12.0 

func HintSoundWithName(soundName string) Hint

func HintUrgency added in v0.12.0 

func HintUrgency(urgency Urgency) Hint

type Notification 

type Notification struct {
	AppName string
	// Setting ReplacesID atomically replaces the notification with this ID.
	// Optional.
	ReplacesID uint32
	// See predefined icons here: http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html
	// Optional.
	AppIcon string
	Summary string
	Body    string
	// Actions are tuples of (action_key, label), e.g.: []Action{"cancel", "Cancel", "open", "Open"}
	Actions []Action
	Hints   map[string]dbus.Variant
	// ExpireTimeout: duration to show notification. See also ExpireTimeoutSetByNotificationServer and ExpireTimeoutNever.
	ExpireTimeout time.Duration
}

Notification holds all information needed for creating a notification

func (*Notification) AddHint added in v0.12.0 

func (n *Notification) AddHint(hint Hint)

func (*Notification) SetUrgency added in v0.12.0 

func (n *Notification) SetUrgency(urgency Urgency)

type NotificationClosedHandler added in v0.9.0 

type NotificationClosedHandler func(*NotificationClosedSignal)

NotificationClosedHandler is called when we receive a NotificationClosed signal

type NotificationClosedSignal 

type NotificationClosedSignal struct {
	// ID of the Notification the signal was invoked for
	ID uint32
	// A reason given if known
	Reason Reason
}

NotificationClosedSignal holds data for *Closed callbacks from Notifications Interface.

type Notifier 

type Notifier interface {
	SendNotification(n Notification) (uint32, error)
	GetCapabilities() ([]string, error)
	GetServerInformation() (ServerInformation, error)
	CloseNotification(id uint32) (bool, error)
	Close() error
}

Notifier is an interface implementing the operations supported by the Freedesktop DBus Notifications object.

New() sets up a Notifier that listens on dbus' signals regarding Notifications: NotificationClosed and ActionInvoked.

Signal delivery works by subscribing to all signals regarding Notifications, which means you will see signals for Notifications also from other sources, not just the latest you sent

Users that only want to send a simple notification, but don't care about interacting with signals, can use exported method: SendNotification(conn, Notification)

Caller is responsible for calling Close() before exiting, to shut down event loop and cleanup dbus registration.

func New 

func New(conn *dbus.Conn, opts ...option) (Notifier, error)

New creates a new Notifier using conn. See also: Notifier

type Reason 

type Reason uint32

Reason for the closed notification 

const (
	// ReasonExpired when a notification expired
	ReasonExpired Reason = 1

	// ReasonDismissedByUser when a notification has been dismissed by a user
	ReasonDismissedByUser Reason = 2

	// ReasonClosedByCall when a notification has been closed by a call to CloseNotification
	ReasonClosedByCall Reason = 3

	// ReasonUnknown when as notification has been closed for an unknown reason
	ReasonUnknown Reason = 4
)

func (Reason) String 

func (r Reason) String() string

type ServerInformation 

type ServerInformation struct {
	Name        string
	Vendor      string
	Version     string
	SpecVersion string
}

ServerInformation is a holder for information returned by GetServerInformation call.

func GetServerInformation 

func GetServerInformation(conn *dbus.Conn) (ServerInformation, error)

GetServerInformation returns the information on the server.

org.freedesktop.Notifications.GetServerInformation 

 GetServerInformation Return Values

		Name		 Type	  Description
		name		 STRING	  The product name of the server.
		vendor		 STRING	  The vendor name. For example, "KDE," "GNOME," "freedesktop.org," or "Microsoft."
		version		 STRING	  The server's version number.
		spec_version STRING	  The specification version the server is compliant with.

type Urgency added in v0.12.0 

type Urgency byte
const (
	UrgencyLow      Urgency = 0
	UrgencyNormal   Urgency = 1
	UrgencyCritical Urgency = 2
)

type Variant deprecated added in v0.12.0 

type Variant = Hint

Deprecated: use Hint

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.