notify

README

go-notify

Package notify provides an implementation of the Gnome DBus Notifications Specification.

Examples

Display a simple notification.

ntf := notify.NewNotification("Test Notification", "Just a test")
if _, err := ntf.Show(); err != nil {
	return
}

Display a notification with an icon. Consult the Icon Naming Specification.

ntf := notify.NewNotification("Test Notification", "Just a test")
ntf.AppIcon = "network-wireless"
if _, err := ntf.Show(); err != nil {
	return
}

Display a notification that never expires.

ntf := notify.NewNotification("Test Notification", "Just a test")
ntf.Timeout = notify.ExpiresNever
if _, err := ntf.Show(); err != nil {
	return
}

Play a sound with the notification.

ntf := notify.NewNotification("Test Notification", "Just a test")
ntf.Hints = make(map[string]interface{})
ntf.Hints[notify.HintSoundFile] = "/home/my-username/sound.oga"
if _, err := ntf.Show(); err != nil {
	return
}

Documentation

Overview

Package notify provides an implementation of the Gnome DBus notifications specification.

Index

• Constants
• func CloseNotification(id uint32) (err error)
• func SignalNotify(ctx context.Context, ch chan<- Signal) error
• type Capabilities
  • func GetCapabilities() (c Capabilities, err error)
• type CloseReason
  • func (x CloseReason) String() string
• type Notification
  • func NewNotification(summary, body string) Notification
  • func (n Notification) Show() (id uint32, err error)
• type ServerInformation
  • func GetServerInformation() (i ServerInformation, err error)
• type Signal

Constants

const (
	DbusObjectPath               = "/org/freedesktop/Notifications"
	DbusInterfacePath            = "org.freedesktop.Notifications"
	SignalNotificationClosed     = "org.freedesktop.Notifications.NotificationClosed"
	SignalActionInvoked          = "org.freedesktop.Notifications.ActionInvoked"
	CallGetCapabilities          = "org.freedesktop.Notifications.GetCapabilities"
	CallCloseNotification        = "org.freedesktop.Notifications.CloseNotification"
	CallNotify                   = "org.freedesktop.Notifications.Notify"
	CallGetServerInformation     = "org.freedesktop.Notifications.GetServerInformation"
	DbusMemberActionInvoked      = "ActionInvoked"
	DbusMemberNotificationClosed = "NotificationClosed"
)

Notification object paths and interfaces.

const (
	ExpiresDefault = -1
	ExpiresNever   = 0
)

Notification expire timeout.

const (
	ClassDevice              = "device"
	ClassDeviceAdded         = "device.added"
	ClassDeviceError         = "device.error"
	ClassDeviceRemoved       = "device.removed"
	ClassEmail               = "email"
	ClassEmailArrived        = "email.arrived"
	ClassEmailBounced        = "email.bounced"
	ClassIm                  = "im"
	ClassImError             = "im.error"
	ClassImReceived          = "im.received"
	ClassNetwork             = "network"
	ClassNetworkConnected    = "network.connected"
	ClassNetworkDisconnected = "network.disconnected"
	ClassNetworkError        = "network.error"
	ClassPresence            = "presence"
	ClassPresenceOffline     = "presence.offline"
	ClassPresenceOnline      = "presence.online"
	ClassTransfer            = "transfer"
	ClassTransferComplete    = "transfer.complete"
	ClassTransferError       = "transfer.error"
)

Notification Categories

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

Urgency Levels

const (
	HintActionIcons   = "action-icons"
	HintCategory      = "category"
	HintDesktopEntry  = "desktop-entry"
	HintImageData     = "image-data"
	HintImagePath     = "image-path"
	HintResident      = "resident"
	HintSoundFile     = "sound-file"
	HintSoundName     = "sound-name"
	HintSuppressSound = "suppress-sound"
	HintTransient     = "transient"
	HintX             = "x"
	HintY             = "y"
	HintUrgency       = "urgency"
)

Hints

Functions

func CloseNotification

func CloseNotification(id uint32) (err error)

CloseNotification closes the notification if it exists using its id.

func SignalNotify

func SignalNotify(ctx context.Context, ch chan<- Signal) error

SignalNotify sends notification signals to the channel, such as close or action. Note that you can receive other signals, check the ID. Does not return until the context is done. Do not close the channel until after this function returns.

Types

type Capabilities

type Capabilities struct {
	// Supports using icons instead of text for displaying actions.
	ActionIcons bool

	// The server will provide any specified actions to the user.
	Actions bool

	// Supports body text. Some implementations may only show the summary.
	Body bool

	// The server supports hyperlinks in the notifications.
	BodyHyperlinks bool

	// The server supports images in the notifications.
	BodyImages bool

	// Supports markup in the body text.
	BodyMarkup bool

	// The server will render an animation of all the frames in a given
	// image array.
	IconMulti bool

	// Supports display of exactly 1 frame of any given image array.
	IconStatic bool

	// The server supports persistence of notifications. Notifications will
	// be retained until they are acknowledged or removed by the user or
	// recalled by the sender.
	Persistence bool

	// The server supports sounds on notifications.
	Sound bool
}

Capabilities is a struct containing the capabilities of the notification server.

func GetCapabilities

func GetCapabilities() (c Capabilities, err error)

GetCapabilities returns the capabilities of the notification server.

type CloseReason

type CloseReason uint32

CloseReason is the reason why the notification was closed.

const (
	NotClosed                CloseReason = 0
	CloseReasonExpired       CloseReason = 1
	CloseReasonUserDismissed CloseReason = 2
	CloseReasonCloseCalled   CloseReason = 3
	CloseReasonUndefined     CloseReason = 4
)

https://developer.gnome.org/notification-spec/#signals

func (CloseReason) String

func (x CloseReason) String() string

type Notification

type Notification struct {
	// The optional name of the application sending the notification.
	// Can be blank.
	AppName string

	// The optional notification ID that this notification replaces.
	ReplacesID uint32

	// The optional program icon of the calling application.
	AppIcon string

	// The summary text briefly describing the notification.
	Summary string

	// The optional detailed body text.
	Body string

	// The actions send a request message back to the notification client
	// when invoked.
	Actions []string

	// Hints are a way to provide extra data to a notification server.
	Hints map[string]interface{}

	// The timeout time in milliseconds since the display of the
	// notification at which the notification should automatically close.
	Timeout int32
}

Notification is a struct which describes the notification to be displayed by the notification server.

func NewNotification

func NewNotification(summary, body string) Notification

NewNotification creates a new notification object with some basic information.

func (Notification) Show

func (n Notification) Show() (id uint32, err error)

Show sends the information in the notification object to the server to be displayed.

type ServerInformation

type ServerInformation struct {
	// The name of the notification server daemon
	Name string

	// The vendor of the notification server
	Vendor string

	// Version of the notification server
	Version string

	// Spec version the notification server conforms to
	SpecVersion string
}

ServerInformation is a struct containing information about the server such as its name and version.

func GetServerInformation

func GetServerInformation() (i ServerInformation, err error)

GetServerInformation returns information about the notification server such as its name and version.

type Signal

type Signal struct {
	Name        string
	ID          uint32
	ActionKey   string
	CloseReason CloseReason
}