159 lines
8.5 KiB
HTML
159 lines
8.5 KiB
HTML
<HTML><HEAD><TITLE>Tk Built-In Commands - tk_getOpenFile manual page</TITLE></HEAD><BODY>
|
|
<DL>
|
|
<DD><A HREF="getOpenFile.htm#M2" NAME="L534">NAME</A>
|
|
<DL><DD>tk_getOpenFile, tk_getSaveFile - pop up a dialog box for the user to select a file to open or save.</DL>
|
|
<DD><A HREF="getOpenFile.htm#M3" NAME="L535">SYNOPSIS</A>
|
|
<DL>
|
|
<DD><B>tk_getOpenFile </B>?<I>option value ...</I>?
|
|
<DD><B>tk_getSaveFile </B>?<I>option value ...</I>?
|
|
</DL>
|
|
<DD><A HREF="getOpenFile.htm#M4" NAME="L536">DESCRIPTION</A>
|
|
<DL>
|
|
<DD><A HREF="getOpenFile.htm#M5" NAME="L537"><B>-defaultextension</B> <I>extension</I></A>
|
|
<DD><A HREF="getOpenFile.htm#M6" NAME="L538"><B>-filetypes</B> <I>filePatternList</I></A>
|
|
<DD><A HREF="getOpenFile.htm#M7" NAME="L539"><B>-initialdir</B> <I>directory</I></A>
|
|
<DD><A HREF="getOpenFile.htm#M8" NAME="L540"><B>-initialfile</B> <I>filename</I></A>
|
|
<DD><A HREF="getOpenFile.htm#M9" NAME="L541"><B>-parent</B> <I>window</I></A>
|
|
<DD><A HREF="getOpenFile.htm#M10" NAME="L542"><B>-title</B> <I>titleString</I></A>
|
|
</DL>
|
|
<DD><A HREF="getOpenFile.htm#M11" NAME="L543">SPECIFYING FILE PATTERNS</A>
|
|
<DD><A HREF="getOpenFile.htm#M12" NAME="L544">SPECIFYING EXTENSIONS</A>
|
|
<DD><A HREF="getOpenFile.htm#M13" NAME="L545">EXAMPLE</A>
|
|
<DD><A HREF="getOpenFile.htm#M14" NAME="L546">SEE ALSO</A>
|
|
<DD><A HREF="getOpenFile.htm#M15" NAME="L547">KEYWORDS</A>
|
|
</DL><HR>
|
|
<H3><A NAME="M2">NAME</A></H3>
|
|
tk_getOpenFile, tk_getSaveFile - pop up a dialog box for the user to select a file to open or save.
|
|
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
|
<B>tk_getOpenFile </B>?<I>option value ...</I>?<BR>
|
|
<B>tk_getSaveFile </B>?<I>option value ...</I>?<BR>
|
|
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
|
The procedures <B>tk_getOpenFile</B> and <B>tk_getSaveFile</B> pop up a
|
|
dialog box for the user to select a file to open or save. The
|
|
<B>tk_getOpenFile</B> command is usually associated with the <B><A HREF="../TkCmd/open.htm">Open</A></B>
|
|
command in the <B><A HREF="../TkCmd/file.htm">File</A></B> menu. Its purpose is for the user to select an
|
|
existing file <I>only</I>. If the user enters an non-existent file, the
|
|
dialog box gives the user an error prompt and requires the user to give
|
|
an alternative selection. If an application allows the user to create
|
|
new files, it should do so by providing a separate <B>New</B> menu command.
|
|
<P>
|
|
The <B>tk_getSaveFile</B> command is usually associated with the <B>Save
|
|
as</B> command in the <B><A HREF="../TkCmd/file.htm">File</A></B> menu. If the user enters a file that
|
|
already exists, the dialog box prompts the user for confirmation
|
|
whether the existing file should be overwritten or not.
|
|
<P>
|
|
The following <I>option-value</I> pairs are possible as command line
|
|
arguments to these two commands:
|
|
<P>
|
|
<DL>
|
|
<P><DT><A NAME="M5"><B>-defaultextension</B> <I>extension</I></A><DD>
|
|
Specifies a string that will be appended to the filename if the user
|
|
enters a filename without an extension. The defaut value is the empty
|
|
string, which means no extension will be appended to the filename in
|
|
any case. This option is ignored on the Macintosh platform, which
|
|
does not require extensions to filenames.
|
|
<P><DT><A NAME="M6"><B>-filetypes</B> <I>filePatternList</I></A><DD>
|
|
If a <B><A HREF="../TkCmd/file.htm">File types</A></B> listbox exists in the file dialog on the particular
|
|
platform, this option gives the <I>filetype</I>s in this listbox. When
|
|
the user choose a filetype in the listbox, only the files of that type
|
|
are listed. If this option is unspecified, or if it is set to the
|
|
empty list, or if the <B><A HREF="../TkCmd/file.htm">File types</A></B> listbox is not supported by the
|
|
particular platform then all files are listed regardless of their
|
|
types. See the section SPECIFYING FILE PATTERNS below for a
|
|
discussion on the contents of <I>filePatternList</I>.
|
|
<P><DT><A NAME="M7"><B>-initialdir</B> <I>directory</I></A><DD>
|
|
Specifies that the files in <I>directory</I> should be displayed
|
|
when the dialog pops up. If this parameter is not specified, then
|
|
the files in the current working directory are displayed. If the
|
|
parameter specifies a relative path, the return value will convert the
|
|
relative path to an absolute path. This option may not always work on
|
|
the Macintosh. This is not a bug. Rather, the <I>General Controls</I>
|
|
control panel on the Mac allows the end user to override the
|
|
application default directory.
|
|
<P><DT><A NAME="M8"><B>-initialfile</B> <I>filename</I></A><DD>
|
|
Specifies a filename to be displayed in the dialog when it pops up. This
|
|
option is ignored on the Macintosh platform.
|
|
<P><DT><A NAME="M9"><B>-parent</B> <I>window</I></A><DD>
|
|
Makes <I>window</I> the logical parent of the file dialog. The file
|
|
dialog is displayed on top of its parent window.
|
|
<P><DT><A NAME="M10"><B>-title</B> <I>titleString</I></A><DD>
|
|
Specifies a string to display as the title of the dialog box. If this
|
|
option is not specified, then a default title is displayed.
|
|
<P></DL>
|
|
<P>
|
|
If the user selects a file, both <B>tk_getOpenFile</B> and
|
|
<B>tk_getSaveFile</B> return the full pathname of this file. If the
|
|
user cancels the operation, both commands return the empty string.
|
|
<H3><A NAME="M11">SPECIFYING FILE PATTERNS</A></H3>
|
|
The <I>filePatternList</I> value given by the <B>-filetypes</B> option
|
|
is a list of file patterns. Each file pattern is a list of the
|
|
form
|
|
<PRE><I>typeName</I> {<I>extension</I> ?<I>extension ...</I>?} ?{<I>macType</I> ?<I>macType ...</I>?}?</PRE>
|
|
<I>typeName</I> is the name of the file type described by this
|
|
file pattern and is the text string that appears in the <B><A HREF="../TkCmd/file.htm">File types</A></B>
|
|
listbox. <I>extension</I> is a file extension for this file pattern.
|
|
<I>macType</I> is a four-character Macintosh file type. The list of
|
|
<I>macType</I>s is optional and may be omitted for applications that do
|
|
not need to execute on the Macintosh platform.
|
|
<P>
|
|
Several file patterns may have the same <I>typeName,</I> in which case
|
|
they refer to the same file type and share the same entry in the
|
|
listbox. When the user selects an entry in the listbox, all the files
|
|
that match at least one of the file patterns corresponding
|
|
to that entry are listed. Usually, each file pattern corresponds to a
|
|
distinct type of file. The use of more than one file patterns for one
|
|
type of file is necessary on the Macintosh platform only.
|
|
<P>
|
|
On the Macintosh platform, a file matches a file pattern if its
|
|
name matches at least one of the <I>extension</I>(s) AND it
|
|
belongs to at least one of the <I>macType</I>(s) of the
|
|
file pattern. For example, the <B>C Source Files</B> file pattern in the
|
|
sample code matches with files that have a <B>.c</B> extension AND
|
|
belong to the <I>macType</I> <B><A HREF="../TclCmd/text.htm">TEXT</A></B>. To use the OR rule instead,
|
|
you can use two file patterns, one with the <I>extensions</I> only and
|
|
the other with the <I>macType</I> only. The <B>GIF Files</B> file type
|
|
in the sample code matches files that EITHER have a <B>.gif</B>
|
|
extension OR belong to the <I>macType</I> <B>GIFF</B>.
|
|
<P>
|
|
On the Unix and Windows platforms, a file matches a file pattern
|
|
if its name matches at at least one of the <I>extension</I>(s) of
|
|
the file pattern. The <I>macType</I>s are ignored.
|
|
<H3><A NAME="M12">SPECIFYING EXTENSIONS</A></H3>
|
|
On the Unix and Macintosh platforms, extensions are matched using
|
|
glob-style pattern matching. On the Windows platforms, extensions are
|
|
matched by the underlying operating system. The types of possible
|
|
extensions are: (1) the special extension * matches any
|
|
file; (2) the special extension "" matches any files that
|
|
do not have an extension (i.e., the filename contains no full stop
|
|
character); (3) any character string that does not contain any wild
|
|
card characters (* and ?).
|
|
<P>
|
|
Due to the different pattern matching rules on the various platforms,
|
|
to ensure portability, wild card characters are not allowed in the
|
|
extensions, except as in the special extension *. Extensions
|
|
without a full stop character (e.g, ~) are allowed but may not
|
|
work on all platforms.
|
|
|
|
<H3><A NAME="M13">EXAMPLE</A></H3>
|
|
<PRE>set types {
|
|
{{Text Files} {.txt} }
|
|
{{TCL Scripts} {.tcl} }
|
|
{{C Source Files} {.c} TEXT}
|
|
{{GIF Files} {.gif} }
|
|
{{GIF Files} {} GIFF}
|
|
{{All Files} * }
|
|
}
|
|
set filename [tk_getOpenFile -filetypes $types]
|
|
|
|
if {$filename != ""} {
|
|
# Open the file ...
|
|
}</PRE>
|
|
<H3><A NAME="M14">SEE ALSO</A></H3>
|
|
<B>tk_chooseDirectory</B>
|
|
<H3><A NAME="M15">KEYWORDS</A></H3>
|
|
<A href="../Keywords/F.htm#file selection dialog">file selection dialog</A>
|
|
<HR><PRE>
|
|
<A HREF="../copyright.htm">Copyright</A> © 1996 Sun Microsystems, Inc.
|
|
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
|
</BODY></HTML>
|