Tk::PathEntry - Entry widget for selecting paths with completion
use Tk::PathEntry; my $pe = $mw->PathEntry (-textvariable => \$path, -selectcmd => sub { warn "The pathname is $path\n" }, )->pack;
This is an alternative to classic file selection dialogs. It works more like the file completion in modern shells like tcsh or bash.
tcsh
bash
With the Tab key, you can force the completion of the current path. If there are more choices, a window is popping up with these choices. With the Meta-Backspace or Alt-Backspace key, the last path component will be deleted.
Tab
Meta-Backspace
Alt-Backspace
Tk::PathEntry supports all standard Tk::Entry options except -vcmd and -validate (these are used internally in PathEntry). The additional options are:
-vcmd
-validate
Set the initial path to the value. Alias: -initialfile. You can also use a pre-filled -textvariable to set the initial path.
-initialfile
-textvariable
The character used as the path component separator. This may be also an array reference for multiple characters. For Windows, this is by default the characters / and \, otherwise just /.
/
\
Set to a true value if the filesystem is case sensitive. For Windows, this is by default false, otherwise true.
If this is set to a true value, and there remains only one item in the choices listbox, it will be transferred to the Entry widget automatically.
true
Can be used to set another directory recognizing subroutine. Alias: -isdirectorycommand. The directory name is passed as second parameter. The default is a subroutine using -d.
-isdirectorycommand
-d
Can be used to set another globbing subroutine. Alias: -choicescommand. The current pathname is passed as second parameter. The default is a subroutine using the standard glob function.
-choicescommand
glob
# For Windows OS, find out the encoding of perl's console window Return key in the Entry widget. Alias: -selectcommand. The encoded path name is passed as second parameter, ready for use in file operations. You may access the path name as a utf8-string via your -textvariable or with $pe->get().
-selectcommand
$pe->get()
This subroutine will be called if the Escape key is pressed in the Entry widget. Alias: -cancelcommand.
-cancelcommand
Can be used to set a different subroutine for displaying messages. Alias: -messagecommand. The message is passed as the second parameter. Examples are -messagecmd => sub {print "$_[1]\n"}, -messagecmd => sub {$_[0]->bell}, or even -messagecmd => undef. The default is a subroutine using messageBox.
-messagecommand
-messagecmd => sub {print "$_[1]\n"}
-messagecmd => sub {$_[0]->bell}
-messagecmd => undef
messageBox
This defines the event that will force the completion of the current path. Alias: -pathcompletion. By default the Tab key will be used. Note: This default conflicts with the standard use of the Tab key to move the focus to the next widget.
-pathcompletion
This sets the height of the choices listbox. The default is 10 lines. If height is negative, the displayed height changes dynamically, and the absolute value gives the maximum displayed height. If height is zero, there is no maximum.
This defines the color for marking directories in the choices listbox. By default directories are not marked.
This will popdown the window with the completion choices. It is called automatically if the user selects an entry from the listbox, hits the Return or Escape key or the widget loses the focus.
See "Subwidget" in Tk::mega how to use advertised widgets.
The Listbox widget that holds the completion choices.
The Toplevel widget for the completion choices.
The PathEntry widget has the same bindings as the Entry widget, exept for FocusOut, which is used internally. In addition there are the following bindings:
FocusOut
Pops up the window with the completion choices and transfers the focus to it.
Calls Finish and invokes the -selectcmd callback.
Finish
-selectcmd
Calls Finish and invokes the -cancelcmd callback.
-cancelcmd
Deletes the path component to the left of the cursor.
Deletes the path component to the right of the cursor.
Moves the cursor one path component to the right.
Moves the cursor one path component to the left.
There is also a user-defined binding, see option -pathcompl.
-pathcompl
The choices listbox of the PathEntry widget uses all bindings of the Listbox widget. In addition there are the following bindings:
Transfers the selected choice to the Entry widget and calls Finish.
Calls Finish.
Transfers the clicked choice to the Entry widget and calls Finish.
use Tk::PathEntry; my $pe = $mw->PathEntry (-autocomplete => 1, -pathcompletion => '<F5>', -selectcmd => sub {my $f = $_[1]; open(OUT, '>', $f) || die "cannot open file $f\n"; }, )->pack(-fill => 'x', -expand => 1);
If you want to not require from your users to install Tk::PathEntry, you can use the following code snippet to create either a PathEntry or an Entry, depending on what is installed:
my $e; if (!eval ' use Tk::PathEntry; $e = $mw->PathEntry(-textvariable => \$file, -selectcmd => sub { $e->Finish }, ); 1; ') { $e = $mw->Entry(-textvariable => \$file); } $e->pack;
Since Tk::PathEntry version 2.17, it is not recommended to bind the Return key directly. Use the -selectcmd option instead.
Tk::PathEntry
Tk::PathEntry::Dialog (3), Tk::Entry (3), tcsh (1), bash (1).
Slaven Rezic <srezic@cpan.org>, Klaus Wittrock <wittrock@cpan.org>
Copyright (c) 2001,2002,2003,2007,2008,2009,2017,2018 Slaven Rezic. Copyright (c) 2007,2009 Klaus Wittrock. All rights reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install Tk::PathEntry, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Tk::PathEntry
CPAN shell
perl -MCPAN -e shell install Tk::PathEntry
For more information on module installation, please visit the detailed CPAN module installation guide.