summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/Tk/chooseDirectory.pod
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Tk/chooseDirectory.pod')
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/chooseDirectory.pod95
1 files changed, 95 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl/lib/Tk/chooseDirectory.pod b/Master/tlpkg/tlperl/lib/Tk/chooseDirectory.pod
new file mode 100644
index 00000000000..8a2edc9d672
--- /dev/null
+++ b/Master/tlpkg/tlperl/lib/Tk/chooseDirectory.pod
@@ -0,0 +1,95 @@
+# Copyright (c) 1998-2000 by Scriptics Corporation.
+# All rights reserved.
+#
+# RCS: @(#) $Id: chooseDirectory.n,v 1.1 2000/01/27 00:23:10 ericm Exp $
+#
+
+=head1 NAME
+
+chooseDirectory - pops up a dialog box for the user to select a directory.
+
+=for category Tk Generic Methods
+
+=head1 SYNOPSIS
+
+I<$widget>-E<gt>B<chooseDirectory>( ?I<option value ...>? );
+
+=head1 DESCRIPTION
+
+The method B<chooseDirectory> is implemented as a perl wrapper on the
+core tk "command" B<tk_chooseDirectory>, and I<$widget> is passed as
+the argument to the hidden B<-parent> option.
+
+The B<chooseDirectory>
+method pops up a dialog box for the user to select a directory. The
+following I<option-value> pairs are possible as command line
+arguments:
+
+=over 4
+
+=item B<-initialdir> I<dirname>
+
+Specifies that the directories in I<directory> should be displayed
+when the dialog pops up. If this parameter is not specified, then
+the directories 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>
+control panel on the Mac allows the end user to override the
+application default directory.
+
+=item B<-parent> $widget
+
+Makes $widget the logical parent of the dialog. The dialog
+is displayed on top of its parent window.
+
+=item B<-title> I<titleString>
+
+Specifies a string to display as the title of the dialog box. If this
+option is not specified, then a default title will be displayed.
+
+=item B<-mustexist> I<boolean>
+
+Specifies whether the user may specify non-existant directories. If
+this parameter is true, then the user may only select directories that
+already exist. The default value is I<false>.
+
+=back
+
+=head1 CAVEATS
+
+Perl does not have a concept of encoded filesystems yet. This means
+that operations on filenames like C<opendir> and C<open> still use
+byte semantics. Tk however uses character semantics internally, which
+means that you can get filenames with the UTF-8 flag set in functions
+like C<chooseDirectory>, C<getOpenFile> and similar. It's the user's
+responsibility to determine the encoding of the underlying filesystem
+and convert the result into bytes, e.g.
+
+ use Encode;
+ ...
+ my $dir = $mw->chooseDirectory;
+ $dir = encode("windows-1252", $dir);
+ opendir DIR, $dir or die $!;
+ ...
+
+See also L<perlunicode/When Unicode Does Not Happen> and
+L<perltodo/Unicode in Filenames>.
+
+=head1 EXAMPLE
+
+ my $dir = $mw->chooseDirectory(-initialdir => '~',
+ -title => 'Choose a directory');
+ if (!defined $dir) {
+ warn 'No directory selected';
+ } else {
+ warn "Selected $dir";
+ }
+
+=head1 SEE ALSO
+
+L<Tk::getOpenFile>, L<Tk::getOpenFile>
+
+=head1 KEYWORDS
+
+directory selection dialog