[OpenSPARC-T2-DV] / tools / perl-5.8.0 / lib / site_perl / 5.8.0 / sun4-solaris / Tk / FileSelect.pod


=head1 NAME

Tk::FileSelect - a widget for choosing files

=for pm Tk/FileSelect.pm

=for category Popups and Dialogs

=head1 SYNOPSIS

 use Tk::FileSelect;

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

=head1 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.

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.

=head1 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

=head1 HISTORY

=head2 950621 -- The following changes were made:

=over 4

=item *

Rewrote Tk stuff to take advantage of new Compound widget module, so
FileSelect is now composed of 2 LabEntry and 2 ScrlListbox2
subwidgets.

=item *

Moved entry labels (from to the left of) to above the entry fields.

=item *

Caller is now able to control these aspects of widget, in both
FileSelect (new) and configure :

(Please see subroutine Populate for details, as these options
change rapidly!)

=item *

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, ...).

=item *

The show method is not yet updated.

=item *

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.

=item *

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.

=back

=head2 95/10/17, SOL, LUCC.  lusol@Lehigh.EDU

=over 4

=item *

 Allow either file or directory names to be accepted.

=item *

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.

=item *

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 IS FileSelect!

For example:

    $fs->configure(-verify => ['-d', [\&verify_code, $P1, $P2, ... $Pn]]);

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:

    &verify_code($cd, $leaf, $P1, $P2, ... $Pn);

where $cd is the current directory, $leaf is a directory or file name, and
$P1 .. $Pn are your optional parameters.  The subroutine should return TRUE
if success or FALSE if failure.

=back

=head2 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.

=cut
Commit	Line	Data
86530b38 AT	1
	2	=head1 NAME
	3
	4	Tk::FileSelect - a widget for choosing files
	5
	6	=for pm Tk/FileSelect.pm
	7
	8	=for category Popups and Dialogs
	9
	10	=head1 SYNOPSIS
	11
	12	use Tk::FileSelect;
	13
	14	$FSref = $top->FileSelect(-directory => $start_dir);
	15	$top - a window reference, e.g. MainWindow->new
	16	$start_dir - the starting point for the FileSelect
	17	$file = $FSref->Show;
	18	Executes the fileselector until either a filename is
	19	accepted or the user hits Cancel. Returns the filename
	20	or the empty string, respectively, and unmaps the
	21	FileSelect.
	22	$FSref->configure(option => value[, ...])
	23	Please see the Populate subroutine as the configuration
	24	list changes rapidly.
	25
	26	=head1 DESCRIPTION
	27
	28	This Module pops up a Fileselector box, with a directory entry on
	29	top, a list of directories in the current directory, a list of
	30	files in the current directory, an entry for entering/modifying a
	31	file name, an accept button and a cancel button.
	32
	33	You can enter a starting directory in the directory entry. After
	34	hitting Return, the listboxes get updated. Double clicking on any
	35	directory shows you the respective contents. Single clicking on a
	36	file brings it into the file entry for further consideration,
	37	double clocking on a file pops down the file selector and calls
	38	the optional command with the complete path for the selected file.
	39	Hitting return in the file selector box or pressing the accept
	40	button will also work. NOTE the file selector box will only then
	41	get destroyed if the file name is not zero length. If you want
	42	yourself take care of it, change the if(length(.. in sub
	43	accept_file.
	44
	45	=head1 AUTHORS
	46
	47	Based on original FileSelect by
	48	Klaus Lichtenwalder, Lichtenwalder@ACM.org, Datapat GmbH, Munich,
	49	April 22, 1995 adapted by
	50	Frederick L. Wagner, derf@ti.com, Texas Instruments Incorporated, Dallas,
	51	21Jun95
	52
	53	=head1 HISTORY
	54
	55	=head2 950621 -- The following changes were made:
	56
	57	=over 4
	58
	59	=item *
	60
	61	Rewrote Tk stuff to take advantage of new Compound widget module, so
	62	FileSelect is now composed of 2 LabEntry and 2 ScrlListbox2
	63	subwidgets.
	64
65	=item *
66
67	Moved entry labels (from to the left of) to above the entry fields.
68
69	=item *
70
71	Caller is now able to control these aspects of widget, in both
72	FileSelect (new) and configure :
73
74	(Please see subroutine Populate for details, as these options
75	change rapidly!)
76
77	=item *
78
79	I changed from Double-Button-1 to Button-1 in the Files listbox,
80	to work with multiple mode in addition to browse mode. I also
81	made some name changes (LastPath --> saved_path, ...).
82
83	=item *
84
85	The show method is not yet updated.
86
87	=item *
88
89	The topLevel stuff is not done yet. I took it out while I toy with
90	the idea of FileSelect as a subwidget. Then the 'normal' topLevel
91	thing with Buttons along the bottom could be build on top of it.
92
93	=item *
94
95	By request of Henry Katz <katz@fs09.webo.dg.com>, I added the functionality
96	of using the Directory entry as a filter. So, if you want to only see the
97	.c files, you add a .c (the 's already there :) and hit return.
98
99	=back
100
101	=head2 95/10/17, SOL, LUCC. lusol@Lehigh.EDU
102
103	=over 4
104
105	=item *
106
107	Allow either file or directory names to be accepted.
108
109	=item *
110
111	Require double click to move into a new directory rather than a single
112	click. This allows a single click to select a directory name so it can
113	be accepted.
114
115	=item *
116
117	Add -verify list option so that standard Perl file test operators (like
118	-d and -x) can be specified for further name validation. The default
119	value is the special value '!-d' (not a directory), so any name can be
120	selected as long as it's not a directory - after all, this IS FileSelect!
121
122	For example:
123
124	$fs->configure(-verify => ['-d', [\&verify_code, $P1, $P2, ... $Pn]]);
125
126	ensures that the selected name is a directory. Further, if an element of
127	the list is an array reference, the first element is a code reference to a
128	subroutine and the remaining optional elements are it's parameters. The
129	subroutine is called like this:
130
131	&verify_code($cd, $leaf, $P1, $P2, ... $Pn);
132
133	where $cd is the current directory, $leaf is a directory or file name, and
134	$P1 .. $Pn are your optional parameters. The subroutine should return TRUE
135	if success or FALSE if failure.
136
137	=back
138
139	=head2 961008 -- derf@ti.com :
140
141	By request of Jim Stern <js@world.northgrum.com> and Brad Vance
142	<bvance@ti.com>, I updated the Accept and Show functions to support
143	selection of multiple files. I also corrected a typo in the -verify code.
144
145	=cut
146