\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#153: Enhancing the [winfo toplevel] Command}
\date{August 26, 2003}
\author{Neil McKay}
\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 \#153}&\textbf{Enhancing the [winfo toplevel] Command}\\\hline
Author&

Neil McKay \tipmail{mckay}{eecs.umich.edu}
\\
Created&Tuesday, \(\text{26}^{\text{th}}\) August 2003\\
Type&Project\\
Tcl Version&\(8.5\)\\
State&Final\\
Vote&Done\\
Version&\tipversion$Revision: 1.8 $\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

The [winfo toplevel] command returns the Tk toplevel window that encloses the window that's passed as an argument. However, Tk extensions may allow the creation of windows which reside at the top of a window hierarchy, but are not Tk toplevel widgets. If a subwindow of one of these top-of-hierarchy widgets is passed to [winfo toplevel], it returns an empty string, making it impossible to determine what hierarchy the window resides in. This TIP proposes enhancing the [winfo toplevel] command so that it will return the top window in the hierarchy regardless of what type of widget it is.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

Focus control does not work properly for top-of-hierarchy Tk windows other than toplevel widgets. This is an artifact of Tk's inability to determine the top of a window hierarchy for such windows. Prior to Tk 8.4, top-of-hierarchy windows other than toplevels were not possible, so the changes proposed in this TIP would be moot. However, they are now possible due to the incorporation into the Tk core of the changes proposed in \cite{tip47}.

As an example, consider the rootwin extension [\url{http://www.eecs.umich.edu/~mckay/computer/rootwin0.4.tar.gz}]. This extension adds a [rootwin] widget creation command, which turns an X display's root window into a Tk widget. The rootwin widget is a top-of-hierarchy widget, but is not an ordinary Tk toplevel. The command sequence
\begingroup\small\begin{verbatim}
 rootwin .r
 entry .r.e
 place .r.e -x 100 -y 100
\end{verbatim}
\endgroup

will create an entry widget near the upper left corner of the screen. However, it is impossible to type anything into the entry widget, because Tk's focus code does not work properly with rootwin widgets. The problem can be traced back to the fact that the command [winfo toplevel .r.e] returns the empty string. With the proposed extension, this command would return ``.r'', and the focus code would work properly.

\section{Compatibility}

The proposed behavior for [winfo toplevel] is different from the current behavior, although only in the presence of Tk extensions that create top-of-hierarchy widgets that are not toplevels. The rootwin package is the only such extension known to this TIP's author, so the difference in behavior is unlikely to be noticed by anyone else. It should also be noted that the behavior (prior to this TIP) of [winfo toplevel] for top-of-hierarchy widgets that are not toplevels is not specified, so relying on its current behavior in such cicumstances is a questionable practice.

\section{Implementation}

The core of the proposed change to [winfo toplevel] requires only a single-line change in file \textit{generic/tkWindow.c}; however, the patch described below also changes the name of a function and changes some comments, to better describe the code's behavior. It also documents the new behavior in the [winfo] man page.

\section{Patches}

A patch (against Tk 8.4.5) that implements the changes described above may be found at \url{http://www.eecs.umich.edu/~mckay/computer/winfotop.patch}

\section{Copyright}

This document is in the public domain.

\section{Colophon}

\textit{TIP AutoGenerator --- written by Donal K. Fellows}
\begin{thebibliography}{TIP \#1}
\addcontentsline{toc}{section}{References}
\bibitem[TIP \#47]{tip47}
Neil McKay,
Andreas Kupries,
Donal K. Fellows,
\emph{Modifying Tk to Allow Writing X Window managers},
on-line at \url{http://purl.org/tcl/tip/47.html}
\end{thebibliography}
\end{document}
