\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#159: Extending Tk 'wm' Command to Support Coloured Icons}
\date{October 01, 2003}
\author{Georgios Petasis}
\urlstyle{sf}
\setlength{\parskip}{1ex}
\setlength{\parindent}{0pt}
\def\tipversion$#1${\texttt{\$#1\$}}
\def\tiplangle#1{\ensuremath{<}}
\def\tiprangle#1{\ensuremath{>}}
\def\tipbar#1{\ensuremath{|}}
\def\tipmail#1#2{\(\langle\){\small\expandafter\url{#1@#2}}\(\rangle\)}
\ifx\pdfoutput\undefined
\newcommand{\tipimage}[2]{\typeout{Make sure you download #1.eps}\ifthenelse{\lengthtest{0.8\textwidth>#2}\and\lengthtest{0pt<#2}}{\includegraphics{#1.eps}}{\includegraphics[width=0.8\textwidth]{#1.eps}}}
\newcommand{\tipxref}[1]{}
\newcommand{\tipxrefend}{}
\else
\newcommand{\tipimage}[2]{\typeout{Make sure you create #1.pdf}\ifthenelse{\lengthtest{0.8\textwidth>#2}\and\lengthtest{0pt<#2}}{\includegraphics{#1.pdf}}{\includegraphics[width=0.8\textwidth]{#1.pdf}}}
\pdfcatalog{/PageMode /UseOutlines}
\newcommand{\tipxref}[1]{\pdfannotlink attr {/C [0.5 0.5 1.0] /Border [0 0 1]} goto name {#1}}
\newcommand{\tipxrefend}{\pdfendlink}
\fi
\newenvironment{tipabstract}{\begin{abstract}}{\end{abstract}}
\begin{document}\maketitle
\begin{center}\begin{tabularx}{\linewidth}{|r@{: }X|}\hline
\textbf{TIP \#159}&\textbf{Extending Tk 'wm' Command to Support Coloured Icons}\\\hline
Author&

Georgios Petasis \tipmail{petasis}{iit.demokritos.gr}
\\
Created&Wednesday, \(\text{1}^{\text{st}}\) October 2003\\
Type&Project\\
Tcl Version&\(8.5\)\\
State&Final\\
Vote&Done\\
Version&\tipversion$Revision: 1.7 $\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

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 \textit{wm iconbitmap} and \textit{wm iconmask} commands. This TIP proposes an extension of the \textit{wm} command with the \textit{iconphoto} subcommand, which will pass a set of photo images as possible window manager icons.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{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 \textit{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 \textit{wm} command, the \textit{iconphoto} subcommand. (\textit{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 \textit{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 \textit{wm iconphoto}.

Currently, two different approaches are used by Unix applications to specify colour icons. The first approach uses the same mechanism as \textit{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 [\url{http://www.freedesktop.org/}]:

\begin{quote}
\_NET\_WM\_ICON
\end{quote}

\begin{quote}
\_NET\_WM\_ICON CARDINAL[][2+n]/32
\end{quote}

\begin{quote}
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.
\end{quote}

\begin{quote}
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.
\end{quote}

\begin{quote}
Currently both KDE and GNOME window managers scale the provided icons to proper sizes.
\end{quote}

\section{Specification}

This document proposes the following changes to the Tk core:
\begin{enumerate}
\item{}
The addition of a new subcommand (\textit{iconphoto}) to the \textit{wm} command. This subcommand will accept the following arguments:
\begin{description}
\item[window]
the name of a Tk toplevel window.
\item[photo\_image ?photo\_image2 ...?]
a set of Tk photo image names, that will be send to the window manager as potential icons.
\end{description}
\end{enumerate}

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.

\section{Reference Implementation}

A reference implementation (initially for just Unix) is available [\url{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 :-) ).

\section{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 :-)

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

\textit{TIP AutoGenerator --- written by Donal K. Fellows}
\end{document}
