DBus.Notify

Contents

Description

A library for issuing notifications using FreeDesktop.org Desktop Notifications protocol. This protocol is used to communicate with services such as Ubuntu's NotifyOSD.

This library does not yet support receiving events relating to notifications, or images in notifications: if you need that functionality please contact the maintainer.

Synopsis

Usage

A DBUS Client is needed to display notifications, so the first step is to create one. The notification service will usually run on the session bus (the DBUS instance responsible for messages within a desktop session) so you can use mkSessionClient to create the client.

To display a notification, first construct a Note. This can be done in pure code. Notifications can have actions, categories, etc. associated to them but we will just show a simple example (these features are not supported by all notification services anyway).

Use the function notify to display a Note. This returns a handle which can be passed to replace to replace a notification.

import DBus.Notify

main = do
         client <- mkSessionClient
         let startNote = appNote { summary="Starting"
                                 , body=(Just $ Text "Calculating fib(33).") }
         notification <- notify client startNote
         let endNote = appNote { summary="Finished"
                               , body=(Just . Text . show $ fib33) }
         fib33 `seq` replace client notification endNote
     where
         appNote = blankNote { appName="Fibonacci Demonstration" }
         fib 0 = 0
         fib 1 = 1
         fib n = fib (n-1) + fib (n-2)
         fib33 = fib 33

Displaying notifications

notify :: Client -> Note -> IO Notification Source

Display a notification. Return a handle which can be used to replace the notification.

replace :: Client -> Notification -> Note -> IO Notification Source

Replace an existing notification. If the notification has already been closed, a new one will be created.

data Notification Source

A handle on a displayed notification The notification may not have reached the screen yet, and may already have been closed.

mkSessionClient :: IO Client Source

Create a Client connected to the session bus. Note that this opens a socket and spawns a thread, so it's best to reuse a single client.

data Client

Clients are opaque handles to an open connection and other internal state.

Constructing notifications

blankNote :: Note Source

A Note with default values. All fields are blank except for expiry, which is Dependent.

data Note Source

Contents of a notification

Constructors

Note
Fields appName :: String appImage :: Maybe Image summary :: String body :: Maybe Body actions :: [(Action, String)] hints :: [Hint] expiry :: Timeout

Instances

Eq Note
Show Note

data Body Source

Message bodies may contain simple markup. NotifyOSD doesn't support any markup.

Constructors

Text String
Bold Body
Italic Body
Underline Body
Hyperlink URL Body
Img URL String
Concat Body Body

Instances

Eq Body
Show Body

type URL = String Source

data Timeout Source

Length of time to display notifications. NotifyOSD seems to ignore these.

Constructors

Never	Wait to be dismissed by user
Dependent	Let the notification service decide
Milliseconds Int32	Show notification for a fixed duration (must be positive)

Instances

Eq Timeout
Show Timeout

newtype Action Source

Constructors

Action
Fields actionName :: String

Instances

Eq Action
Show Action

data Image Source

Images are not yet supported

Instances

Eq Image
Show Image

data Category Source

Categorisation of (some) notifications

Instances

Eq Category
Show Category

data UrgencyLevel Source

Urgency of the notification. Notifications may be prioritised by urgency.

Constructors

Low
Normal
Critical	Critical notifications require user attention

Instances

Enum UrgencyLevel
Eq UrgencyLevel
Ord UrgencyLevel
Show UrgencyLevel

data Hint Source

Various hints about how the notification should be displayed

Constructors

Urgency UrgencyLevel
Category Category
ImageData Image
SoundFile FilePath
SuppressSound Bool
X Int32
Y Int32

Instances

Eq Hint
Show Hint

Capabilities

getCapabilities :: Client -> IO [Capability]Source

Determine the server's capabilities

data Capability Source

Constructors

ActionsCap
BodyCap
BodyHyperlinksCap
BodyImagesCap
BodyMarkupCap
IconMultiCap
IconStaticCap
SoundCap
UnknownCap String

Instances

Eq Capability
Read Capability
Show Capability

Device
DeviceAdded
DeviceError
DeviceRemoved
Email
EmailArrived
EmailBounced
Im
ImError
ImReceived
Network
NetworkConnected
NetworkDisconnected
NetworkError
Presence
PresenceOffline
PresenceOnline
Transfer
TransferComplete
TransferError