/ 
Tk-PathEntry-3.02
River stage zero No dependents
/ Tk::PathEntry

NAME

Tk::PathEntry - Entry widget for selecting paths with completion

SYNOPSIS

    use Tk::PathEntry;
    my $pe = $mw->PathEntry
                     (-textvariable => \$path,
		      -selectcmd => sub { warn "The pathname is $path\n" },
		     )->pack;

DESCRIPTION

This is an alternative to classic file selection dialogs. It works more like the file completion in modern shells like tcsh or 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.

OPTIONS

Tk::PathEntry supports all standard Tk::Entry options except -vcmd and -validate (these are used internally in PathEntry). The additional options are:

-initialdir

Set the initial path to the value. Alias: -initialfile. You can also use a pre-filled -textvariable to set the initial path.

-separator

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 /.

-casesensitive

Set to a true value if the filesystem is case sensitive. For Windows, this is by default false, otherwise true.

-autocomplete

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.

-isdircmd

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.

-choicescmd

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.

-selectcmd

# 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().

-cancelcmd

This subroutine will be called if the Escape key is pressed in the Entry widget. Alias: -cancelcommand.

-messagecmd

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.

-pathcompl

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.

-height

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.

-dircolor

This defines the color for marking directories in the choices listbox. By default directories are not marked.

METHODS

Finish

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.

ADVERTISED SUBWIDGETS

See "Subwidget" in Tk::mega how to use advertised widgets.

ChoicesLabel

The Listbox widget that holds the completion choices.

ChoicesToplevel

The Toplevel widget for the completion choices.

BINDINGS

Bindings of the Entry widget

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:

Down_arrow

Pops up the window with the completion choices and transfers the focus to it.

Return

Calls Finish and invokes the -selectcmd callback.

Escape

Calls Finish and invokes the -cancelcmd callback.

Alt-Backspace or Meta-Backspace

Deletes the path component to the left of the cursor.

Alt-d or Meta-d or Alt-Delete or Meta-Delete

Deletes the path component to the right of the cursor.

Alt-f or Meta-f or Alt-Right_arrow or Meta-Right_arrow

Moves the cursor one path component to the right.

Alt-b or Meta-b or Alt-Left_arrow or Meta-Left_arrow

Moves the cursor one path component to the left.

There is also a user-defined binding, see option -pathcompl.

Bindings of the Listbox widget

The choices listbox of the PathEntry widget uses all bindings of the Listbox widget. In addition there are the following bindings:

Return

Transfers the selected choice to the Entry widget and calls Finish.

Escape

Calls Finish.

Button-1

Transfers the clicked choice to the Entry widget and calls Finish.

EXAMPLES

    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;

NOTES

Since Tk::PathEntry version 2.17, it is not recommended to bind the Return key directly. Use the -selectcmd option instead.

SEE ALSO

Tk::PathEntry::Dialog (3), Tk::Entry (3), tcsh (1), bash (1).

AUTHOR

Slaven Rezic <srezic@cpan.org>, Klaus Wittrock <wittrock@cpan.org>

COPYRIGHT

Copyright (c) 2001,2002,2003,2007,2008 Slaven Rezic. Copyright (c) 2007 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.