1tk_getOpenFile(n)            Tk Built-In Commands            tk_getOpenFile(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       tk_getOpenFile,  tk_getSaveFile  -  pop up a dialog box for the user to
9       select a file to open or save.
10

SYNOPSIS

12       tk_getOpenFile ?option value ...?
13       tk_getSaveFile ?option value ...?
14______________________________________________________________________________
15

DESCRIPTION

17       The procedures tk_getOpenFile and tk_getSaveFile pop up  a  dialog  box
18       for  the user to select a file to open or save. The tk_getOpenFile com‐
19       mand is usually associated with the Open command in the File menu.  Its
20       purpose  is  for  the user to select an existing file only. If the user
21       enters a non-existent file, the dialog box  gives  the  user  an  error
22       prompt  and  requires  the user to give an alternative selection. If an
23       application allows the user to create new files, it  should  do  so  by
24       providing a separate New menu command.
25
26       The  tk_getSaveFile command is usually associated with the Save as com‐
27       mand in the File menu. If the user enters a file that  already  exists,
28       the  dialog  box prompts the user for confirmation whether the existing
29       file should be overwritten or not.
30
31       The following option-value pairs are possible as command line arguments
32       to these two commands:
33
34       -confirmoverwrite boolean
35              Configures  how  the  Save  dialog reacts when the selected file
36              already exists, and saving would overwrite  it.   A  true  value
37              requests  a  confirmation  dialog  be  presented to the user.  A
38              false value requests that the overwrite take place without  con‐
39              firmation.  Default value is true.
40
41       -defaultextension extension
42              Specifies  a string that will be appended to the filename if the
43              user enters a filename without an extension. The  default  value
44              is  the  empty string, which means no extension will be appended
45              to the filename in any case. This option is ignored on Mac OS X,
46              which  does  not  require  extensions to filenames, and the UNIX
47              implementation guesses  reasonable  values  for  this  from  the
48              -filetypes option when this is not supplied.
49
50       -filetypes filePatternList
51              If a File types listbox exists in the file dialog on the partic‐
52              ular platform, this option gives the filetypes in this  listbox.
53              When  the  user choose a filetype in the listbox, only the files
54              of that type are listed. If this option is unspecified, or if it
55              is  set  to  the empty list, or if the File types listbox is not
56              supported by the particular platform then all files  are  listed
57              regardless  of their types. See the section SPECIFYING FILE PAT‐
58              TERNS below for a discussion on the contents of filePatternList.
59
60       -initialdir directory
61              Specifies that the files in directory should be  displayed  when
62              the dialog pops up. If this parameter is not specified, the ini‐
63              tial directory defaults to the current working directory on non-
64              Windows systems and on Windows systems prior to Vista.  On Vista
65              and later systems, the initial directory defaults  to  the  last
66              user-selected  directory  for  the application. If the parameter
67              specifies a relative path, the return  value  will  convert  the
68              relative path to an absolute path.
69
70       -initialfile filename
71              Specifies  a filename to be displayed in the dialog when it pops
72              up.
73
74       -message string
75              Specifies a message to include in the client area of the dialog.
76              This is only available on Mac OS X.
77
78       -multiple boolean
79              Allows the user to choose multiple files from the Open dialog.
80
81       -parent window
82              Makes  window  the  logical  parent of the file dialog. The file
83              dialog is displayed on top of its parent window. On  Mac  OS  X,
84              this  turns  the file dialog into a sheet attached to the parent
85              window.
86
87       -title titleString
88              Specifies a string to display as the title of the dialog box. If
89              this option is not specified, then a default title is displayed.
90
91       -typevariable variableName
92              The global variable variableName is used to preselect which fil‐
93              ter is used from filterList when the dialog box is opened and is
94              updated when the dialog box is closed, to the last selected fil‐
95              ter. The variable is read once at the beginning  to  select  the
96              appropriate filter. If the variable does not exist, or its value
97              does not match any filter typename, or is empty ({}), the dialog
98              box  will  revert to the default behavior of selecting the first
99              filter in the list. If the dialog is canceled, the  variable  is
100              not modified.
101
102       If  the  user  selects  a  file, both tk_getOpenFile and tk_getSaveFile
103       return the full pathname of this file. If the user cancels  the  opera‐
104       tion, both commands return the empty string.
105

SPECIFYING FILE PATTERNS

107       The  filePatternList  value given by the -filetypes option is a list of
108       file patterns. Each file pattern is a list of the form
109              typeName {extension ?extension ...?} ?{macType ?macType ...?}?
110       typeName is the name of the file type described by  this  file  pattern
111       and  is  the text string that appears in the File types listbox. exten‐
112       sion is a file extension for this file pattern.   macType  is  a  four-
113       character Macintosh file type. The list of macTypes is optional and may
114       be omitted for applications that do not need to execute on  the  Macin‐
115       tosh platform.
116
117       Several  file  patterns  may have the same typeName, in which case they
118       refer to the same file type and share the same entry  in  the  listbox.
119       When the user selects an entry in the listbox, all the files that match
120       at least one of the file  patterns  corresponding  to  that  entry  are
121       listed.  Usually,  each  file pattern corresponds to a distinct type of
122       file. The use of more than one file pattern for one  type  of  file  is
123       only necessary on the Macintosh platform.
124
125       On  the  Macintosh  platform, a file matches a file pattern if its name
126       matches at least one of the extension(s) AND it belongs to at least one
127       of  the macType(s) of the file pattern. For example, the C Source Files
128       file pattern in the sample code matches  with  files  that  have  a  .c
129       extension  AND  belong to the macType TEXT. To use the OR rule instead,
130       you can use two file patterns, one with the  extensions  only  and  the
131       other with the macType only. The GIF Files file type in the sample code
132       matches files that either have a .gif extension OR belong to  the  mac‐
133       Type GIFF.
134
135       On the Unix and Windows platforms, a file matches a file pattern if its
136       name matches at least one of the extension(s) of the file pattern.  The
137       macTypes are ignored.
138

SPECIFYING EXTENSIONS

140       On the Unix and Macintosh platforms, extensions are matched using glob-
141       style pattern matching. On the Windows platform, extensions are matched
142       by  the  underlying  operating system. The types of possible extensions
143       are:
144
145       (1)    the special extension “*” matches any file;
146
147       (2)    the special extension “” matches any files that do not  have  an
148              extension (i.e., the filename contains no full stop character);
149
150       (3)    any character string that does not contain any wild card charac‐
151              ters (* and ?).
152
153       Due to the different pattern matching rules on the  various  platforms,
154       to  ensure  portability,  wild  card  characters are not allowed in the
155       extensions, except as in the special extension “*”.  Extensions without
156       a  full  stop character (e.g.  “~”) are allowed but may not work on all
157       platforms.
158

EXAMPLE

160              set types {
161                  {{Text Files}       {.txt}        }
162                  {{TCL Scripts}      {.tcl}        }
163                  {{C Source Files}   {.c}      TEXT}
164                  {{GIF Files}        {.gif}        }
165                  {{GIF Files}        {}        GIFF}
166                  {{All Files}        *             }
167              }
168              set filename [tk_getOpenFile -filetypes $types]
169
170              if {$filename ne ""} {
171                  # Open the file ...
172              }
173

SEE ALSO

175       tk_chooseDirectory
176

KEYWORDS

178       file selection dialog
179
180
181
182Tk                                    4.2                    tk_getOpenFile(n)
Impressum