diff options
author | Siep Kroonenberg <siepo@cybercomm.nl> | 2011-02-17 15:05:13 +0000 |
---|---|---|
committer | Siep Kroonenberg <siepo@cybercomm.nl> | 2011-02-17 15:05:13 +0000 |
commit | 9fc19ef8e2dcd8bcf6a1d034b95c1de2b88e485c (patch) | |
tree | ee28de37fe0de6137d535fee2e64ecafaffefb91 /Master/tlpkg/tlperl/lib/Tk/getOpenFile.pod | |
parent | 73b942cfb4ccf168f9c2b7f20a289b06f1f54a4b (diff) |
New tlperl part II
git-svn-id: svn://tug.org/texlive/trunk@21424 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Tk/getOpenFile.pod')
-rw-r--r-- | Master/tlpkg/tlperl/lib/Tk/getOpenFile.pod | 182 |
1 files changed, 182 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl/lib/Tk/getOpenFile.pod b/Master/tlpkg/tlperl/lib/Tk/getOpenFile.pod new file mode 100644 index 00000000000..56d39422afd --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/getOpenFile.pod @@ -0,0 +1,182 @@ +# 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 + |