\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#95: Add [wm attributes] Command}
\date{May 29, 2002}
\author{Jeff Hobbs}
\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 \#95}&\textbf{Add [wm attributes] Command}\\\hline
Author&

Jeff Hobbs \tipmail{JeffH}{ActiveState.com}
\\
Created&Wednesday, \(\text{29}^{\text{th}}\) May 2002\\
Type&Project\\
Tcl Version&\(8.4\)\\
State&Final\\
Vote&Done\\
Version&\tipversion$Revision: 1.5 $\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP proposes adding a [wm attributes] command in order to control platform-specific aspects of a toplevel. In addition, it proposes making [wm] a \textit{Tcl\_Obj}-based command and centralizing the common functionality.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

While Tk has been proven useful over time as a cross-platform toolkit, it has some serious drawbacks in acceptance due to small, but important, lacking functionality in the handling of toplevel windows on certain platforms. Having a toplevel stay on top on Windows is a prime example of a commonly requested feature for which there is no core support. Mac/Tk has long had a special unknown command to support special styles needed for proper ``look and feel'' there. I hereby propose a [wm attributes] command (like the [file attributes] command) to providing platform-specific functionality for toplevel windows.

\section{Specification}
\begingroup\small\begin{verbatim}
   wm attributes $toplevel ...
   [[WINDOWS]]
        ?-disabled ?bool??
        ?-toolwindow ?bool??
        ?-topmost ?bool??
        ?-minimizebox ?bool??
        ?-maximizebox ?bool??
        ?-sysmenu ?bool??
   [[MAC]]
        ?-style ?alert|moveablealert|modal|moveablemodal|
                 floating|document ...??
   [[UNIX]]
        <empty at this time>
\end{verbatim}
\endgroup

Because Tk started off on Unix, most potential attributes are already in the wm command, whether they really make sense across platforms or not (some equivalent has been emulated in most cases). If someone feels that there are some X window attributes that Tk does not support, this would be the place to put them.

On Windows, most of the attribute settings can be combined (they are OR-ed bits of special style fields on a toplevel), which is why they are set or retrieved as booleans. The names reflect their Win32 API bits. For Windows and the Mac, the naming of attributes and/or styles mirrors the native API as closely as possible, as we are exposing native platform functionality in this command. More specifics about Windows styles can be seen here:

\begin{quote}
\url{http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_styles32.asp}
\end{quote}

For Macs, styles are mutually exclusive, so you set one of a list of available styles. MacOS has nine standard window types and eight standard floating window types. More information can be seen here:

\begin{quote}
\url{http://developer.apple.com/techpubs/quicktime/qtdevdocs/INMAC/MACWIN/imWindowMgrRef.3.htm}
\end{quote}

\section{Reference Implementation}

Mac/Tk has a reference implementation already that would just adapt the existing \textit{unsupported1} code to \textit{wm attributes}. There are two variant patches for the Windows work in Tk patch 553926 at SF.

File: \textit{tk/mac/tkMacWm.c}

File: \textit{tk/win/tkWinWm.c}

File: \textit{tk/unix/tkUnixWm.c}

Function: \textit{Tk\_WmCmd}

\section{Comments}

Several names have been used for a command with similar functionality. Mac/Tk uses the \textit{style} command, as does Tk Patch 553926. This is only for platform-specific configuration of toplevel windows, and it not necessarily limited to style. I considered \textit{wm configure}, but I chose \textit{wm attributes} because that worked just as well and had the equivalent of \textit{file attributes} to support the naming.

Windows toplevels could have more special styles like \textit{-transparent}, Windows scrollbars on the toplevel and a few other window styles that the Win32 API supports. Only the styles that have had user requests are supported at this time. We may want to add \textit{-caption} and \textit{-dialogmodal} support if these seem useful.

It was recommended that commonality be reached where possible, but this tip addresses most specifically what isn't common across the minute aspects of toplevel window handing on different platforms. For examples, for Windows to allow TOPMOST, it keeps a special list of the topmost windows. This manager-level support is necessary to avoid contention amongst topmost windows. Macintosh has many special dialog and window styles to represent both changing UI design over time, as well as the latest in UI design that can be reached standard for Mac toplevels but not Unix or Windows ones.

It may be that certain functionality will become cross-platform as native APIs develop, but this is meant to allow access to key native look and feel features that Tk lacks for serious developers now.

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

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