Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | # Copyright (c) 1996 Sun Microsystems, Inc. |
2 | # See the file "license.terms" for information on usage and redistribution | |
3 | # of this file, and for a DISCLAIMER OF ALL WARRANTIES. | |
4 | ||
5 | =head1 NAME | |
6 | ||
7 | getOpenFile, getSaveFile - pop up a dialog box for the user to select a file to open or save. | |
8 | ||
9 | =for category Popups and Dialogs | |
10 | ||
11 | =head1 SYNOPSIS | |
12 | ||
13 | S< >I<$widget>-E<gt>B<getOpenFile>(?I<-option>=E<gt>value, ...>?) | |
14 | ||
15 | S< >I<$widget>-E<gt>B<getSaveFile>(?I<-option>=E<gt>value, ...>?) | |
16 | ||
17 | =head1 DESCRIPTION | |
18 | ||
19 | The methods B<getOpenFile> and B<getSaveFile> pop up a | |
20 | dialog box for the user to select a file to open or save. | |
21 | ||
22 | The B<getOpenFile> method is usually associated with the B<Open> | |
23 | command in the B<File> menu. Its purpose is for the user to select an | |
24 | existing file I<only>. If the user enters an non-existent file, the | |
25 | dialog box gives the user an error prompt and requires the user to give | |
26 | an alternative selection. If an application allows the user to create | |
27 | new files, it should do so by providing a separate B<New> menu command. | |
28 | ||
29 | The B<getSaveFile> method is usually associated with the B<Save> | |
30 | as command in the B<File> menu. If the user enters a file that | |
31 | already exists, the dialog box prompts the user for confirmation | |
32 | whether the existing file should be overwritten or not. | |
33 | ||
34 | If the user selects a file, both B<getOpenFile> and | |
35 | B<getSaveFile> return the full pathname of this file. If the | |
36 | user cancels the operation, both commands return an undefined value. | |
37 | ||
38 | The following I<option-value> pairs are possible as command line | |
39 | arguments to these two commands: | |
40 | ||
41 | =over 4 | |
42 | ||
43 | =item B<-defaultextension> =E<gt> I<extension> | |
44 | ||
45 | Specifies a string that will be appended to the filename if the user | |
46 | enters a filename without an extension. The default value is the empty | |
47 | string, which means no extension will be appended to the filename in | |
48 | any case. This option is ignored on the Macintosh platform, which | |
49 | does not require extensions to filenames. | |
50 | ||
51 | =item B<-filetypes> =E<gt> [I<filePattern> ?, ...?] | |
52 | ||
53 | If a B<File types> listbox exists in the file dialog on the particular | |
54 | platform, this option gives the I<filetype>s in this listbox. When | |
55 | the user choose a filetype in the listbox, only the files of that type | |
56 | are listed. If this option is unspecified, or if it is set to the | |
57 | empty list, or if the B<File types> listbox is not supported by the | |
58 | particular platform then all files are listed regardless of their | |
59 | types. See L<"SPECIFYING FILE PATTERNS"> below for a | |
60 | discussion on the contents of I<filePattern>s. | |
61 | ||
62 | =item B<-initialdir> =E<gt> I<directory> | |
63 | ||
64 | Specifies that the files in I<directory> should be displayed | |
65 | when the dialog pops up. If this parameter is not specified, then | |
66 | the files in the current working directory are displayed. This | |
67 | option may not always work on the Macintosh. This is not a bug. | |
68 | Rather, the I<General Controls> control panel on the Mac allows the | |
69 | end user to override the application default directory. | |
70 | ||
71 | =item B<-initialfile> =E<gt> I<filename> | |
72 | ||
73 | Specifies a filename to be displayed in the dialog when it pops | |
74 | up. This option is ignored by the B<getOpenFile> method. | |
75 | ||
76 | =item B<-title> =E<gt> I<titleString> | |
77 | ||
78 | Specifies a string to display as the title of the dialog box. If this | |
79 | option is not specified, then a default title is displayed. This | |
80 | option is ignored on the Macintosh platform. | |
81 | ||
82 | =back | |
83 | ||
84 | =head1 SPECIFYING FILE PATTERNS | |
85 | ||
86 | The I<filePattern>s given by the B<-filetypes> option | |
87 | are a list of file patterns. Each file pattern is a list of the | |
88 | form | |
89 | ||
90 | typeName [extension ?extension ...?] ?[macType ?macType ...?]? | |
91 | ||
92 | I<typeName> is the name of the file type described by this | |
93 | file pattern and is the text string that appears in the B<File types> | |
94 | listbox. I<extension> is a file extension for this file pattern. | |
95 | I<macType> is a four-character Macintosh file type. The list of | |
96 | I<macType>s is optional and may be omitted for applications that do | |
97 | not need to execute on the Macintosh platform. | |
98 | ||
99 | Several file patterns may have the same I<typeName,> in which case | |
100 | they refer to the same file type and share the same entry in the | |
101 | listbox. When the user selects an entry in the listbox, all the files | |
102 | that match at least one of the file patterns corresponding | |
103 | to that entry are listed. Usually, each file pattern corresponds to a | |
104 | distinct type of file. The use of more than one file patterns for one | |
105 | type of file is necessary on the Macintosh platform only. | |
106 | ||
107 | On the Macintosh platform, a file matches a file pattern if its | |
108 | name matches at least one of the I<extension>(s) AND it | |
109 | belongs to at least one of the I<macType>(s) of the | |
110 | file pattern. For example, the B<C Source Files> file pattern in the | |
111 | sample code matches with files that have a B<\.c> extension AND | |
112 | belong to the I<macType> B<TEXT>. To use the OR rule instead, | |
113 | you can use two file patterns, one with the I<extensions> only and | |
114 | the other with the I<macType> only. The B<GIF Files> file type | |
115 | in the sample code matches files that EITHER have a B<\.gif> | |
116 | extension OR belong to the I<macType> B<GIFF>. | |
117 | ||
118 | On the Unix and Windows platforms, a file matches a file pattern | |
119 | if its name matches at at least one of the I<extension>(s) of | |
120 | the file pattern. The I<macType>s are ignored. | |
121 | ||
122 | =head1 SPECIFYING EXTENSIONS | |
123 | ||
124 | On the Unix and Macintosh platforms, extensions are matched using | |
125 | glob-style pattern matching. On the Windows platforms, extensions are | |
126 | matched by the underlying operating system. The types of possible | |
127 | extensions are: (1) the special extension * matches any | |
128 | file; (2) the special extension "" matches any files that | |
129 | do not have an extension (i.e., the filename contains no full stop | |
130 | character); (3) any character string that does not contain any wild | |
131 | card characters (* and ?). | |
132 | ||
133 | Due to the different pattern matching rules on the various platforms, | |
134 | to ensure portability, wild card characters are not allowed in the | |
135 | extensions, except as in the special extension *. Extensions | |
136 | without a full stop character (e.g, ~) are allowed but may not | |
137 | work on all platforms. | |
138 | ||
139 | =head1 EXAMPLE | |
140 | ||
141 | my $types = [ | |
142 | ['Text Files', ['.txt', '.text']], | |
143 | ['TCL Scripts', '.tcl' ], | |
144 | ['C Source Files', '.c', 'TEXT'], | |
145 | ['GIF Files', '.gif', ], | |
146 | ['GIF Files', '', 'GIFF'], | |
147 | ['All Files', '*', ], | |
148 | ]; | |
149 | my $filename = $widget->getOpenFile(-filetypes=>$types); | |
150 | ||
151 | if ($filename ne "") { | |
152 | # Open the file ... | |
153 | } | |
154 | ||
155 | =head1 SEE ALSO | |
156 | ||
157 | L<Tk::FBox|Tk::FBox>, L<Tk::FileSelect|Tk::FileSelect> | |
158 | ||
159 | =head1 KEYWORDS | |
160 | ||
161 | file selection dialog | |
162 | ||
163 | =cut | |
164 |