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

FreeBSD Manual Pages

  
 
  

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

NAME
       Tk::getOpenFile,	Tk::getSaveFile	- pop up a dialog box for the user to
       select a	file to	open or	save.

SYNOPSIS
       A A A A $widget->getOpenFile(?-option=>value, ...>?)

       A A A A $widget->getSaveFile(?-option=>value, ...>?)

DESCRIPTION
       The methods getOpenFile and getSaveFile pop up a	dialog box for the
       user to select a	file to	open or	save.

       The getOpenFile method is usually associated with the Open command in
       the File	menu.  Its purpose is for the user to select an	existing file
       only.  If the user enters an non-existent file, the dialog box gives
       the user	an error prompt	and requires the user to give an alternative
       selection. If an	application allows the user to create new files, it
       should do so by providing a separate New	menu command.

       The getSaveFile method is usually associated with the Save as command
       in the File menu. If the	user enters a file that	already	exists,	the
       dialog box prompts the user for confirmation whether the	existing file
       should be overwritten or	not.

       If the user selects a file, both	getOpenFile and	getSaveFile return the
       full pathname of	this file. If the user cancels the operation, both
       commands	return an undefined value.

       The following option-value pairs	are possible as	command	line arguments
       to these	two commands:

       -defaultextension => extension
	   Specifies a string that will	be appended to the filename if the
	   user	enters a filename without an extension.	The default value is
	   the empty string, which means no extension will be appended to the
	   filename in any case. This option is	ignored	on the Macintosh
	   platform, which does	not require extensions to filenames, and the
	   UNIX	implementation guesses reasonable values  for  this from the
	   -filetypes option when this is not supplied.

       -filetypes => [filePattern ?, ...?]
	   If a	File types listbox exists in the file dialog on	the particular
	   platform, this option gives the filetypes in	this listbox. When the
	   user	choose a filetype in the listbox, only the files of that type
	   are listed. If this option is unspecified, or if it is set to the
	   empty list, or if the File types listbox is not supported by	the
	   particular platform then all	files are listed regardless of their
	   types. See "SPECIFYING FILE PATTERNS" below for a discussion	on the
	   contents of filePatterns.

       -initialdir => directory
	   Specifies that the files in directory should	be displayed when the
	   dialog pops up. If this parameter is	not specified, then the	files
	   in the current working directory are	displayed.  This option	may
	   not always work on the Macintosh.  This is not a bug.  Rather, the
	   General Controls control panel on the Mac allows the	end user to
	   override the	application default directory.

       -initialfile => filename
	   Specifies a filename	to be displayed	in the dialog when it pops up.
	   This	option is ignored by the getOpenFile method.

       -multiple
	   Allows the user to choose multiple files from the Open dialog.  On
	   the Macintosh, this is only available when Navigation Services are
	   installed.

       -message	=> string
	   Specifies a message to include in the client	area of	the dialog.
	   This	is only	available on the Macintosh, and	only when Navigation
	   Services are	installed.

       -title => titleString
	   Specifies a string to display as the	title of the dialog box. If
	   this	option is not specified, then a	default	title is displayed.
	   This	option is ignored on the Macintosh platform.

SPECIFYING FILE	PATTERNS
       The filePatterns	given by the -filetypes	option are a list of file
       patterns. Each file pattern is a	list of	the form

	typeName [extension ?extension ...?] ?[macType ?macType	...?]?

       typeName	is the name of the file	type described by this file pattern
       and is the text string that appears in the File types listbox.
       extension is a file extension for this file pattern.  macType is	a
       four-character Macintosh	file type. The list of macTypes	is optional
       and may be omitted for applications that	do not need to execute on the
       Macintosh platform.

       Several file patterns may have the same typeName, in which case they
       refer to	the same file type and share the same entry in the listbox.
       When the	user selects an	entry in the listbox, all the files that match
       at least	one of the file	patterns corresponding to that entry are
       listed. Usually,	each file pattern corresponds to a distinct type of
       file. The use of	more than one file patterns for	one type of file is
       necessary on the	Macintosh platform only.

       On the Macintosh	platform, a file matches a file	pattern	if its name
       matches at least	one of the extension(s)	AND it belongs to at least one
       of the macType(s) of the	file pattern. For example, the C Source	Files
       file pattern in the sample code matches with files that have a \.c
       extension AND belong to the macType TEXT. To use	the OR rule instead,
       you can use two file patterns, one with the extensions only and the
       other with the macType only. The	GIF Files file type in the sample code
       matches files that EITHER have a	\.gif extension	OR belong to the
       macType GIFF.

       On the Unix and Windows platforms, a file matches a file	pattern	if its
       name matches at at least	one of the extension(s)	of the file pattern.
       The macTypes are	ignored.

SPECIFYING EXTENSIONS
       On the Unix and Macintosh platforms, extensions are matched using glob-
       style pattern matching. On the Windows platforms, extensions are
       matched by the underlying operating system. The types of	possible
       extensions are: (1) the special extension * matches any file; (2) the
       special extension "" matches any	files that do not have an extension
       (i.e., the filename contains no full stop character); (3) any character
       string that does	not contain any	wild card characters (*	and ?).

       Due to the different pattern matching rules on the various platforms,
       to ensure portability, wild card	characters are not allowed in the
       extensions, except as in	the special extension *. Extensions without a
       full stop character (e.g, ~) are	allowed	but may	not work on all
       platforms.

CAVEATS
       See "CAVEATS" in	Tk::chooseDirectory.

EXAMPLE
	my $types = [
	    ['Text Files',	 ['.txt', '.text']],
	    ['TCL Scripts',	 '.tcl'		  ],
	    ['C	Source Files',	 '.c',	    'TEXT'],
	    ['GIF Files',	 '.gif',	  ],
	    ['GIF Files',	 '',	    'GIFF'],
	    ['All Files',	 '*',		  ],
	];
	my $filename = $widget->getOpenFile(-filetypes=>$types);

	if ($filename ne "") {
	    # Open the file ...
	}

SEE ALSO
       Tk::FBox, Tk::FileSelect

KEYWORDS
       file selection dialog

perl v5.24.1			  2013-11-15			getOpenFile(3)

NAME | SYNOPSIS | DESCRIPTION | SPECIFYING FILE PATTERNS | SPECIFYING EXTENSIONS | CAVEATS | EXAMPLE | SEE ALSO | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Tk::getOpenFile&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help