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
- func GetCapabilities(conn *dbus.Conn) ([]string, error)
- func SendNotification(conn *dbus.Conn, note Notification) (uint32, error)
- func WithLogger(logz logger) option
- func WithOnAction(h ActionInvokedHandler) option
- func WithOnClosed(h NotificationClosedHandler) option
- type Action
- type ActionInvokedHandler
- type ActionInvokedSignal
- type Hint
- type Notification
- type NotificationClosedHandler
- type NotificationClosedSignal
- type Notifier
- type Reason
- type ServerInformation
- type Urgency
- type Variantdeprecated
Constants ¶
const ExpireTimeoutNever time.Duration = 0
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 ¶
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
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 HintImageFilePath ¶ added in v0.13.0
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 HintUrgency ¶ added in v0.12.0
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.
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 )
type ServerInformation ¶
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.