diff options
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Tk/getOpenFile.pod')
-rw-r--r-- | Master/tlpkg/tlperl/lib/Tk/getOpenFile.pod | 182 |
1 files changed, 0 insertions, 182 deletions
diff --git a/Master/tlpkg/tlperl/lib/Tk/getOpenFile.pod b/Master/tlpkg/tlperl/lib/Tk/getOpenFile.pod deleted file mode 100644 index 56d39422afd..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/getOpenFile.pod +++ /dev/null @@ -1,182 +0,0 @@ -# Copyright (c) 1996 Sun Microsystems, Inc. -# See the file "license.terms" for information on usage and redistribution -# of this file, and for a DISCLAIMER OF ALL WARRANTIES. - -=head1 NAME - -getOpenFile, getSaveFile - pop up a dialog box for the user to select a file to open or save. - -=for category Popups and Dialogs - -=head1 SYNOPSIS - -S< >I<$widget>-E<gt>B<getOpenFile>(?I<-option>=E<gt>value, ...>?) - -S< >I<$widget>-E<gt>B<getSaveFile>(?I<-option>=E<gt>value, ...>?) - -=head1 DESCRIPTION - -The methods B<getOpenFile> and B<getSaveFile> pop up a -dialog box for the user to select a file to open or save. - -The B<getOpenFile> method is usually associated with the B<Open> -command in the B<File> menu. Its purpose is for the user to select an -existing file I<only>. 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> menu command. - -The B<getSaveFile> method is usually associated with the B<Save> -as command in the B<File> 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. - -If the user selects a file, both B<getOpenFile> and -B<getSaveFile> return the full pathname of this file. If the -user cancels the operation, both commands return an undefined value. - -The following I<option-value> pairs are possible as command line -arguments to these two commands: - -=over 4 - -=item B<-defaultextension> =E<gt> I<extension> - -Specifies a string that will be appended to the filename if the user -enters a filename without an extension. The default 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, and the UNIX implementation -guesses reasonable values for this from the B<-filetypes> -option when this is not supplied. - -=item B<-filetypes> =E<gt> [I<filePattern> ?, ...?] - -If a B<File types> listbox exists in the file dialog on the particular -platform, this option gives the I<filetype>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<File types> listbox is not supported by the -particular platform then all files are listed regardless of their -types. See L<"SPECIFYING FILE PATTERNS"> below for a -discussion on the contents of I<filePattern>s. - -=item B<-initialdir> =E<gt> I<directory> - -Specifies that the files in I<directory> should be displayed -when the dialog pops up. If this parameter is not specified, then -the files in the current working directory are displayed. This -option may not always work on the Macintosh. This is not a bug. -Rather, the I<General Controls> control panel on the Mac allows the -end user to override the application default directory. - -=item B<-initialfile> =E<gt> I<filename> - -Specifies a filename to be displayed in the dialog when it pops -up. This option is ignored by the B<getOpenFile> method. - -=item B<-multiple> - -Allows the user to choose multiple files from the Open dialog. On the -Macintosh, this is only available when Navigation Services are -installed. - -=item B<-message> =E<gt> I<string> - -Specifies a message to include in the client area of the dialog. This -is only available on the Macintosh, and only when Navigation Services -are installed. - -=item B<-title> =E<gt> I<titleString> - -Specifies a string to display as the title of the dialog box. If this -option is not specified, then a default title is displayed. This -option is ignored on the Macintosh platform. - -=back - -=head1 SPECIFYING FILE PATTERNS - -The I<filePattern>s given by the B<-filetypes> option -are a list of file patterns. Each file pattern is a list of the -form - - typeName [extension ?extension ...?] ?[macType ?macType ...?]? - -I<typeName> is the name of the file type described by this -file pattern and is the text string that appears in the B<File types> -listbox. I<extension> is a file extension for this file pattern. -I<macType> is a four-character Macintosh file type. The list of -I<macType>s is optional and may be omitted for applications that do -not need to execute on the Macintosh platform. - -Several file patterns may have the same I<typeName,> 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. - -On the Macintosh platform, a file matches a file pattern if its -name matches at least one of the I<extension>(s) AND it -belongs to at least one of the I<macType>(s) of the -file pattern. For example, the B<C Source Files> file pattern in the -sample code matches with files that have a B<\.c> extension AND -belong to the I<macType> B<TEXT>. To use the OR rule instead, -you can use two file patterns, one with the I<extensions> only and -the other with the I<macType> only. The B<GIF Files> file type -in the sample code matches files that EITHER have a B<\.gif> -extension OR belong to the I<macType> B<GIFF>. - -On the Unix and Windows platforms, a file matches a file pattern -if its name matches at at least one of the I<extension>(s) of -the file pattern. The I<macType>s are ignored. - -=head1 SPECIFYING EXTENSIONS - -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 ?). - -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. - -=head1 CAVEATS - -See L<Tk::chooseDirectory/CAVEATS>. - -=head1 EXAMPLE - - my $types = [ - ['Text Files', ['.txt', '.text']], - ['TCL Scripts', '.tcl' ], - ['C Source Files', '.c', 'TEXT'], - ['GIF Files', '.gif', ], - ['GIF Files', '', 'GIFF'], - ['All Files', '*', ], - ]; - my $filename = $widget->getOpenFile(-filetypes=>$types); - - if ($filename ne "") { - # Open the file ... - } - -=head1 SEE ALSO - -L<Tk::FBox|Tk::FBox>, L<Tk::FileSelect|Tk::FileSelect> - -=head1 KEYWORDS - -file selection dialog - -=cut - |