GNOME icons again

[Felix Bellaby <felix pooh u-net com>]

This proposal outlines how GNOME should supply icons and panel menu data
to wms. It draws heavily on suggestions by Raster, Mandrake and Marko.

I would like to implement this proposal but it remains incomplete 
because I have run into a nasty problem getting towards the end.
GNOME does not have the widget that I need to implement this cleanly, 
it uses one from Gtk instead which can not be made GNOME specific. 
The widget concerned is GtkWindow!!!!

Unfortunately, unlike Xt, Gtk does not accomodate "Vendor" defined
extensions to its "Shell" widgets.

Can anyone see a (nice) way out ? 

Or do  we need a GnomeWindow widget ?

Overview
--------

GNOME will provide scalable, shaped, icon windows to GNOME aware wms 
from three separate sources:

 1) Some GNOME apps create their own scalable, shaped, icon windows at 
    runtime using windowed GtkWidgets ("runtime icons").

 2) The panel provides scalable, shaped, icon windows for building a 
    root menu ("menu icons").

 3) The panel implement scalable, shaped icon windows using user defined 
    images indexed by class hints using "empty" windows provided by the 
    wm ("user icons")

The panel provides additional facilities for building root menus:

 1) Details of the panel menu heirarchy including two values: 

    a) The menu icon. 

    b) The fully scoped desktop entry name.

 2) A launch facility for starting panel menu items through X

The panel provides flags indexed by class hints taking two values: 

 a) "A" - the user has assigned an icon to this class hint.

 b) "P" - the user prefers this user icon to any runtime icon.

Non-GNOME apps which provide scalable runtime icon windows fit 
seemlessly into this model. This proposal does not assist wms in
dealing with non-scalable runtime icons provided by legacy apps
but users can choose to override them with user icons.

The purpose of this proposal is to provide scalable icon images which 
wms can use rather than specifying how they use them.

However, the design has the following intentions:

1) WMs use the menu icons to build their launch menus.

2) WMs use the user icons as their user defined icon images.

3) WMs rescale the runtime and user icons when clients man and unmap
   to provide titlebar and desktop menus (or their equivalents).

4) WMs may combine runtime and user icons to form composite icons.

5) WMs may add additional decorations to the GNOME icons but should
   not need to replace them with another layer of user configuration.

This proposal is intended to be sufficiently efficient and flexible
to meet these intentions. Please comment on its failings.

GNOME aware wm interface
------------------------

GNOME aware wms can access the runtime icon for a GNOME app by
reading the IconWindowHint from the WM_HINTS property. This
icon will either be provided by the app or it will be provided
automatically by the gnome libs using the user icon for the
relevent class hint or a default GNOME user icon. As a result, 
EVERY GNOME app is guaranteed to have a runtime icon.

GNOME aware wms do not need pixmaps icons for GNOME apps.
Setting the WIN_GNOME_ICONS atom in the WIN_PROTOCOLS property
on root (screen 0) will suppress support for pixmap protocols
by the gnome-libs and increase the efficiency of GNOME apps.

GNOME aware wms access the menu icons and menu data by reading
X resources from the RESOURCE_MANAGER property on root (screen 0). 
There are two types of X resource specified:

"GnomePanelMenu." DesktopEntry ".name:" <GnomeDesktopEntry::name>
"GnomePanelMenu." DesktopEntry ".icon:" <menu icon window id>

where

DesktopEntry  = {DesktopEntry "."} ComponentName
ComponentName = NameChar {NameChar}
NameChar      = "a"-"z" | "A"-"Z" | "0"-"9" | "_" | "-"

Arranging the ComponentNames in ASCII order within each level
reproduces the exact structure of the panel menu. 

[A third resource type might be useful to remote X apps but IMO
 wms would not use it so I do not propose to implement it:
 "gnomePanelMenu."MenuEntry".comment:" <GnomeDesktopEntry::comment>]

GNOME aware wms may launch panel menu entries

GNOME aware wms access the user icon flags by reading X resources 
from the RESOURCE_MANAGER property on root (screen 0). 
The X resources specified take the following form:

ComponentName ".gnomeUserIconFlag:" {"A" | "P"}

The ComponentName corresponds to an X resource class or name that
may appear in the WM_CLASS property of a wm client window.

GNOME aware wms access the user icons using the following protocol:

1) The wm creates an X window on a screen.

2) The wm sets the WM_CLASS property on this new X window to match
   the WM_CLASS of the desired user icon (usually the WM_CLASS
   of the client window that generated the MapRequest).

3) The wm prepends the window id onto the GNOME_USER_ICONS property
   on root for its screen. This property is of type WINDOW.

4) The wm uses the window as part of its decorations.

GNOME selects the Configure and MapNotify events on windows in the
GNOME_USER_ICONS property to render user images and may apply XShape 
masks to those windows. The wm should not break this behavior.

GNOME uses a default image to render user icons when the WM_CLASS
hint is absent or it fails to match any user icon flag. 
This default image is user defined.

WMs should be aware that the runtime and user icons for a GNOME app
may be identical in appearance. When the icons have identical 
WM_CLASS properties then they will be identical in appearance.

Interoperability
----------------

There are no GNOME aware wms available yet (for obvious reasons).
Furthermore, (AFAIK) all wms that currently support app defined
titlebar icons do so by requesting pixmaps rather than scaling 
an icon window. Accordingly, the gnome-libs will implement the 
protocols necessary for GNOME apps to work with legacy wms.

When the WIN_GNOME_ICONS atom is not set then the gnome libs will:

0) Provide the icon window using the WM_HINTS based protocol.

1) Retrieve any sizes specified in the WM_ICON_SIZES property,

2) ELSE use the sizes 32x32 and 16x16.

[Are there any wms still in circulation thata do not suppport
 the WM_ICON_SIZES protocol ? Which pixmap sizes can they use?] 

3) Provide pixmaps/masks/etc using the WIN_ICONS based protocol,

4) ELSE provide a pixmap/mask using the KWN_WIN_ICON based protocol
	(at the smallest requested size) and a pixmap/mask using 
	the WM_HINTS based protocol (at the largest requested size).

[Is this what the KWM wants ?]

5) ELSE provide a pixmap/mask using the WM_HINTS based protocol
	(at the smallest requested size).

[Do any wms use this approach to get a titlebar icon?] 

Protocols 3 and 4 will not be used unless the wm specifies support.

[My knowledge of how wms interpret 

The icon window implementation
------------------------------

The implementation of the icons windows is completely opaque to the wm. 
The following specification seeks to get the ball rolling with a
simple approach that can be extended in the future.

Each user and menu icon window is associated with a single image file 
which it renders using imlib to form its background pixmap on receiving 
a configuration or map event. Any mask from the image is applied to 
form a shaped window.

The panel process must have read access to the image files for all the
user icons and to the desktop entry files used to build the panel menu. 

The image file for the user icon associated with a specific wm name
or wm class is recorded in the .desktop file for the app that creates
windows in that class. The files and resources are recorded as follows:

Icon=image.png
Resource=resource
Preferred=0
Icon1=image1.png
Resource1=resource1
Preferred1=1
...

The "Icon=" field is used to generate the image in the panel menu
and the corresponding menu icon. Setting the "Resource=" field to 
match the wm class for the app (i.e. the app_id, as proposed above) 
will mean that this image will be used for the default user icon 
for all the windows created by the GNOME app. 

The resource names should be descriptive and should follow the
syntax given for ComponentNames avove. Any underscores will be 
replaced with spaces to obtain a C locale string which (after i18n) 
will appear in the panel menu editor. GNOME apps should list all 
the wm names used by the app in its desktop file so that the 
panel menu editor can list them. The app may provide and assign 
user icons as part of its distribution.

For example, an app with a "Mail box window" (C locale name) that 
supplied an icon image "mailbox.png" for that window might have 
these lines in its desktop file:

Icon2=mailbox.png
Resource2=Mail_box_window

A "Resource?=" field without an icon is an unassigned user icon 
and does not appear in the X resources passed to the wm. 
The "Preferred?=" field is used to determine the value of the 
".gnomeUserIconFlag" in the X resources and setting it to "1"
will set that flage to "P". 

On start up the panel scans the desktop files under the apps/
subdirectory and converts the information to provide the 
X resources described above, creating unmapped menu icon windows
for the "Icon=" image files. 


GNOME icons API
---------------

GNOME app runtime icons are guaranteed to be scalable windows.
They are always available thoughout the life of the client window 
to which they are attached (via the WM_HINTS property). 

gdk already provides a function for setting a suitable runtime
icon:

void gdk_window_set_icon(GdkWindow, GdkWindow, GdkPixmap, GdkBitmap):
  sets the runtime icon window for a given gdk_window. 
  Gnome apps MUST implement exact scaling in response to 
  configuration events on these icon windows. 
  Gnome apps MUST NOT set pixmaps or bitmap masks.

The user icon attached to a window depends on it WM_CLASS property
which may be set with the gtk function:

void gkt_window_set_wmclass(GtkWindow, gchar*, gchar*): 
  determines the user icon used with a top level window by setting 
  its WM_CLASS property.

These functions work at a low level and are unlikely to inspire 
compliance among app programmers so something with more sugar is 
needed. Now the problems start...

I can add sugar to GnomeApp and GnomeDialog so that icons are easy
to assign to these top level windows. I can also implement the 
protocols, etc. needed to get them working properly. However, I
will be duplicating code and I will still have missed quite a
few top level windows created by GNOME apps using GtkWindow and
its Gtk descendents, GtkDialog, GtkColorsel, etc.

The problem is that icon code SHOULD go into the standard top level
widget (GtkWindow) but I want to add GNOME SPECIFIC icon code!
GNOME specific code can not go into GtkWindow.

There are ways round this but they break the widget model and I have
no intention of trying to use them. I think GNOME specific icons,
or any other GNOME specific help for wms or other top level window
functionality is basically impossible unless we introduce
a GnomeWindow. 


Felix