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.

#### Instances

Instances details

IsValue a => AutoMethod (DBusR (Either Reply a)) |
Instance details Defined in DBus.Client Methods funTypes :: DBusR (Either Reply a) -> ([Type], [Type]) apply :: DBusR (Either Reply a) -> [Variant] -> DBusR Reply
IsValue a => AutoMethod (DBusR a) |
Instance details Defined in DBus.Client Methods funTypes :: DBusR a -> ([Type], [Type]) apply :: DBusR a -> [Variant] -> DBusR Reply

# 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

Instances details

Show Note # |
Instance details Defined in DBus.Notify Methods showsPrec :: Int -> Note -> ShowS # show :: Note -> String # showList :: [Note] -> ShowS #
Eq Note # |
Instance details Defined in DBus.Notify Methods (==) :: Note -> Note -> Bool # (/=) :: Note -> Note -> Bool #

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

Instances details

Show Body # |
Instance details Defined in DBus.Notify Methods showsPrec :: Int -> Body -> ShowS # show :: Body -> String # showList :: [Body] -> ShowS #
Eq Body # |
Instance details Defined in DBus.Notify Methods (==) :: Body -> Body -> Bool # (/=) :: Body -> Body -> Bool #

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

Instances details

Show Timeout # |
Instance details Defined in DBus.Notify Methods showsPrec :: Int -> Timeout -> ShowS # show :: Timeout -> String # showList :: [Timeout] -> ShowS #
Eq Timeout # |
Instance details Defined in DBus.Notify Methods (==) :: Timeout -> Timeout -> Bool # (/=) :: Timeout -> Timeout -> Bool #

newtype Action #

Constructors

Action |
Fields actionName :: String

#### Instances

Instances details

Show Action # |
Instance details Defined in DBus.Notify Methods showsPrec :: Int -> Action -> ShowS # show :: Action -> String # showList :: [Action] -> ShowS #
Eq Action # |
Instance details Defined in DBus.Notify Methods (==) :: Action -> Action -> Bool # (/=) :: Action -> Action -> Bool #

data Image #

Images are not yet supported

#### Instances

Instances details

Show Image # |
Instance details Defined in DBus.Notify Methods showsPrec :: Int -> Image -> ShowS # show :: Image -> String # showList :: [Image] -> ShowS #
Eq Image # |
Instance details Defined in DBus.Notify Methods (==) :: Image -> Image -> Bool # (/=) :: Image -> Image -> Bool #

data Icon #

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

Constructors

File FilePath |
Icon String |

#### Instances

Instances details

Show Icon # |
Instance details Defined in DBus.Notify Methods showsPrec :: Int -> Icon -> ShowS # show :: Icon -> String # showList :: [Icon] -> ShowS #
Eq Icon # |
Instance details Defined in DBus.Notify Methods (==) :: Icon -> Icon -> Bool # (/=) :: Icon -> Icon -> Bool #

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

Instances details

Show Category # |
Instance details Defined in DBus.Notify Methods showsPrec :: Int -> Category -> ShowS # show :: Category -> String # showList :: [Category] -> ShowS #
Eq Category # |
Instance details Defined in DBus.Notify Methods (==) :: Category -> Category -> Bool # (/=) :: Category -> Category -> Bool #

data UrgencyLevel #

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

Constructors

Low |
Normal |
Critical | Critical notifications require user attention

#### Instances

Instances details

Enum UrgencyLevel # |
Instance details Defined in DBus.Notify 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] #
Show UrgencyLevel # |
Instance details Defined in DBus.Notify Methods showsPrec :: Int -> UrgencyLevel -> ShowS # show :: UrgencyLevel -> String # showList :: [UrgencyLevel] -> ShowS #
Eq UrgencyLevel # |
Instance details Defined in DBus.Notify Methods (==) :: UrgencyLevel -> UrgencyLevel -> Bool # (/=) :: UrgencyLevel -> UrgencyLevel -> Bool #
Ord UrgencyLevel # |
Instance details Defined in DBus.Notify 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 #

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

Instances details

Show Hint # |
Instance details Defined in DBus.Notify Methods showsPrec :: Int -> Hint -> ShowS # show :: Hint -> String # showList :: [Hint] -> ShowS #
Eq Hint # |
Instance details Defined in DBus.Notify Methods (==) :: Hint -> Hint -> Bool # (/=) :: Hint -> Hint -> Bool #

# Capabilities

getCapabilities :: Client -> IO [Capability] #

Determine the server's capabilities

data Capability #

Constructors

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

#### Instances

Instances details

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