NAME

UI::Various::Compound::FileSelect - general file selection widget of UI::Various

SYNOPSIS

    use UI::Various;
    my $main = UI::Various::Main->new(height => 20, width => 60);
    my $fs =
        UI::Various::Compound::FileSelect->new(
            mode => 2,
            directory => $ENV{HOME},
            filter => [['all files' => '.'], ['Perl scripts' => '\.pl$']],
            height => 12,
            width => 20);
    my $dialog = $main->dialog({title => 'select input files'}, $fs);
    ...
    $main->mainloop();
    print join("\n", $fs->selection(), '');

ABSTRACT

This module defines a specialised compound UI::Various widget for selecting one or more files for input or one file for output.

DESCRIPTION

The Compound::FileSelect widget creates and returns a compound Box widget containing everything needed to select a file. This widget can be simply put into a dialog as in the example in the SYNOPSIS or put into another Box to combine it with something else. All directory operations are handled internally.

Note that the given width and height are the values for the internal Listbox widget. The FileSelect widget is notably higher than that. Besides those common attributes inherited from UI::Various::widget the Compound::FileSelect widget knows the following additional attributes:

Attributes

directory [rw, fixed, optional]

the initial working directory of the file selector as string or variable reference defaulting to the current directory of the application (during creation of the widget)

Note that though this attribute may not be changed from outside after initialisation, it is always changed internally to the directory currently displayed in the file selection widget.

filter [rw, fixed, optional]

a list of filters that can be applied to the files listed (as Optionmenu)

The list of filters must be an ARRAY of pairs (reference to an ARRAY with two elements each). The first entry of a pair is the entry shown in the selection and the second one must be a regular expression used to filter the files to be displayed. (We don't use a glob as a regular expression allows much more flexibility.)

Note that directories are always displayed to allow traversing the file system.

mode [rw, fixed]

the mandatory file selection mode of the file selector:

0

the file selector is used to select or enter a file name for an output file (which may not yet exist)

1

the file selector is used to select one input file

2

the file selector is used to select one or more input files (using a Optionmenu with multiple selection)

symlinks [rw, fixed]

an optional flag if symbolic links can be selected or not:

0

Symbolic links are automatically followed (replaced with their target). This is the default.

1

Symbolic links are kept as they are. This allows selecting them instead of their target.

METHODS

Besides the accessors (attributes) described above and the attributes and methods of UI::Various::widget, UI::Various::container and UI::Various::Box, the following additional methods are provided by the FileSelect class itself:

new - constructor

see UI::Various::core::construct

_cd - get list of files for directory

This internal method returns the list of sub-directories and files according to the current configuration. An optional parameter changes the current directory prior to that.

selection - get current selection of file selection widget

    $selection = $listbox->selection();  # C<mode =E<gt> 0 or 1>
    @selection = $listbox->selection();  # C<mode =E<gt> 2>

description:

This method returns the full path(s) to the file(s) selected or entered (in case of mode => 0) in the file selection widget. If there is nothing selected at all, the method returns the current directory with a trailing /. (A directory selected after a regular file in mode => 2 has no trailing /.)

returns:

selected/entered element(s)

SEE ALSO

UI::Various

LICENSE

Copyright (C) Thomas Dorner.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See LICENSE file for more details.

AUTHOR

Thomas Dorner <dorner (at) cpan (dot) org>