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

FreeBSD Manual Pages

  
 
  

home | help
tk_getOpenFile(n)	     Tk	Built-In Commands	     tk_getOpenFile(n)

______________________________________________________________________________

NAME
       tk_getOpenFile,	tk_getSaveFile	-  pop up a dialog box for the user to
       select a	file to	open or	save.

SYNOPSIS
       tk_getOpenFile ?option value ...?
       tk_getSaveFile ?option value ...?
______________________________________________________________________________

DESCRIPTION
       The procedures tk_getOpenFile and tk_getSaveFile	pop up	a  dialog  box
       for  the	user to	select a file to open or save. The tk_getOpenFile com-
       mand 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 a	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  tk_getSaveFile command is usually associated with the Save as com-
       mand 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.

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

       -command	string
	      Specifies	 the  prefix  of a Tcl command to invoke when the user
	      closes the dialog	after having selected an item.	This  callback
	      is  not called if	the user cancelled the dialog. The actual com-
	      mand consists of string followed by a space and  the  value  se-
	      lected  by the user in the dialog. This is only available	on Mac
	      OS X.

       -confirmoverwrite boolean
	      Configures how the Save dialog reacts when the selected file al-
	      ready  exists,  and saving would overwrite it.  A	true value re-
	      quests a confirmation dialog be presented	to the user.  A	 false
	      value  requests  that the	overwrite take place without confirma-
	      tion.  Default value is true.

       -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 Mac OS X,
	      which does not require extensions	to filenames, and the UNIX im-
	      plementation  guesses reasonable values for this from the	-file-
	      types option when	this is	not supplied.

       -filetypes filePatternList
	      If a File	types listbox exists in	the file dialog	on the partic-
	      ular  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 the section SPECIFYING FILE  PAT-
	      TERNS below for a	discussion on the contents of filePatternList.

       -initialdir directory
	      Specifies	 that  the files in directory should be	displayed when
	      the dialog pops up. If this parameter is not specified, the ini-
	      tial directory defaults to the current working directory on non-
	      Windows systems and on Windows systems prior to Vista.  On Vista
	      and  later  systems,  the	initial	directory defaults to the last
	      user-selected directory for the application.  If	the  parameter
	      specifies	 a  relative  path,  the return	value will convert the
	      relative path to an absolute path.

       -initialfile filename
	      Specifies	a filename to be displayed in the dialog when it  pops
	      up.

       -message	string
	      Specifies	a message to include in	the client area	of the dialog.
	      This is only available on	Mac OS X.

       -multiple boolean
	      Allows the user to choose	multiple files from the	Open dialog.

       -parent window
	      Makes window the logical parent of the file dialog. The file di-
	      alog is displayed	on top of its parent window. On	Mac OS X, this
	      turns the	file dialog into a sheet attached to the  parent  win-
	      dow.

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

       -typevariable variableName
	      The global variable variableName is used to preselect which fil-
	      ter is used from filterList when the dialog box is opened	and is
	      updated when the dialog box is closed, to	the last selected fil-
	      ter.  The	 variable  is read once	at the beginning to select the
	      appropriate filter. If the variable does not exist, or its value
	      does not match any filter	typename, or is	empty ({}), the	dialog
	      box will revert to the default behavior of selecting  the	 first
	      filter  in  the list. If the dialog is canceled, the variable is
	      not modified.

       If the user selects a file, both	tk_getOpenFile and tk_getSaveFile  re-
       turn the	full pathname of this file. If the user	cancels	the operation,
       both commands return the	empty string.

SPECIFYING FILE	PATTERNS
       The filePatternList value given by the -filetypes option	is 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.	exten-
       sion  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	Macin-
       tosh 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 pattern for one type of file is
       only necessary on the Macintosh platform.

       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 ex-
       tension 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 mac-
       Type GIFF.

       On the Unix and Windows platforms, a file matches a file	pattern	if its
       name  matches 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 platform,	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 charac-
	      ters (* and ?).

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

EXAMPLE
	      set types	{
		  {{Text Files}	      {.txt}	    }
		  {{TCL	Scripts}      {.tcl}	    }
		  {{C Source Files}   {.c}	TEXT}
		  {{GIF	Files}	      {.gif}	    }
		  {{GIF	Files}	      {}	GIFF}
		  {{All	Files}	      *		    }
	      }
	      set filename [tk_getOpenFile -filetypes $types]

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

SEE ALSO
       tk_chooseDirectory

KEYWORDS
       file selection dialog

Tk				      4.2		     tk_getOpenFile(n)

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

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=tk_getOpenFile.tk86&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help