Manual Pages for UNIX Operating System command usage for man tk_getOpenFile

Tk Built-In Commands                           tk_getOpenFile(1T)



_________________________________________________________________

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

     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 plat-
          form,  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 filePatternList
          If a File types listbox exists in the  file  dialog  on
          the  particular  platform,  this option gives the file-
          types 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 sup-
          ported by the particular platform then  all  files  are
          listed  regardless  of  their  types.  See  the section



Tk                      Last change: 4.2                        1






Tk Built-In Commands                           tk_getOpenFile(1T)



          SPECIFYING FILE PATTERNS 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 parameter specifies a
          relative path, the return value will convert the  rela-
          tive  path  to  an  absolute path.  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 on the Macintosh
          platform.

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

     -parent window
          Makes window the logical parent of the file dialog. The
          file dialog is displayed on top of its parent window.

     -title titleString
          Specifies a string to display as the title of the  dia-
          log  box.  If  this  option  is  not  specified, then a
          default title is displayed.

     If  the  user  selects  a  file,  both  tk_getOpenFile   and
     tk_getSaveFile return 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. extension is a file extension for  this  file



Tk                      Last change: 4.2                        2






Tk Built-In Commands                           tk_getOpenFile(1T)



     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  pat-
     tern.  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 exten-
     sion OR belong to the macType 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 platforms,
     extensions are matched by the underlying  operating  system.
     The types of possible extensions are: (1) the special exten-
     sion * 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); (3TK) any charac-
     ter 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.


EXAMPLE
          set types {
              {{Text Files}       {.txt}        }
              {{TCL Scripts}      {.tcl}        }
              {{C Source Files}   {.c}      TEXT}



Tk                      Last change: 4.2                        3






Tk Built-In Commands                           tk_getOpenFile(1T)



              {{GIF Files}        {.gif}        }
              {{GIF Files}        {}        GIFF}
              {{All Files}        *             }
          }
          set filename [tk_getOpenFile -filetypes $types]

          if {$filename != ""} {
              # Open the file ...
          }


SEE ALSO
     tk_chooseDirectory


KEYWORDS
     file selection dialog

ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:

     _______________________________________
    |   ATTRIBUTE TYPE   |  ATTRIBUTE VALUE|
    |____________________|__________________|_
    | Availability       |  runtime/tk-8   |
    |____________________|__________________|_
    | Interface Stability|  Uncommitted    |
    |____________________|_________________|

NOTES
     Source for Tk is available on http://opensolaris.org.























Tk                      Last change: 4.2                        4