<?xml version="1.0" encoding="ISO-8859-1" ?>
<!DOCTYPE TIP SYSTEM "http://www.tcl.tk/cgi-bin/tct/tip/tipxml.dtd">
<!-- Converted at Wed Jun 19 14:38:35 GMT 2013 -->
<!-- TIP AutoGenerator - written by Donal K. Fellows -->

<TIP number='141'>
<header><title>Multiple Initial-Files in [tk_getOpenFile]</title><author address="mailto:davidw@dedasys.com">David N. Welton</author><status type='project' state='final' tclversion="8.5" vote='after'>$Revision: 1.8 $</status><history></history><created day='18' month='jul' year='2003' /></header>
<abstract>This TIP proposes modifying the semantics of the <emph style="bold">-initialfile</emph> option when the <emph style="bold">tk_get*File</emph> commands are asked to select multiple files so as to allow several files to be selected initially.</abstract>
<body><section title="Rationale">
<para>The <emph style="bold">tk_getOpenFile</emph> command has a <emph style="bold">-multiple</emph> option, which allows multiple files to be selected in the dialog. It also has an <emph style="bold">-initialfile</emph> argument. However, at the present time, at least on Unix, it is impossible to have multiple files selected initially with <emph style="bold">-initialfile</emph>. This TIP proposes that <emph style="bold">-initialfile</emph> take a list of files if <emph style="bold">-multiple</emph> is also passed as an argument.</para>
<para>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 <emph style="bold">-initialfile</emph> switch.</para>
<subsection title="Additional Notes from Kevin Kenny">

<subsubsection title="On -initialdir">
<para>If the <emph style="bold">-initialdir</emph> 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 <emph style="bold">-initialdir</emph> was not specified.</para>
<para>If the object designated by the <emph style="bold">-initialdir</emph> value does not exist, or if it is not a directory, nor a symbolic link to one, the behavior is as if <emph style="bold">-initialdir</emph> was not specified.</para>
<para>If the <emph style="bold">-initialdir</emph> value is the empty string, the behavior is as if <emph style="bold">-initialdir</emph> was not specified.</para>
</subsubsection>
<subsubsection title="On -initialfile">
<para>If <emph style="bold">-multiple</emph> <emph style="italic">0</emph> is specified, or <emph style="bold">tk_getSaveFile</emph> was called, the <emph style="bold">-initialfile</emph> value is interpreted as a file name. If <emph style="bold">-multiple</emph> <emph style="italic">1</emph> is specified to <emph style="bold">tk_getOpenFile</emph>, the <emph style="bold">-initialfile</emph> 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 <emph style="bold">-initialfile</emph> option to be ignored.</para>
<para>For each file name in the <emph style="bold">-initialfile</emph> value, the system joins the directory provided on the <emph style="bold">-initialdir</emph> option (or the current working directory if no <emph style="bold">-initialdir</emph> is supplied) with the <emph style="bold">-initialfile</emph>. The resulting path name is normalized as with <emph style="bold">file normalize</emph> and then separated into directory and tail components as with <emph style="bold">file dirname</emph> and <emph style="bold">file tail</emph>. Any errors in this process cause the file name to be ignored.</para>
<para>Once the file name is separated into its components, the directory part is checked:</para>
<itemize><item.i><para>If the <emph style="bold">-initialdir</emph> option was supplied, and the directory part of the file name differs from the result of normalizing the <emph style="bold">-initialdir</emph> value, the file name is ignored.</para></item.i><item.i><para>If the <emph style="bold">-initialdir</emph> option was not supplied, and the directory part of the file name designates a directory in the file system, the <emph style="bold">-initialdir</emph> value is set to that directory. Otherwise, (since the file cannot exist), the file name is ignored.</para></item.i><item.i><para>If the given file exists, or if <emph style="bold">tk_getSaveFile was called</emph>, the tail part of the file name is added to a list of files to select within the initial directory.</para></item.i></itemize>
<para>Once <emph style="bold">-initialdir</emph> and <emph style="bold">-initialfile</emph> 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 <emph style="bold">tk_getOpenFile</emph>) are known to exist.</para>
</subsubsection>
</subsection>
</section>
<section title="Reference Implementation">
<para>The reference implementation exists in a patch [<url ref="http://sf.net/tracker/?func=detail&amp;aid=657656&amp;group_id=12997&amp;atid=362997"/>] which also includes new tests for the Tk test suite and updated documentation.</para>
</section>
<section title="Copyright">
<para>This document is in the public domain.</para>
</section>
</body></TIP>
