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

Deprecated: Use DBus.Client.connectSession

connectSession :: IO Client Source #

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 Source #

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 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 Icon
- summary :: String
- body :: Maybe Body
- actions :: [(Action, String)]
- hints :: [Hint]
- expiry :: Timeout

#### Instances

Instances details

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

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

Instances details

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

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

Instances details

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

newtype Action Source #

Constructors

Action |

Fields

- actionName :: String

#### Instances

Instances details

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

data Image Source #

Images are not yet supported

#### Instances

Instances details

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

data Icon Source #

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

data Category Source #

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

data UrgencyLevel Source #

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

Constructors

Low |
Normal |
Critical | Critical notifications require user attention

#### Instances

Instances details

Enum UrgencyLevel Source # |

Instance details

Defined in DBus.Notify

Methods

succ :: UrgencyLevel -> UrgencyLevel Source #

pred :: UrgencyLevel -> UrgencyLevel Source #

toEnum :: Int -> UrgencyLevel Source #

fromEnum :: UrgencyLevel -> Int Source #

enumFrom :: UrgencyLevel -> [UrgencyLevel] Source #

enumFromThen :: UrgencyLevel -> UrgencyLevel -> [UrgencyLevel] Source #

enumFromTo :: UrgencyLevel -> UrgencyLevel -> [UrgencyLevel] Source #

enumFromThenTo :: UrgencyLevel -> UrgencyLevel -> UrgencyLevel -> [UrgencyLevel] Source #

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

Instance details

Defined in DBus.Notify

Methods

compare :: UrgencyLevel -> UrgencyLevel -> Ordering Source #

(<) :: UrgencyLevel -> UrgencyLevel -> Bool Source #

(<=) :: UrgencyLevel -> UrgencyLevel -> Bool Source #

(>) :: UrgencyLevel -> UrgencyLevel -> Bool Source #

(>=) :: UrgencyLevel -> UrgencyLevel -> Bool Source #

max :: UrgencyLevel -> UrgencyLevel -> UrgencyLevel Source #

min :: UrgencyLevel -> UrgencyLevel -> UrgencyLevel Source #

data Hint Source #

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

# 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

Instances details

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