Notifications spec: Icons

[Bo Thorsen]

Hi list,

There have been a bunch of emails going back and forth between the KDE and 
GNOME people about the notifications spec. It seems everyone wants to have a 
common spec instead of the two current implementations (galago and knotify). I 
think Enlightenment also have an implementation of galago, but I'm not certain 
of this.

The goal for these discussions is a single spec that's based on galago, but 
modified to suit the needs of more groups.

It has been suggested to get this done in time for KDE 4.3, which is just over 
one month away. I don't know about GNOME timing.

The first problem I'll raise is icons and images. These are mentioned several 
places, and not in a completely coherent way. At the end of this mail, you can 
find the text from all the places where icons or images are mentioned in the 
spec. I hope we can have a debate about these changes here, and then I will 
write up a patch to the spec and send it here.

In a mail (http://lists.freedesktop.org/archives/xdg/2008-April/009401.html) 
to this list, Aaron Seigo have these change requests concerning icons:

<quote>
Issue: the iibiiay format seems a bit overspecified.

Proposal: always use argb32 data.

Issue: this part of the spec seems generally underspecificied. there is no 
reference to how icons referenced by name are resolved (the theme and naming 
specs) to name one.

Proposal: remove this page entirely. all relevant information on icons can be 
found elsewhere in the spec. duplicating information in this way just begs 
for inconsistencies over time.

org.freedesktop.Notifications.Notify:

Issue: app_icon is not necessarily appropriate for a given notification. it is 
defined as "The optional program icon of the calling application." the other 
option is to use the icon_data hint instead and ship raw data. there's also 
abiguities as to the related to icon_data, where this icon is defined, etc.

Proposal: "The name of the icon to show in association with the notification, 
such as the application icon. The icon name should be accessible via icon 
theme loading as defined in the freedesktop.org Icon Theme and Icon Naming 
specifications {link to urls}. Alternatively, image data may be passed via 
the icon_data hint {link to description of hint}.
</quote>

My main problem with icons is that the spec seems to be confused as to what 
icons the notification server should present. For example, the app_icon is 
called "the notification icon" in section 2, but "app_icon" suggests a different 
meaning. Also, the desktop-entry hint can be used to get an icon. So which one 
should the notification server show? While the spec must give some room for 
server implementation freedom, it's hard to write an application when you 
don't know which icon the server will show.

Answering (http://lists.freedesktop.org/archives/xdg/2008-April/009409.html) 
Aaron, Olivier Gouffart writes this about the icons: "icon_data and app_icon 
are different: Take the Kopete online notification: app_icon is the kopete icon, 
while icon_data would be the user's avatar." This answer suggests that the 
application can provide both. But what will the server implementations show, 
then?

I hope we can have a good discussion about these items. I will send more mails 
with other pieces to discuss soon.

Thank you,

Bo Thorsen,
Canonical Ltd.

Here are all parts of the spec that mentions icons or images. You can find the 
full spec at http://www.galago-project.org/specs/notification/0.9/index.html.

Section 2 - Basic Design. This says a notification component has, among other 
properties, a "Notification Icon" with this description: "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). " Another component is the "Hints" which has this in it: "Element: 
Icon Data. Description: Instead of overloading the icon field we now have an 
icon_data field that is used when icon is blank."

Section 4.2 - Markup/Images. This is about simple HTML in the notification 
text. This markup text can have an inline image, which is specified with the 
<img> tag and must be a local file. It's mentioned here only for completeness, 
I haven't seen anyone requesting change to this.

Section 5 - Icons. Full text: "A notification can optionally have an icon 
specified by the Notification Icon field or by the icon_data hint. The icon_data 
field 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."

Section 8 - Hints. The list of standard hints include "image_data" (as 
mentioned in section 2). The value type is "iiibiiay". Full description text: 
"This is a raw data image format which describes the width, height, rowstride, 
has alpha, bits per sample, channels and image data respectively. We use this 
value if the icon field is left blank." Another hint is "desktop-entry", value 
type "Application Desktop ID", with this description: "This specifies the name 
of the desktop filename representing the calling program. This should be the 
same as the prefix used for the application's .desktop file. An example would be 
"rhythmbox" from "rhythmbox.desktop". This can be used by the daemon to 
retrieve the correct icon for the application, for logging purposes, etc."

Section 9.1.2 - D-Bus Protocol/Message commands/Notify call spec. In the list 
of arguments to the Notify call, it lists "app_icon" with type STRING and 
description: "The optional program icon of the calling application. See Icons. 
Can be an empty string, indicating no icon."