\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#8: Add Winico support to the wm command on windows}
\date{November 06, 2000}
\author{Vince Darley}
\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 \#8}&\textbf{Add Winico support to the wm command on windows}\\\hline
Author&

Vince Darley \tipmail{vince.darley}{eurobios.com}
\\
Created&Monday, \(\text{6}^{\text{th}}\) November 2000\\
Type&Project\\
Tcl Version&\(8.4.0\)\\
State&Final\\
Vote&Done\\
Version&\tipversion$Revision: 1.8 $\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

Add to \textit{wm} the ability to do the windows-titlebar-icon manipulation that the Winico extension currently provides, without the bugs noted in that extension.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Proposal}

Modify \textit{wm} on Windows only to allow an optional \textit{-default} argument.
\begingroup\small\begin{verbatim}
wm iconbitmap .winpath ?-default? filename
\end{verbatim}
\endgroup

And to allow a file which is of valid windows-icon format to be interpreted as such. Any file which is not correctly interpreted as an icon will be handled as before, by the \textit{bitmap} code (which will generally either do nothing, or throw an error, thus maintaining backwards compatibility).

The \textit{-default} argument, if given, will change not the icon of the .winpath given, but rather the default icon for all windows in the current application for which no specific icon as been set.

An implementation already exists, which fixes the basic ``wrapper window'' problems and which has the above syntax. The issues surrounding reference counting of icons in use has also been addressed in this patch so that icons no longer in use are released (the Winico patch required manual deletion of icons). This reference implementation is available from \url{ftp://ftp.ucsd.edu/pub/alpha/tcl/tkWinWm.diff} (documentation has been separately patched, and can also be made available).

\section{Rationale}

There have been many requests on \url{news:comp.lang.tcl} for this ability in the Tk core, and several bug reports filed against Winico, and this ability has been placed on the Tk 8.4 roadmap. \url{http://purl.org/tcl/home/software/tcltk/roadmap.tml}

The choice of \textit{wm iconbitmap} is suggested, because \textit{wm iconbitmap} currently doesn't appear to do anything on Windows, yet is the obvious choice for the user trying to set the window's icon (e.g. many posts on \url{news:comp.lang.tcl} are actually asking why \textit{wm iconbitmap} doesn't do anything).

In the future we may wish to extend \textit{wm iconbitmap} on all platforms so that other image types can be accepted (e.g. .gif, .png). This proposal extends naturally to allow such future work. The primary changes required will be icon\tiplangle{}-\tiprangle{}image conversion routines.

\section{Alternatives}

Fix the core so that Winico can work properly as an extension.

My implementation as shown that this would require a couple of patches, and also the exporting of an additional obscure function into Tk's stub table (a function which would ensure that Tk's window manager is completely initialised). It would also not help the users posting to \url{news:comp.lang.tcl} asking ``why doesn't wm iconbitmap do anything?''

\section{Objections}

\textit{This is platform specific and should go in an extension}

See \textit{Alternatives} above, also see the \textit{future suggestion} above in which this kind of code can be usefully extended in a cross-platform way.

\textit{The -default flag is weird, and it means we ignore the window name}

I agree, but please suggest a better alternative rather than just moaning. The command with the -default flag is in my opinion more useful than the command without (for example it makes sure that Tk's built-in dialogs have the icon of your application). An alternative might be to use \textit{wm iconbitmap -default filename}, but that involves more significant modifications of the semantics of \textit{wm}. It might, however, be a good idea.

\textit{wm iconbitmap will still do nothing when given a bitmap}

Yes, but there's that backwards compatibility issue. This should be properly documented with pointers to the use of valid icon file formats. When or if proper support is added to Tk for .gif, .png or even Tk images as icons, this bug can be fixed. The purpose of this TIP is not to fix that bug, but to provide a better solution.

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

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