Initial commit of OpenSPARC T2 design and verification files.

[OpenSPARC-T2-DV] / tools / perl-5.8.0 / man / man3 / Tk::FileSelect.3

.\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.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.  | will give a
.\" real vertical bar.  \*(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-|\(bv\*(Tr
.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" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" 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 "FILESELECT 1"
.TH FILESELECT 1 "2000-12-30" "perl v5.8.0" "User Contributed Perl Documentation"
.SH "NAME"
Tk::FileSelect \- a widget for choosing files
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Tk::FileSelect;
.Ve
.PP
.Vb 11
\& $FSref = $top->FileSelect(-directory => $start_dir);
\&               $top            - a window reference, e.g. MainWindow->new
\&               $start_dir      - the starting point for the FileSelect
\& $file = $FSref->Show;
\&               Executes the fileselector until either a filename is
\&               accepted or the user hits Cancel. Returns the filename
\&               or the empty string, respectively, and unmaps the
\&               FileSelect.
\& $FSref->configure(option => value[, ...])
\&               Please see the Populate subroutine as the configuration
\&               list changes rapidly.
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This Module pops up a Fileselector box, with a directory entry on
top, a list of directories in the current directory, a list of
files in the current directory, an entry for entering/modifying a
file name, an accept button and a cancel button.
.PP
You can enter a starting directory in the directory entry. After
hitting Return, the listboxes get updated. Double clicking on any
directory shows you the respective contents. Single clicking on a
file brings it into the file entry for further consideration,
double clocking on a file pops down the file selector and calls
the optional command with the complete path for the selected file.
Hitting return in the file selector box or pressing the accept
button will also work. *NOTE* the file selector box will only then
get destroyed if the file name is not zero length. If you want
yourself take care of it, change the if(length(.. in sub
accept_file.
.SH "AUTHORS"
.IX Header "AUTHORS"
Based on original FileSelect by
Klaus Lichtenwalder, Lichtenwalder@ACM.org, Datapat GmbH, Munich,
April 22, 1995 adapted by
Frederick L. Wagner, derf@ti.com, Texas Instruments Incorporated, Dallas,
21Jun95
.SH "HISTORY"
.IX Header "HISTORY"
.Sh "950621 \*(-- The following changes were made:"
.IX Subsection "950621  The following changes were made:"
.IP "\(bu" 4
Rewrote Tk stuff to take advantage of new Compound widget module, so
FileSelect is now composed of 2 LabEntry and 2 ScrlListbox2
subwidgets.
.IP "\(bu" 4
Moved entry labels (from to the left of) to above the entry fields.
.IP "\(bu" 4
Caller is now able to control these aspects of widget, in both
FileSelect (new) and configure :
.Sp
(Please see subroutine Populate for details, as these options
change rapidly!)
.IP "\(bu" 4
I changed from Double\-Button\-1 to Button\-1 in the Files listbox,
to work with multiple mode in addition to browse mode.  I also
made some name changes (LastPath \-\-> saved_path, ...).
.IP "\(bu" 4
The show method is not yet updated.
.IP "\(bu" 4
The topLevel stuff is not done yet.  I took it out while I toy with
the idea of FileSelect as a subwidget.  Then the 'normal' topLevel
thing with Buttons along the bottom could be build on top of it.
.IP "\(bu" 4
By request of Henry Katz <katz@fs09.webo.dg.com>, I added the functionality
of using the Directory entry as a filter. So, if you want to only see the
*.c files, you add a .c (the *'s already there :) and hit return.
.Sh "95/10/17, \s-1SOL\s0, \s-1LUCC\s0.  lusol@Lehigh.EDU"
.IX Subsection "95/10/17, SOL, LUCC.  lusol@Lehigh.EDU"
.IP "\(bu" 4
.Vb 1
\& Allow either file or directory names to be accepted.
.Ve
.IP "\(bu" 4
Require double click to move into a new directory rather than a single
click.  This allows a single click to select a directory name so it can
be accepted.
.IP "\(bu" 4
Add \-verify list option so that standard Perl file test operators (like
\&\-d and \-x) can be specified for further name validation.  The default
value is the special value '!\-d' (not a directory), so any name can be
selected as long as it's not a directory \- after all, this \s-1IS\s0 FileSelect!
.Sp
For example:
.Sp
.Vb 1
\&    $fs->configure(-verify => ['-d', [\e&verify_code, $P1, $P2, ... $Pn]]);
.Ve
.Sp
ensures that the selected name is a directory.  Further, if an element of
the list is an array reference, the first element is a code reference to a
subroutine and the remaining optional elements are it's parameters.  The
subroutine is called like this:
.Sp
.Vb 1
\&    &verify_code($cd, $leaf, $P1, $P2, ... $Pn);
.Ve
.Sp
where \f(CW$cd\fR is the current directory, \f(CW$leaf\fR is a directory or file name, and
\&\f(CW$P1\fR .. \f(CW$Pn\fR are your optional parameters.  The subroutine should return \s-1TRUE\s0
if success or \s-1FALSE\s0 if failure.
.Sh "961008 \*(-- derf@ti.com :"
.IX Subsection "961008  derf@ti.com :"
By request of Jim Stern <js@world.northgrum.com> and Brad Vance
<bvance@ti.com>, I updated the Accept and Show functions to support
selection of multiple files.  I also corrected a typo in the \-verify code.