\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#141: Multiple Initial-Files in [tk\_getOpenFile]}
\date{July 18, 2003}
\author{David N. Welton}
\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 \#141}&\textbf{Multiple Initial-Files in [tk\_getOpenFile]}\\\hline
Author&

David N. Welton \tipmail{davidw}{dedasys.com}
\\
Created&Friday, \(\text{18}^{\text{th}}\) July 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}

This TIP proposes modifying the semantics of the \textbf{-initialfile} option when the \textbf{tk\_get*File} commands are asked to select multiple files so as to allow several files to be selected initially.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

The \textbf{tk\_getOpenFile} command has a \textbf{-multiple} option, which allows multiple files to be selected in the dialog. It also has an \textbf{-initialfile} argument. However, at the present time, at least on Unix, it is impossible to have multiple files selected initially with \textbf{-initialfile}. This TIP proposes that \textbf{-initialfile} take a list of files if \textbf{-multiple} is also passed as an argument.

As it is possible to select multiple files, it should also be possible to have multiple files be selected when the widget is created via the \textbf{-initialfile} switch.

\subsection{Additional Notes from Kevin Kenny}

\subsubsection{On -initialdir}

If the \textbf{-initialdir} value is not a well-formed path name in its filesystem (for instance, if a component name contains a null byte or a character that is not permissible), the behavior is as if \textbf{-initialdir} was not specified.

If the object designated by the \textbf{-initialdir} value does not exist, or if it is not a directory, nor a symbolic link to one, the behavior is as if \textbf{-initialdir} was not specified.

If the \textbf{-initialdir} value is the empty string, the behavior is as if \textbf{-initialdir} was not specified.

\subsubsection{On -initialfile}

If \textbf{-multiple} \textit{0} is specified, or \textbf{tk\_getSaveFile} was called, the \textbf{-initialfile} value is interpreted as a file name. If \textbf{-multiple} \textit{1} is specified to \textbf{tk\_getOpenFile}, the \textbf{-initialfile} value is interpreted as a list of file names. A list that is not well formed (for example, one containing unbalanced braces) is not an error, but instead causes the \textbf{-initialfile} option to be ignored.

For each file name in the \textbf{-initialfile} value, the system joins the directory provided on the \textbf{-initialdir} option (or the current working directory if no \textbf{-initialdir} is supplied) with the \textbf{-initialfile}. The resulting path name is normalized as with \textbf{file normalize} and then separated into directory and tail components as with \textbf{file dirname} and \textbf{file tail}. Any errors in this process cause the file name to be ignored.

Once the file name is separated into its components, the directory part is checked:
\begin{itemize}
\item{}
If the \textbf{-initialdir} option was supplied, and the directory part of the file name differs from the result of normalizing the \textbf{-initialdir} value, the file name is ignored.
\item{}
If the \textbf{-initialdir} option was not supplied, and the directory part of the file name designates a directory in the file system, the \textbf{-initialdir} value is set to that directory. Otherwise, (since the file cannot exist), the file name is ignored.
\item{}
If the given file exists, or if \textbf{tk\_getSaveFile was called}, the tail part of the file name is added to a list of files to select within the initial directory.
\end{itemize}

Once \textbf{-initialdir} and \textbf{-initialfile} have both been parsed, the initial directory is known, and the list of initial files is identified; the files are known to be relative to the initial directory, and (for \textbf{tk\_getOpenFile}) are known to exist.

\section{Reference Implementation}

The reference implementation exists in a patch [\url{http://sf.net/tracker/?func=detail&aid=657656&group_id=12997&atid=362997}] which also includes new tests for the Tk test suite and updated documentation.

\section{Copyright}

This document is in the public domain.

\section{Colophon}

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