DBus.Notify

fdo-notify-0.3.1: Desktop Notifications client

Safe Haskell | None
Language | Haskell98

DBus.Notify

Contents

- Usage
- Displaying notifications
- Constructing notifications
- Capabilities

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

- notify :: Client -> Note -> IO Notification
- replace :: Client -> Notification -> Note -> IO Notification
- data Notification
- mkSessionClient :: IO Client
- connectSession :: IO Client
- data Client :: *
- blankNote :: Note
- data Note = Note {
  - appName :: String
  - appImage :: Maybe Icon
  - summary :: String
  - body :: Maybe Body
  - actions :: [(Action, String)]
  - hints :: [Hint]
  - expiry :: Timeout
  }
- data Body
  - = Text String
  - | Bold Body
  - | Italic Body
  - | Underline Body
  - | Hyperlink URL Body
  - | Img URL String
  - | Concat Body Body
- type URL = String
- data Timeout
  - = Never
  - | Dependent
  - | Milliseconds Int32
- newtype Action = Action {
  - actionName :: String
  }
- data Image
- data Icon
  - = File FilePath
  - | Icon String
- data Category
  - = Device
  - | DeviceAdded
  - | DeviceError
  - | DeviceRemoved
  - | Email
  - | EmailArrived
  - | EmailBounced
  - | Im
  - | ImError
  - | ImReceived
  - | Network
  - | NetworkConnected
  - | NetworkDisconnected
  - | NetworkError
  - | Presence
  - | PresenceOffline
  - | PresenceOnline
  - | Transfer
  - | TransferComplete
  - | TransferError
- data UrgencyLevel
  - = Low
  - | Normal
  - | Critical
- data Hint
  - = Urgency UrgencyLevel
  - | Category Category
  - | ImageData Image
  - | ImagePath Icon
  - | SoundFile FilePath
  - | SuppressSound Bool
  - | X Int32
  - | Y Int32
- getCapabilities :: Client -> IO [Capability]
- data Capability
  - = ActionsCap
  - | BodyCap
  - | BodyHyperlinksCap
  - | BodyImagesCap
  - | BodyMarkupCap
  - | IconMultiCap
  - | IconStaticCap
  - | SoundCap
  - | UnknownCap String

# 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 `sessionConnect` 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 <- sessionConnect
             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 #

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

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

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

data Notification #

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

mkSessionClient :: IO Client #

Deprecated: Use DBus.Client.connectSession

connectSession :: IO Client #

Connect to the bus specified in the environment variable `DBUS_SESSION_BUS_ADDRESS`, which must be set.

Throws a `ClientError` if `DBUS_SESSION_BUS_ADDRESS` is unset, contains an invalid address, or if connecting to the bus failed.

data Client :: * #

An active client session to a message bus. Clients may send or receive method calls, and listen for or emit signals.

# Constructing notifications

blankNote :: Note #

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

data Note #

Contents of a notification

Constructors

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

Instances

Eq Note # |
Methods (==) :: Note -> Note -> Bool # (/=) :: Note -> Note -> Bool #
Show Note # |
Methods showsPrec :: Int -> Note -> ShowS # show :: Note -> String # showList :: [Note] -> ShowS #

data Body #

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 # |
Methods (==) :: Body -> Body -> Bool # (/=) :: Body -> Body -> Bool #
Show Body # |
Methods showsPrec :: Int -> Body -> ShowS # show :: Body -> String # showList :: [Body] -> ShowS #

type URL = String #

data Timeout #

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 # |
Methods (==) :: Timeout -> Timeout -> Bool # (/=) :: Timeout -> Timeout -> Bool #
Show Timeout # |
Methods showsPrec :: Int -> Timeout -> ShowS # show :: Timeout -> String # showList :: [Timeout] -> ShowS #

newtype Action #

Constructors

Action |
Fields actionName :: String

Instances

Eq Action # |
Methods (==) :: Action -> Action -> Bool # (/=) :: Action -> Action -> Bool #
Show Action # |
Methods showsPrec :: Int -> Action -> ShowS # show :: Action -> String # showList :: [Action] -> ShowS #

data Image #

Images are not yet supported

Instances

Eq Image # |
Methods (==) :: Image -> Image -> Bool # (/=) :: Image -> Image -> Bool #
Show Image # |
Methods showsPrec :: Int -> Image -> ShowS # show :: Image -> String # showList :: [Image] -> ShowS #

data Icon #

An Icon is either a path to an image, or a name in an icon theme

Constructors

File FilePath |
Icon String |

Instances

Eq Icon # |
Methods (==) :: Icon -> Icon -> Bool # (/=) :: Icon -> Icon -> Bool #
Show Icon # |
Methods showsPrec :: Int -> Icon -> ShowS # show :: Icon -> String # showList :: [Icon] -> ShowS #

data Category #

Categorisation of (some) notifications

Constructors

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

Instances

Eq Category # |
Methods (==) :: Category -> Category -> Bool # (/=) :: Category -> Category -> Bool #
Show Category # |
Methods showsPrec :: Int -> Category -> ShowS # show :: Category -> String # showList :: [Category] -> ShowS #

data UrgencyLevel #

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

Constructors

Low |
Normal |
Critical | Critical notifications require user attention

Instances

Enum UrgencyLevel # |
Methods succ :: UrgencyLevel -> UrgencyLevel # pred :: UrgencyLevel -> UrgencyLevel # toEnum :: Int -> UrgencyLevel # fromEnum :: UrgencyLevel -> Int # enumFrom :: UrgencyLevel -> [UrgencyLevel] # enumFromThen :: UrgencyLevel -> UrgencyLevel -> [UrgencyLevel] # enumFromTo :: UrgencyLevel -> UrgencyLevel -> [UrgencyLevel] # enumFromThenTo :: UrgencyLevel -> UrgencyLevel -> UrgencyLevel -> [UrgencyLevel] #
Eq UrgencyLevel # |
Methods (==) :: UrgencyLevel -> UrgencyLevel -> Bool # (/=) :: UrgencyLevel -> UrgencyLevel -> Bool #
Ord UrgencyLevel # |
Methods compare :: UrgencyLevel -> UrgencyLevel -> Ordering # (<) :: UrgencyLevel -> UrgencyLevel -> Bool # (<=) :: UrgencyLevel -> UrgencyLevel -> Bool # (>) :: UrgencyLevel -> UrgencyLevel -> Bool # (>=) :: UrgencyLevel -> UrgencyLevel -> Bool # max :: UrgencyLevel -> UrgencyLevel -> UrgencyLevel # min :: UrgencyLevel -> UrgencyLevel -> UrgencyLevel #
Show UrgencyLevel # |
Methods showsPrec :: Int -> UrgencyLevel -> ShowS # show :: UrgencyLevel -> String # showList :: [UrgencyLevel] -> ShowS #

data Hint #

Various hints about how the notification should be displayed

Constructors

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

Instances

Eq Hint # |
Methods (==) :: Hint -> Hint -> Bool # (/=) :: Hint -> Hint -> Bool #
Show Hint # |
Methods showsPrec :: Int -> Hint -> ShowS # show :: Hint -> String # showList :: [Hint] -> ShowS #

# Capabilities

getCapabilities :: Client -> IO [Capability] #

Determine the server's capabilities

data Capability #

Constructors

ActionsCap |
BodyCap |
BodyHyperlinksCap |
BodyImagesCap |
BodyMarkupCap |
IconMultiCap |
IconStaticCap |
SoundCap |
UnknownCap String |

Instances

Eq Capability # |
Methods (==) :: Capability -> Capability -> Bool # (/=) :: Capability -> Capability -> Bool #
Read Capability # |
Methods readsPrec :: Int -> ReadS Capability # readList :: ReadS [Capability] # readPrec :: ReadPrec Capability # readListPrec :: ReadPrec [Capability] #
Show Capability # |
Methods showsPrec :: Int -> Capability -> ShowS # show :: Capability -> String # showList :: [Capability] -> ShowS #