\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#222: Add [wm attributes -alpha] Attribute on Windows}
\date{September 16, 2004}
\author{Jeff Hobbs, Andreas Kupries}
\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 \#222}&\textbf{Add [wm attributes -alpha] Attribute on Windows}\\\hline
Author&

Jeff Hobbs \tipmail{jeffh}{activestate.com}
\par
Andreas Kupries \tipmail{akupries}{shaw.ca}
\\
Created&Thursday, \(\text{16}^{\text{th}}\) September 2004\\
Type&Project\\
Tcl Version&\(8.5\)\\
State&Final\\
Vote&Done\\
Version&\tipversion$Revision: 1.8 $\\
Keywords&Tk\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP proposes a new controlled attribute \textbf{-alpha} to control toplevel alpha transparency for the \textbf{wm attributes} command on Windows.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

Windows 2000/XP+ has the ability to create windows with alpha transparency. This attribute would expose control for that functionality for Tk users. This is mostly an eye candy feature, but could be useful for fade-in splash screens or fancy demos.

\section{Specification}

A new attribute \textbf{-alpha} will be recognized by \textbf{wm attributes}. It will take a double value from 0.0 (completely transparent) to 1.0 (opaque) that signifies the percentage transparency of the toplevel. Thus, \textbf{-alpha 0.9} would make the toplevel 90\% visible (10\% transparent). Any value outside [0.0..1.0] will be constrained to the nearest bound.

There are some special considerations for this feature. It only works on Windows 2000/XP+. The code handles the dynamic lookup of the necessary functionality. If you do not have the functionality, then any attempt to set the \textbf{-alpha} value will be ignored, and queries to \textbf{-alpha} will always return 0 (opaque).

Layered windows cannot use the CS\_CLASSDC class style, so an alternative class must be made available. This is handled in the implementation transparently, with \textit{UpdateWrapper} choosing the appropriate class as necessary. Transparent windows will use \textbf{TkToplevelNoDC} as their class name (normal is \textbf{TkToplevel}).

Efforts have been made to reduce calls to \textit{UpdateWrapper}.

\section{Reference Implementation}

See Tk Patch 892194 [\url{http://sf.net/support/tracker.php?aid=892194}]

The reference patch implements the functionality along with one bug fix to \textit{UpdateWrapper} --- correct setting of the Z order of the window based on the previous wrapper window.

While this patch addresses Windows alpha transparency, it is available for other platforms. It is recommended that the same syntax be used across platforms.

\section{Comments}

Discussion focused around the use of \textit{-alpha} versus \textit{-transparency}. Some felt that the latter was more familiar to end users. The author refutes this with several points. First, the existing TIP\#166 uses \textit{-alpha} as well, for the same functionality specific to Tk images (using the same [0..1] value as well). Also, the underlying APIs for each platform refer to the alpha level as well. In looking over various documentation, transparency is often a boolean concept, which alpha is the gradual level. This is how it will be used in Tk.

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

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