Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
FileDialog(3)	      User Contributed Perl Documentation	 FileDialog(3)

       Tk::FileDialog -	A highly configurable File Dialog widget for Perl/Tk.

       The widget is composed of a number of sub-widgets, namely, a listbox
       for files and (optionally) directories, an entry	for filename, an
       (optional) entry	for pathname, an entry for a filter pattern, a
       'ShowAll' checkbox (for enabling	display	of .* files and	directories),
       and three buttons, namely OK, Rescan, and Cancel.  Note that the	labels
       for all subwidgets (including the text for the buttons and Checkbox)
       are configurable	for foreign language support.  The Listboxes will
       respond to characters typed over	them with scrolling to the first line
       that starts with	the given character (or	next etc. if this character is
       not present).

   Usage Description
       To use FileDialog, simply create	your FileDialog	objects	during
       initialization (or at least before a Show).  When you wish to display
       the FileDialog, invoke the 'Show' method	on the FileDialog object;  The
       method will return either a file	name, a	path name, or undef.  undef is
       returned	only if	the user pressed the Cancel button.

   Example Code
       The following code creates a FileDialog and calls it.  Note that
       perl5.002gamma is required.


	    #!/usr/local/bin/perl -w

	    use	Tk;
	    use	Tk::FileDialog;
	    use	strict;

	    my($main) =	MainWindow->new;
	    my($Horiz) = 1;

	    my($LoadDialog) = $main->FileDialog(-Title =>'This is my title',
					       -Create => 0);

	    print "Using FileDialog Version ",$LoadDialog->Version,"\n";

	    $LoadDialog->configure(-FPat => '*pl',
				  -ShowAll => 'NO');

	    $main->Entry(-textvariable => \$fname)
		   ->pack(-expand => 1,
			  -fill	=> 'x');

	    $main->Button(-text	=> 'Kick me!',
			 -command => sub {
			     $fname = $LoadDialog->Show(-Horiz => $Horiz);
			     if	(!defined($fname)) {
				 $fname	= "Fine,Cancel,	but no Chdir anymore!!!";
				 $LoadDialog->configure(-Chdir =>'NO');
		   ->pack(-expand => 1,
			  -fill	=> 'x');

	    $main->Checkbutton(-text =>	'Horizontal',
			      -variable	=> \$Horiz)
		   ->pack(-expand => 1,
			  -fill	=> 'x');

	    $main->Button(-text	=> 'Exit',
			 -command => sub {
		   ->pack(-expand => 1,
			  -fill	=> 'x');


	    print "Exit	Stage right!\n";


       o   The following non-standard methods may be used with a FileDialog


	   Displays the	file dialog box	for the	user to	operate.  Additional
	   configuration items may be passed in	at Show-time In	other words,
	   this	code snippet:

	     $fd->Show(-Title => 'Ooooh, Preeeeeety!');

	   is the same as this code snippet:

	     $fd->configure(-Title => 'Ooooh, Preeeeeety!');


       Returns the current Version of FileDialog

       Any of the following configuration items	may be set via the configure
       (or Show) method, or retrieved via the cget method.

       Flags may be configured with either 1,'true', or	'yes' for 1, or	0,
       'false',	or 'no'	for 0. Any portion of 'true', 'yes', 'false', or 'no'
       may be used, and	case does not matter.


       o       Enable the user to change directories. The default is 1.	If
	       disabled, the directory list box	will not be shown.

       o       Enable the user to specify a file that does not exist. If not
	       enabled,	and the	user specifies a non-existent file, a dialog
	       box will	be shown informing the user of the error (This Dialog
	       Box is configurable via the EDlg* switches, below).

	       default:	1

       o       Determines whether hidden files (.*) are	displayed in the File
	       and Directory Listboxes.	 The default is	0. The Show All
	       Checkbox	reflects the setting of	this switch.

       o       Disables	the ability of the user	to change the status of	the
	       ShowAll flag. The default is 0 (the user	is by default allowed
	       to change the status).

       o       Enables the File	Dialog to do an	application Grab when
	       displayed. The default is 1.

       o       True sets the File List box to be to the	right of the Directory
	       List Box. If 0, the File	List box will be below the Directory
	       List box. The default is	1.

       o       If True,	enables	selection of a directory rather	than a file,
	       and disables the	actions	of the File List Box. The default is


       o       Sets the	default	file selection pattern.	The default is '*'.
	       Only files matching this	pattern	will be	displayed in the File
	       List Box.

       o       Sets the	geometry of the	File Dialog. Setting the size is a
	       dangerous thing to do.  If not configured, or set to '',	the
	       File Dialog will	be centered.

       o       SelHook is configured with a reference to a routine that	will
	       be called when a	file is	chosen.	The file is called with	a sole
	       parameter of the	full path and file name	of the file chosen. If
	       the Create flag is disabled (and	the user is not	allowed	to
	       specify new files), the file will be known to exist at the time
	       that SelHook is called. Note that SelHook will also be called
	       with directories	if the SelDir Flag is enabled, and that	the
	       FileDialog box will still be displayed. The FileDialog box
	       should not be destroyed from within the SelHook routine,
	       although	it may generally be configured.

	       SelHook routines	return 0 to reject the selection and allow the
	       user to reselect, and any other value to	accept the selection.
	       If a SelHook routine returns non-zero, the FileDialog will
	       immediately be withdrawn, and the file will be returned to the

	       There may be only one SelHook routine active at any time.
	       Configuring the SelHook routine replaces	any existing SelHook
	       routine.	Configuring the	SelHook	routine	with 0 removes the
	       SelHook routine.	The default SelHook routine is undef.

       The following two switches may be used to set default variables,	and to
       get final values	after the Show method has returned (but	has not	been
       explicitly destroyed by the caller)

       o   -File  The file selected, or	the default file. The default is ''.

	   -Path  The path of the selected file, or the	initial	path. The
	   default is $ENV{'HOME'}.

   Labels and Captions
       For support of internationalization, the	text on	any of the subwidgets
       may be changed.

       o   -Title  The Title of	the dialog box.	The default is 'Select File:'.

	   -DirLBCaption  The Caption above the	Directory List Box. The
	   default is 'Directories'.

	   -FileLBCaption  The Caption above the File List Box.	The default is

	   -FileEntryLabel  The	label to the left of the File Entry. The
	   Default is 'Filename:'.

	   -PathEntryLabel  The	label to the left of the Path Entry. The
	   default is 'Pathname:'.

	   -FltEntryLabel  The label to	the left of the	Filter entry. The
	   default is 'Filter:'.

	   -ShowAllLabel  The text of the Show All Checkbutton.	The default is
	   'Show All'.

   Button Text
       For support of internationalization, the	text on	the three buttons may
       be changed.

       o   -OKButtonLabel  The text for	the OK button. The default is 'OK'.

	   -RescanButtonLabel  The text	for the	Rescan button. The default is

	   -CancelButtonLabel  The text	for the	Cancel button. The default is

   Error Dialog	Switches
       If the Create switch is set to 0, and the user specifies	a file that
       does not	exist, a dialog	box will be displayed informing	the user of
       the error. These	switches allow some configuration of that dialog box.


       o       The title of the	Error Dialog Box. The default is 'File does
	       not exist!'.

       o       The message of the Error	Dialog Box. The	variables $path,
	       $file, and $filename (the full path and filename	of the
	       selected	file) are available. The default is "You must specify
	       an existing file.\n(\$filename not found)"

       Brent B.	Powers,	Merrill	Lynch (B2Pi)

       This code may be	distributed under the same conditions as Perl itself.

       Hey! The	above document had some	coding errors, which are explained

       Around line 63:
	   You forgot a	'=back'	before '=head2'

       Around line 133:
	   =back without =over

       Around line 145:
	   You forgot a	'=back'	before '=head2'

       Around line 162:
	   '=item' outside of any '=over'

       Around line 164:
	   You forgot a	'=back'	before '=head2'

       Around line 168:
	   =back without =over

       Around line 185:
	   You forgot a	'=back'	before '=head2'

       Around line 264:
	   =back without =over

       Around line 272:
	   You forgot a	'=back'	before '=head2'

       Around line 319:
	   =back without =over

       Around line 388:
	   You forgot a	'=back'	before '=head2'

       Around line 410:
	   =back without =over

perl v5.32.0			  1996-06-09			 FileDialog(3)


Want to link to this manual page? Use this URL:

home | help