diff options
author | Mike Hearn <mike@navi.cx> | 2004-06-30 13:01:57 +0000 |
---|---|---|
committer | Mike Hearn <mike@navi.cx> | 2004-06-30 13:01:57 +0000 |
commit | 6d4976e1d1e2b543d784164d680090a3d9943dd7 (patch) | |
tree | a782e4e17de8c129ecc619be76fb9963e905bd0c /SPECIFICATION | |
parent | f4bab237353d270dbb8a8db6b477d70378729a02 (diff) | |
download | libnotify-6d4976e1d1e2b543d784164d680090a3d9943dd7.tar.gz |
Initial version
Diffstat (limited to 'SPECIFICATION')
-rw-r--r-- | SPECIFICATION | 117 |
1 files changed, 117 insertions, 0 deletions
diff --git a/SPECIFICATION b/SPECIFICATION new file mode 100644 index 0000000..7d497c9 --- /dev/null +++ b/SPECIFICATION @@ -0,0 +1,117 @@ +FreeDesktop proposed notifications spec +======================================= + +(c) 2004 Mike Hearn <mike@navi.cx> + 2004 Christian Hammond <chipx86@chipx86.com> + +ChangeLog: + +v0.1: + * Initial version + +--------------------------------------------------------------------- + +OVERVIEW + +This is a draft standard for a desktop notifications service, through +which applications can generate passive popups (sometimes known as +"poptarts") to notify the user in an asynchronous manner of events. + +This specification explicitly does not include other types of +notification presentation such as modal message boxes, window manager +decorations or window list annotations. + +Example use cases include: + +* Presence changes in IM programs: for instance, MSN Messenger on + Windows pioneered the use of passive popups to indicate presence + changes. + +* New mail notification + +* Low disk space/battery warnings + + + +BASIC DESIGN + +In order to ensure that multiple notifications can easily be +displayed at once, and to provide a convenient implementation, all +notifications are controlled by a single session-scoped service which +exposes a DBUS interface. + +On startup, a conforming implementation should take the +"org.freedesktop.Notifications" service on the session bus. This +service will be referred to as the "notification server" or just "the +server" in this document. It can optionally be activated automatically +by the bus process, however this is not required and notification +server clients must not assume that it is available. + +The server should implement the "org.freedesktop.Notifications" interface on +an object with the path "/org/freedesktop/Notifications". This is the +only interface required by this version of the specification. + +A notification has the following components: + +- A summary: This is a single line overview of the notification. For + instance "You have mail" or "A friend has come online". It should + generally not be longer than 40 characters (FIXME: is 40 sane?) + +- An optional body: This is a multi-line body of text. Each line is a + paragraph, server implementations are free to word wrap them as they + see fit. + + The text may contain simple markup as specified in the MARKUP + section below. + + If the body is omitted just the summary is displayed. + +- An optional icon: See the ICONS/SOUNDS section below. + +- An optional sound: See the ICONS/SOUNDS section below. + +- An array of buttons. The buttons send a request message back to the + notification client when clicked. + +- A timeout: the time in milliseconds after which the notification + should be hidden (FIXME: should this be a function of text length + to accommodate different reading speeds?). If zero the notification + stays on-screen indefinitely (persistent notifications). + + The timeout should be respected by implementations, but this is not + required (this is for compatibility with KNotify). + + +Each notification displayed is allocated a unique ID by the server +(FIXME: should this be unique within a session, or just unique while +the notification is active?). This can be used to hide the +notification before the timeout is over. It can also be used to +atomically replace the notification with another: this allows you to +(for instance) modify the contents of a notification while it's +on-screen. + + +BACKWARDS COMPATIBILITY + +Prior art in this area is basically just the KNotify system. This +specification strives to be compatible with KNotify, however there is +still some semantic mismatch. Clients should try and avoid making +assumptions about the presentation and abilities of the notification +server: the message content is the most important thing. + + +MARKUP + +Write me! + + + +ICON ENCODING + +Write me! + + + +DBUS PROTOCOL + +Write me! |