\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#242: Preselect Filter on tk\_get*File Dialogs}
\date{March 03, 2005}
\author{Brian Griffin}
\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 \#242}&\textbf{Preselect Filter on tk\_get*File Dialogs}\\\hline
Author&

Brian Griffin \tipmail{bgriffin}{model.com}
\\
Created&Thursday, \(\text{3}^{\text{rd}}\) March 2005\\
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}

This TIP proposes adding an \textbf{-typevariable} option to the \textbf{tk\_getOpenFile} and \textbf{tk\_getSaveFile} dialog box commands. This option will preselect the filter from the \textbf{-filetypes} list based on the type name.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

The standard Open and Save dialog boxes currently allow you to seed the initial directory and the initial file. The path returned by the call can be saved and used to seed future calls to these dialgo boxes. However, the selected filter cannot be choosen nor read, nor is examining the returned file path sufficient to guess at the filter setting. 

One common aspect of good U/I design is remembering prior selections so the user does not have to repeat actions each time a dialog is used. The initial directory and initial file options provide partially for this ability in the File dialog boxes, but the selected filter type is not controllable. 

The filter selection can also be used for format selection when the file extension is insufficient or not present as is typical in the Mac OS X environment. One example might be a file with the extension .xml, where the file contents may be data, schema, or a dtd. By selecting ``XML Schema'', over ``XML DTD'', the user can control the formatting of the .xml file.

By giving the application access to the filter selection, the UI can be made friendlier to the user.

\section{Proposed Change}

Since the requirement is to be able to set and read the filter selection, the proposal is to use a variable to control and access this feature of the dialog boxes. This is done by adding a \textbf{-typevariable} option to \textbf{tk\_getOpenFile} and \textbf{tk\_getSaveFile}. 

The variable specified is read once at the begining to select the appropriate filter. If the variable does not exist, or it's value does not match any filter typename, or is empty (\{\}), the dialog box will revert to the default behavior of selecting the first filter in the list.

When the dialog box is closed by using the Ok button, the variable is set to the typename value of the currently selected filter. The variable will not be updated while the dialog box is open and the user makes various selections. If the dialog box is closed using the Cancel button, the variable is not changed.

Example:
\begingroup\small\begin{verbatim}
    set types {
        {{Text Files}       {.txt}        }
        {{TCL Scripts}      {.tcl}        }
        {{C Source Files}   {.c}      TEXT}
        {{GIF Files}        {.gif}        }
        {{GIF Files}        {}        GIFF}
        {{All Files}        *             }
    }
    set type {C Source Files}
    tk_getOpenFile -filetypes $types -typevariable type
    set type
 => {TCL Scripts}
\end{verbatim}
\endgroup

To preselect .c files for the filter, set type \{C Source Files\}. If the filter is changed to \{TCL Scripts\}, for example, the variable ``type'' is modified to the value \{TCL Scripts\}.

\section{Reference Implementation}

A reference implementation will be posted to Tk patches[\url{http://sf.net/tracker/?func=detail&aid=1156388&group_id=12997&atid=312997}]. I have modified \textit{tkfbox.tcl} and \textit{tkWinDialog.c}. I have not looked at MacOSX yet.

\section{Acknowledgement}

Thanks to Michael Kirkham and Donal Fellows for their valuable suggestions.

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

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