\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#223: Full-Screen Toplevel Support for Tk}
\date{September 21, 2004}
\author{Mo DeJong}
\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 \#223}&\textbf{Full-Screen Toplevel Support for Tk}\\\hline
Author&

Mo DeJong \tipmail{mdejong}{users.sourceforge.net}
\\
Created&Tuesday, \(\text{21}^{\text{st}}\) September 2004\\
Type&Project\\
Tcl Version&\(8.5\)\\
State&Final\\
Vote&Done\\
Version&\tipversion$Revision: 1.6 $\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

Tk lacks an optimal method for creating a full-screen \textbf{toplevel}. A full-screen toplevel is one that has no borders and a client drawing area that covers the entire screen. On some UNIX systems, one can create a normal toplevel that is a little larger than size of the screen and place the upper left corner of the client drawing area at at (0,0). This option is not available under Windows as the position and dimensions of normal windows are constrained to keep them from covering up the start menu and task bar. Under Windows, a zoomed toplevel with the \textit{overrideredirect} flag set avoids this size restriction and displays with no borders, both desirable properties. Unfortunately, setting the \textit{overrideredirect} flag also keeps an icon for the toplevel from being displayed in the task bar and in the programs list accessed via Alt-Tab. There are also some UNIX systems that restrict the placement of a normal toplevel window. For example, the default window manager for the KDE desktop restricts size and placement of a normal toplevel in much the same way as Windows. This TIP and its associated patch implement full-screen functionality that also displays an icon in the taskbar and is accessible via Alt-Tab. The implementation adds a new \textbf{-fullscreen} option to the \textbf{wm attributes} subcommand.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Motivation}

A Tk developer will at some point need to create a full-screen application. Existing Tk commands under Windows can be used to create a mostly working full-screen application, but the edge cases where it does not work well make the application look unprofessional. The example code[\url{http://wiki.tcl.tk/12506}] was created to support a native looking full-screen Windows application using only existing Tk commands.

The main problem this example attempts to work around is that a toplevel with the overrideredirect flag set does not show an icon in the Windows taskbar. To address this issue, a second fake window was created and certain events for the fake window are redirected to the full-screen window. This approach works for the most part but there are some real user visible problems that don't seem to be fixable. When a toplevel switched from regular to full-screen mode the user observes two resizing operations, first to switch to the zoomed state and another to switch to the overrideredirect state. Another user visible problem shows when the interpreter is busy processing code between the time a focus event is delivered to the fake window and it is redirected to the full-screen window. The fake window is mapped with a solid color fill for a moment which is visually disruptive.

A similar user visible problem can be seen when the Windows desktop is stretched across two monitors. If the toplevel is moved over to the second monitor and then placed in full-screen mode, the fake window appears in the main desktop. This is especially disruptive because the fake window needs to mirror the zoomed state of the full-screen window so that the state available via a right click in the Windows taskbar match up. The result is that the fake window covers up all the other applications on the first monitor.

The final user visible issue shows up when a full-screen window is first mapped. The window gets mapped in the normal state and is then resized to full-screen instead of being mapped at the size of the screen. These application behaviors do not match native Windows apps and just look unprofessional. As a result, a project was undertaken to create a Tk patch to address these issues.

\section{Proposal}

The implementation adds a \textbf{-fullscreen} attribute that can be set to a boolean value of 0 or 1. Example code to switch a window from normal to full-screen mode is as follows.
\begingroup\small\begin{verbatim}
proc fullscreen_switch { top } {
    if {[wm attributes $top -fullscreen]} {
        wm attributes $top -fullscreen 0
    } else {
        wm attributes $top -fullscreen 0
    }
}
\end{verbatim}
\endgroup

An implementation for Windows has been created to support this new \textbf{-fullscreen} attribute. The list of changed files is as follows:

\begin{quote}
\textit{doc/wm.n, tests/winWm.test, tests/wm.test, win/tkWinWm.c}
\end{quote}

Tk patch 1032982 has been created to track these modifications. The patch mostly duplicates the way an overrideredirect window is created with some modifications so that the window is the proper size and has an icon in the taskbar. In \textit{UpdateWrapper} the Win32 \textit{CreateWindowEx} function is invoked with the WS\_EX\_APPWINDOW flag passed as the \textit{dwExStyle} argument and (WS\_POPUP\tipbar{}WS\_CLIPCHILDREN\tipbar{}CS\_DBLCLKS) passed as the \textit{dwStyle} argument. Example Win32 code to create a standalone example of such a window is also attached and can be found in the file named \textit{full\_screen.c}. The patch also includes additions to the Tk test suite and documentation to cover these modifications.

\section{Alternatives}

One alternative is to do nothing. The existing pure Tcl implementation works for most cases. Reasons for rejecting this alternative have already been covered in this TIP.

An earlier approach that added a new \textbf{fullscreen} state available via the \textbf{wm state} subcommand was abandoned based on advice from Joe English. After implementing it both ways, both the Tk, and the end user code seemed cleaner using the attributes approach.

Assuming the TIP is accepted and a new attribute is added, there is one implementation alternative that might be useful to explore. There may be a way to pass a window manager hint to the Windows OS so that it allows the creation of a normal window that is larger than the height of the screen minus the height of the task bar. That would mean a regular window class could be used instead of a popup class. The only user visible change would be that right clicking on the icon in the taskbar would show a context menu with the Restore, Minimize, Maximise, and Close options. The current patch creates a taskbar icon that always pops the full-screen window to the top on a left or right click. It is not clear that this minor detail is important enough to worry about.

\section{Risks}

The complexity of Unix and Mac implementation of this TIP is currently not known.

\section{See Also}

SourceForge patch: 1032982

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

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