From 4497c99f858350e81ca2de4e60bd6fcb3d144caa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aur=C3=A9lien=20G=C3=A2teau?= Date: Sun, 31 Jan 2010 16:17:24 -0500 Subject: [spec] Update for version 1.1 --- docs/notification-spec.xml | 143 +++++++++++++++++++++++---------------------- 1 file changed, 73 insertions(+), 70 deletions(-) diff --git a/docs/notification-spec.xml b/docs/notification-spec.xml index 667f82b..7df9e05 100644 --- a/docs/notification-spec.xml +++ b/docs/notification-spec.xml @@ -3,7 +3,7 @@
Desktop Notifications Specification - Version 1.0 + Version 1.1 25 August 2007 @@ -31,8 +31,8 @@ 25 August 2007 cdh - Added spec_version to the GetServerInformation return values. - Mark this specification as a 1.0. + Added spec_version to the GetServerInformation return values. + Mark this specification as a 1.0. @@ -195,9 +195,7 @@ Notification Icon - The notification icon. This is represented either as a URI - (file:// is the only URI schema supported right now) or a name in - a freedesktop.org-compliant icon theme (not a GTK+ stock ID). + The notification icon. See . @@ -254,35 +252,11 @@ Hints - See . - Beyond the core protocol is the hints table. A couple of core - elements have been moved to hints mostly because in a huge number - of cases their default values would be sufficent. The elements moved - to hints are: + Hints are a way to provide extra data to a notification server that + the server may be able to make use of. - - Elements Moved to Hints - Element - Description - - Category ID - An optional ID representing the type of notification (the name - has been changed from Notification Type ID in pervious versions). - See . - - - Urgency Level - The urgency of the notification. See - . (Defaults to 1 - Normal) - - - Icon Data - Deprecated and should not be used in new - implementations. Use the Image Data hint instead. - - - + See for a list of available hints. @@ -449,34 +423,54 @@ - - Icons + + Icons and Images - A notification can optionally have an icon specified by the Notification - Icon field or by the image_data or image_path hints. + A notification can optionally have an associated icon and/or image. - The image_data hint should be a raw image data structure of signature - (iiibiiay) which describes the width, height, rowstride, has alpha, bits - per sample, channels and image data respectively. If an implementation - cannot display multiple icons then image_data should be preferred over - the Notification Icon field, as this icon is generally used to provide - more specific information about the notification (for example, a chat - application may use this field for a contact's icon). + The icon is defined by the "app_icon" parameter. + The image can be defined by the "image_path", the "image_data" hint or the + deprecated "icon_data" hint. - - The image_path hint should be a string that contains the path to an image - to use, or a FreeDesktop.org icon name. For the same reasons as above - this icon should be used before the icon specified in the Notification Icon - field if present. If the image_data hint is present, this hint should - be ignored. - - - In existing implementations, a third deprecated hint "icon_data" may be - present, and is used similarly to the image_data hint. However, - new implementations should not use this hint, and existing - implementations should migrate to image_data instead. + + Priorities + + An implementation which only displays one image or icon must choose which one + to display using the following order: + + "image_data" + "image_path" + app_icon parameter + for compatibility reason, "icon_data" + + + + + An implementation which can display both the image and icon must show the + icon from the "app_icon" parameter and choose which image to display using + the following order: + + "image_data" + "image_path" + for compatibility reason, "icon_data" + + + + + + Formats + + The "image_data" and "icon_data" hints should be a raw image data structure + of signature (iiibiiay) which describes the width, height, rowstride, has + alpha, bits per sample, channels and image data respectively. + + The "app_icon" parameter and "image_path" hint should be either an URI + (file:// is the only URI schema supported right now) or a name in a + freedesktop.org-compliant icon theme (not a GTK+ stock ID). + + @@ -735,6 +729,7 @@ Name Value Type Description + Spec Version @@ -744,6 +739,7 @@ The urgency level. + "category" @@ -751,6 +747,7 @@ The type of notification this is. + "desktop-entry" @@ -762,15 +759,7 @@ "rhythmbox.desktop". This can be used by the daemon to retrieve the correct icon for the application, for logging purposes, etc. - - - "image_path" - string - - This is represented either as a URI (file:// is the only URI - schema supported right now) or a name in a - freedesktop.org-compliant icon theme (not a GTK+ stock ID). - + "image_data" @@ -780,6 +769,15 @@ rowstride, has alpha, bits per sample, channels and image data respectively. + >= 1.1 + + + "image_path" + string + + Alternative way to define the notification image. See . + + >= 1.1 "icon_data" @@ -787,6 +785,7 @@ Deprecated. Use image_data instead. + < 1.1 "sound-file" @@ -794,17 +793,18 @@ The path to a sound file to play when the notification pops up. + "sound-name" string A themeable named sound from the freedesktop.org - sound - naming specification to play when the notification pops - up. Similar to icon-name, only for sounds. An example would be - "message-new-instant". + sound naming specification + to play when the notification pops up. Similar to icon-name, only for + sounds. An example would be "message-new-instant". + "suppress-sound" @@ -814,6 +814,7 @@ ability. This is usually set when the client itself is going to play its own sound. + "x" @@ -822,6 +823,7 @@ Specifies the X location on the screen that the notification should point to. The "y" hint must also be specified. + "y" @@ -830,6 +832,7 @@ Specifies the Y location on the screen that the notification should point to. The "x" hint must also be specified. + @@ -996,7 +999,7 @@ app_icon STRING - The optional program icon of the calling application. See . + The optional program icon of the calling application. See . Can be an empty string, indicating no icon. -- cgit v1.2.1