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

FreeBSD Manual Pages


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


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

       tk_getOpenFile ?option value ...?
       tk_getSaveFile ?option value ...?

       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:

       -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, then the
	      files in the current working directory are displayed. If the pa-
	      rameter 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

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

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

       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.

       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

       (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

	      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 != ""} {
		  # Open the file ...


       file selection dialog

Tk				      4.2		     tk_getOpenFile(n)


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

home | help