Author:		Georgios Petasis <petasis@iit.demokritos.gr>
State:		Final
Type:		Project
Vote:		Done
Tcl-Version:	8.5
Created:	01-Oct-2003
Post-History:

Abstract

Currently, Tk lacks a mechanism for allowing scripts to place colour icons in the window manager decorations of a toplevel window. Tk supports only the placement of monochrome bitmaps through the wm iconbitmap and wm iconmask commands. This TIP proposes an extension of the wm command with the iconphoto subcommand, which will pass a set of photo images as possible window manager icons.

Rationale

Almost all modern window managers or desktop environments offer support for using colour icons in toplevel window decorations. Tk has made some steps in this direction by allowing wm iconbitmap command to also accept a Windows icon file, to be used as an icon for a toplevel under windows. This solution is quite incomplete, and of course works only under windows. No support for colour icons under Unix is currently offered and I (think) the same is also true for Mac OS.

This TIP proposes the introduction of a new subcommand to the wm command, the iconphoto subcommand. (iconimage was an alternative that I rejected because bitmaps are also considered images by Tk). This subcommand will accept a Tk window name and a set of photo image names. These images will then passed to the window manager as possible window icons.

The wm iconphoto subcommand will be available under all platforms. However, at this stage of development I will focus mainly on Unix: I don't know anything about Mac OS (so others must help in this direction) and support for windows already exists. The final goal will be to support at least windows and Unix. There is currently a patch that implements the Unix port of wm iconphoto.

Currently, two different approaches are used by Unix applications to specify colour icons. The first approach uses the same mechanism as wm iconbitmap to pass the icon: instead of passing a monochrome pixmap (that is a bitmap), they pass a colour pixmap with 3 planes (no transparency). This approach works with many modern window managers (including the ones used by KDE and GNOME). However, as Joe English noted this approach violates the ICCCM, despite the fact that it is used by some applications (i.e. gvim).

The second approach (again pointed by Joe English) is the one proposed by freedesktop.org: The application defines a window property that holds a special encoding of the colour icons. I don't know exactly how many window managers follow this proposal, but the window managers in two popular desktops (KDE and GNOME) support it. My proposal is of course to follow the second approach, as it does not violate the ICCCM.

The window property that should be defined is "_NET_WM_ICON". From the specifications http://www.freedesktop.org/ :

_NET_WM_ICON

_NET_WM_ICON CARDINAL[][2+n]/32

This is an array of possible icons for the client. This specification does not stipulate what size these icons should be, but individual desktop environments or toolkits may do so. The Window Manager MAY scale any of these icons to an appropriate size.

This is an array of 32bit packed CARDINAL ARGB with high byte being A, low byte being B. The first two cardinals are width, height. Data is in rows, left to right and top to bottom.

Currently both KDE and GNOME window managers scale the provided icons to proper sizes.

Specification

This document proposes the following changes to the Tk core:

The addition of a new subcommand (iconphoto) to the wm command. This subcommand will accept the following arguments:

window: the name of a Tk toplevel window.

photo_image ?photo_image2 ...?: a set of Tk photo image names, that will be send to the window manager as potential icons.

Currently, no other facilities are planned (like for example getting back the image names that are currently used as icons).

Also, no facilities are provided to request the window manager what icon sizes are preferred, although Xlib offers a relevant function.

Reference Implementation

A reference implementation (initially for just Unix) is available http://sf.net/tracker/?func=detail&aid=815751&group_id=12997&atid=312997 .

Note that also I have a reference implementation of the first approach (passing a colour pixmap instead of a bitmap), in case we decide to follow this approach (or both simultaneously :-) ).

Notes

I don't know if I have handled the assignment of the four bytes inside the long correctly. Currently the code works fine under Linux. It would be great if somebody could re-write the assignment to use bit-shift operations :-)

Copyright