TIP: 159
Title: Extending Tk 'wm' Command to Support Coloured Icons
Version: $Revision: 1.4 $
Author: Georgios Petasis <[email protected]>
State: Draft
Type: Project
Vote: Pending
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:
1. 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
This document has been placed in the public domain.