\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#125: Converting between Frame and Toplevel Windows}
\date{January 20, 2003}
\author{Brian Griffin, Donal K. Fellows, Sacha Schär}
\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 \#125}&\textbf{Converting between Frame and Toplevel Windows}\\\hline
Author&

Brian Griffin \tipmail{bgriffin}{model.com}
\par
Donal K. Fellows \tipmail{donal.k.fellows}{man.ac.uk}
\par
Sacha Schär \tipmail{sacha.schaer}{unibas.ch}
\\
Created&Monday, \(\text{20}^{\text{th}}\) January 2003\\
Type&Project\\
Tcl Version&\(8.5\)\\
State&Final\\
Vote&Done\\
Version&\tipversion$Revision: 1.10 $\\
Keywords&reparent, Tk\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP modifies the \textbf{wm} command to act as a geometry manager for Frames, allowing them to become Toplevel windows.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

One of the usability features introduced recently in many windowing systems, is the ability to ``tear out'' or ``insert'' sub-frames and panes within an application. The most common form of this is the ability to tear off a toolbar, making it an independent window. This feature gives the end user the ability to configure the application in ways that best suit them and improve their overall productivity.

Currently there is no mechanism with Tk to move a widget subtree to a new toplevel parent without reconstructing the hierarchy from scratch. The basic command will give the Tk programmer the ability to implement megawidgets that support tear-off toolbars, notebooks, etc., since the children widgets of the frame will follow along, unchanged.

An alternative approach has been taken from the orignal \textbf{wm toplevel} proposal as described here:

In Tk, Toplevel windows are basically a special form of a Frame which are managed by the window manager. The proposal is to add the commands \textbf{wm manage} and \textbf{wm forget} which will take an arbitrary Frame and allow it to be managed by the window manager, making it a Toplevel window.

There are three configure options of Toplevel that are not present on a frame, \textbf{-menu}, \textbf{-screen}, and \textbf{-use}. The options \textbf{-screen} and \textbf{-use} can only be specified when a Toplevel is created and cannot be modified later. The \textbf{-menu} option can be modified after widget creation and should be available on a frame so that when the frame is managed as a Toplevel, the menu can be present, therefore, this option has been added to the Frame widget. When a frame is not managed as a toplevel, the \textbf{-menu} option is ignored.

Note: because of special conditions of Toplevel, it is necessary to restrict them to only be managed by the window manager; they cannot be converted to frames and therefore, \textbf{wm forget} is not allowed on a Toplevel widget.

\section{Reference Implementation}

TkToolkit patch \#998125 implements the \textbf{wm manage} and \textbf{wm forget} commands on Unix and Windows. A partial MacOSX implementation is also provided. This implementation only works for buttons and menubuttons. For the remaining Tk widgets to be present in a \textbf{wm manage}'d frame, the widgets need to recognize and implement the TK\_URBAN\_RENEWAL flag.

The original \textbf{wm toplevel} implementation can be obtained [\url{ftp://ftp.model.com/pub/tcl/reframe}], with patch files as well as Linux and Win32 builds of 8.3.4 and 8.4.1 available.

The \textit{demo.tcl} file illustrates the basic function.

\section{Known Issues}

The reference implementation works on Windows and Linux. A Mac implementation has been partially implemented. Because of the Mac architecture, it is necessary to reconstruct widgets in order to remap their window hierarchy. The reference implementation includes a widget flag, TK\_URBAN\_RENEWAL which is used to trigger this reconstruction.

Because of assumptions and restrictions, Toplevels can only be managed by the window manager and cannot become frames and be managed by any other geometry manager. This restriction is enforced which means the \textbf{-use} and \textbf{-screen} options do not present any problem or complication with this proposal.

The toplevel \textbf{-menu} option has been added to frames. This allows the setting of menus on a frame so that when the frame is managed as a toplevel, the menus will appear, otherwise the option is ignored.

\section{Alternatives}

An alternative to extending the \textbf{wm} command is to make this feature either a method or a configure option of the Toplevel and Frame widget.

\textit{A.} [\textit{w} \textbf{detach}] to convert a Frame into a Toplevel, and [\textit{w} attach\('''\)] to convert a Toplevel into a Frame.

\textit{B.} [\textit{w} \textbf{configure -toplevel 1}] to convert a Frame into a Toplevel, and [\textit{w} \textbf{configure -toplevel 0}] to convert a Toplevel into a Frame.

These different approaches (wm, method, config) depend on how the feature is viewed. One view is that the of changing the nature or class (Toplevel, Frame) of the widget. An alternative view is that of changing ``who'' manages the widget (wm, place, grid, pack).

I suppose another alternative is to follow the precedent of the geometry managers:
\begin{itemize}
\item{}
\textbf{wm} \textit{w} ?\textbf{-transient} \textit{parent}? ?\textbf{-overrideredirect} \textit{boolean}? ...
\item{}
\textbf{wm forget} \textit{w}
\end{itemize}

\section{Comments}

\textit{From Sacha Schär \tipmail{sacha.schaer}{unibas.ch}:}

The way the TIP and its alternatives are proposed, a frame can be made into a toplevel and vice versa. However, it is not possible, to move a frame from one toplevel to another. This is of importance even for the most common motivation for this TIP, the possibility to implement a tear-off behaviour. If a frame is going to be teared out of a toplevel window, it might be desirable that it becomes part of another toplevel window, together with some extra decoration.

I see, that with this more general behaviour, the path name becomes a problem. Therefore I propose the alternative approach, of making the \textbf{-container} and \textbf{-use} options dynamically configurable as already discussed in the past

\textit{From Brian:}

The problem is that we can't reparent widgets without changing their Tk widget pathname. Doing this introduces all kinds of sticky problems.

In practice, the decoration is in the form of Menus, Toolbars, and Footers. All of these things can (must) be created and managed as part of the dock/undock process. The way to do this is to create these things the first time a window is undocked, then just ``hide'' them when redocking the window; they still exist, but are just not mapped anywhere, until the next time the window is undocked.

The bottom line is that the \textbf{wm manage} command does not do \textit{everything} you need when performing an undock operation; it is only a small piece of the pie, but a very critical one.

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

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