.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Prima::FileDialog 3"
.TH Prima::FileDialog 3 "2009-02-24" "perl v5.20.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Prima::FileDialog \- File system related widgets and dialogs.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
# open a file
	use Prima qw(Application);
	use Prima::StdDlg;
.PP
.Vb 7
\&        my $open = Prima::OpenDialog\-> new(
\&                filter => [
\&                        [\*(AqPerl modules\*(Aq => \*(Aq*.pm\*(Aq],
\&                        [\*(AqAll\*(Aq => \*(Aq*\*(Aq]
\&                ]
\&        );
\&        print $open\-> fileName, " is to be opened\en" if $open\-> execute;
\&
\&        # save a file
\&        my $save = Prima::SaveDialog\-> new(
\&                fileName => $open\-> fileName,
\&        );
\&        print $save\-> fileName, " is to be saved\en" if $save\-> execute;
\&
\&        # open several files
\&        $open\-> multiSelect(1);
\&        print $open\-> fileName, " are to be opened\en" if $open\-> execute;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The module contains widgets for file and drive selection,
and also standard open file, save file, and change directory 
dialogs.
.SH "Prima::DirectoryListBox"
.IX Header "Prima::DirectoryListBox"
A directory listing list box. Shows the list of 
subdirectories and upper directories, hierarchy-mapped,
with the folder images and outlines.
.SS "Properties"
.IX Subsection "Properties"
.IP "closedGlyphs \s-1INTEGER\s0" 4
.IX Item "closedGlyphs INTEGER"
Number of horizontal equal-width images, contained in closedIcon
property.
.Sp
Default value: 1
.IP "closedIcon \s-1ICON\s0" 4
.IX Item "closedIcon ICON"
Provides an icon representation 
for the directories, contained in the current directory.
.IP "indent \s-1INTEGER\s0" 4
.IX Item "indent INTEGER"
A positive integer number of pixels, used for offset of
the hierarchy outline.
.Sp
Default value: 12
.IP "openedGlyphs \s-1INTEGER\s0" 4
.IX Item "openedGlyphs INTEGER"
Number of horizontal equal-width images, contained in openedIcon
property.
.Sp
Default value: 1
.IP "openedIcon \s-1OBJECT\s0" 4
.IX Item "openedIcon OBJECT"
Provides an icon representation 
for the directories, contained in the directories above the current
directory.
.IP "path \s-1STRING\s0" 4
.IX Item "path STRING"
Runtime-only property. Selects a file system path.
.IP "showDotDirs \s-1BOOLEAN\s0" 4
.IX Item "showDotDirs BOOLEAN"
Selects if the directories with the first dot character
are shown the view. The treatment of the dot-prefixed names
as hidden is traditional to unix, and is of doubtful use under
win32 and os2.
.Sp
Default value: 1
.SS "Methods"
.IX Subsection "Methods"
.IP "files [ \s-1FILE_TYPE \s0]" 4
.IX Item "files [ FILE_TYPE ]"
If \s-1FILE_TYPE\s0 value is not specified, the list of all files in the
current directory is returned. If \s-1FILE_TYPE\s0 is given, only the files
of the types are returned. The \s-1FILE_TYPE\s0 is a string, one of those
returned by \f(CW\*(C`Prima::Utils::getdir\*(C'\fR ( see \*(L"getdir\*(R" in Prima::Utils.
.SH "Prima::DriveComboBox"
.IX Header "Prima::DriveComboBox"
Provides drive selection combo-box for non-unix systems.
.SS "Properties"
.IX Subsection "Properties"
.IP "firstDrive \s-1DRIVE_LETTER \s0" 4
.IX Item "firstDrive DRIVE_LETTER "
Create-only property.
.Sp
Default value: 'A:'
.Sp
\&\s-1DRIVE_LETTER\s0 can be set to other value to start the drive enumeration from.
Some OSes can probe eventual diskette drives inside the drive enumeration
routines, so it might be reasonable to set \s-1DRIVE_LETTER\s0 to \f(CW\*(C`C:\*(C'\fR string
for responsiveness increase.
.IP "drive \s-1DRIVE_LETTER\s0" 4
.IX Item "drive DRIVE_LETTER"
Selects the drive letter.
.Sp
Default value: 'C:'
.SH "Prima::FileDialog"
.IX Header "Prima::FileDialog"
Provides a standard file dialog, allowing to navigate by the
file system and select one or many files. The class can
operate in two modes \- 'open' and 'save'; these modes are
set by Prima::OpenDialog and Prima::SaveDialog.
Some properties behave differently depending on the mode,
which is stored in openMode property.
.SS "Properties"
.IX Subsection "Properties"
.IP "createPrompt \s-1BOOLEAN\s0" 4
.IX Item "createPrompt BOOLEAN"
If 1, and a file selected is nonexistent, asks the user
if the file is to be created.
.Sp
Only actual when openMode is 1.
.Sp
Default value: 0
.IP "defaultExt \s-1STRING\s0" 4
.IX Item "defaultExt STRING"
Selects the file extension, appended to the 
file name typed by the user, if the extension is not given.
.Sp
Default value: ''
.IP "directory \s-1STRING\s0" 4
.IX Item "directory STRING"
Selects the currently selected directory.
.IP "fileMustExist \s-1BOOLEAN\s0" 4
.IX Item "fileMustExist BOOLEAN"
If 1, ensures that the file typed by the user exists before
closing the dialog.
.Sp
Default value: 1
.IP "fileName \s-1STRING, ...\s0" 4
.IX Item "fileName STRING, ..."
For single-file selection, assigns the selected file name,
For multiple-file selection, on get-call returns list of the selected
files; on set-call, accepts a single string, where the file names
are separated by the space character. The eventual space characters
must be quoted.
.IP "filter \s-1ARRAY\s0" 4
.IX Item "filter ARRAY"
Contains array of arrays of string pairs, where each pair describes
a file type. The first scalar in the pair is the description of
the type; the second is a file mask.
.Sp
Default value: [[ 'All files' => '*']]
.IP "filterIndex \s-1INTEGER\s0" 4
.IX Item "filterIndex INTEGER"
Selects the index in filter array of the currently selected file type.
.IP "multiSelect \s-1BOOLEAN\s0" 4
.IX Item "multiSelect BOOLEAN"
Selects whether the user can select several ( 1 ) or one ( 0 ) file.
.Sp
See also: fileName.
.IP "noReadOnly \s-1BOOLEAN\s0" 4
.IX Item "noReadOnly BOOLEAN"
If 1, fails to open a file when it is read-only.
.Sp
Default value: 0
.Sp
Only actual when openMode is 0.
.IP "noTestFileCreate \s-1BOOLEAN\s0" 4
.IX Item "noTestFileCreate BOOLEAN"
If 0, tests if a file selected can be created.
.Sp
Default value: 0
.Sp
Only actual when openMode is 0.
.IP "overwritePrompt \s-1BOOLEAN\s0" 4
.IX Item "overwritePrompt BOOLEAN"
If 1, asks the user if the file selected is to be overwrittten.
.Sp
Default value: 1
.Sp
Only actual when openMode is 0.
.IP "openMode \s-1BOOLEAN\s0" 4
.IX Item "openMode BOOLEAN"
Create-only property.
.Sp
Selects whether the dialog operates in 'open' ( 1 ) mode or 'save' ( 0 ) 
mode.
.IP "pathMustExist \s-1BOOLEAN\s0" 4
.IX Item "pathMustExist BOOLEAN"
If 1, ensures that the path, types by the user, exists before
closing the dialog.
.Sp
Default value: 1
.IP "showDotFiles \s-1BOOLEAN\s0" 4
.IX Item "showDotFiles BOOLEAN"
Selects if the directories with the first dot character
are shown the files view.
.Sp
Default value: 0
.IP "showHelp \s-1BOOLEAN\s0" 4
.IX Item "showHelp BOOLEAN"
Create-only property. If 1, 'Help' button is inserted in the dialog.
.Sp
Default value: 1
.IP "sorted \s-1BOOLEAN\s0" 4
.IX Item "sorted BOOLEAN"
Selects whether the file list appears sorted by name ( 1 ) or not ( 0 ).
.Sp
Default value : 1
.IP "system \s-1BOOLEAN\s0" 4
.IX Item "system BOOLEAN"
Create-only property. If set to 1, \f(CW\*(C`Prima::FileDialog\*(C'\fR returns
instance of \f(CW\*(C`Prima::sys::XXX::FileDialog\*(C'\fR system-specific file dialog, 
if available for the \fI\s-1XXX\s0\fR platform.
.Sp
\&\f(CW\*(C`system\*(C'\fR knows only how to map \f(CW\*(C`FileDialog\*(C'\fR, \f(CW\*(C`OpenDialog\*(C'\fR, and \f(CW\*(C`SaveDialog\*(C'\fR
classes onto the system-specific file dialog classes; the inherited classes 
are not affected.
.SS "Methods"
.IX Subsection "Methods"
.IP "reread" 4
.IX Item "reread"
Re-reads the currently selected directory.
.SH "Prima::OpenDialog"
.IX Header "Prima::OpenDialog"
Descendant of Prima::FileDialog, tuned for open-dialog functionality.
.SH "Prima::SaveDialog"
.IX Header "Prima::SaveDialog"
Descendant of Prima::FileDialog, tuned for save-dialog functionality.
.SH "Prima::ChDirDialog"
.IX Header "Prima::ChDirDialog"
Provides standard dialog with interactive directory selection.
.SS "Properties"
.IX Subsection "Properties"
.IP "directory \s-1STRING\s0" 4
.IX Item "directory STRING"
Selects the directory
.IP "showDotDirs" 4
.IX Item "showDotDirs"
Selects if the directories with the first dot character
are shown the view.
.Sp
Default value: 0
.IP "showHelp" 4
.IX Item "showHelp"
Create-only property. If 1, 'Help' button is inserted in the dialog.
.Sp
Default value: 1
.SH "AUTHOR"
.IX Header "AUTHOR"
Dmitry Karasik, <dmitry@karasik.eu.org>.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Prima, Prima::Window, Prima::Lists,
\&\fIexamples/drivecombo.pl\fR, \fIexamples/launch.pl\fR.