| % File src/library/utils/man/choose.files.Rd |
| % Part of the R package, https://www.R-project.org |
| % Copyright 1995-2018 R Core Team |
| % Distributed under GPL 2 or later |
| |
| \name{choose.files} |
| \alias{choose.files} |
| \alias{Filters} |
| \title{Choose a List of Files Interactively on MS Windows} |
| \description{ |
| Use a Windows file dialog to choose a list of zero or more files |
| interactively. |
| } |
| \usage{ |
| choose.files(default = "", caption = "Select files", |
| multi = TRUE, filters = Filters, |
| index = nrow(Filters)) |
| |
| Filters |
| } |
| \arguments{ |
| \item{default}{which filename to show initially} |
| \item{caption}{the caption on the file selection dialog} |
| \item{multi}{whether to allow multiple files to be selected} |
| \item{filters}{a matrix of filename filters (see Details)} |
| \item{index}{which row of filters to use by default} |
| } |
| \value{ |
| A character vector giving zero or more file paths. |
| } |
| \details{ |
| Unlike \code{\link{file.choose}}, \code{choose.files} will always |
| attempt to return a character vector giving a list of files. If the |
| user cancels the dialog, then zero files are returned, whereas |
| \code{\link{file.choose}} would signal an error. \code{choose.dir} |
| chooses a directory. |
| |
| Windows file dialog boxes include a list of \sQuote{filters}, which allow |
| the file selection to be limited to files of specific types. |
| The \code{filters} argument to \code{choose.files} allows the list |
| of filters to be set. It should be an \code{n} by \code{2} character |
| matrix. The first column gives, for each filter, the description the |
| user will see, while the second column gives the mask(s) to select |
| those files. If more than one mask is used, separate them by |
| semicolons, with no spaces. The \code{index} argument chooses which |
| filter will be used initially. |
| |
| \code{Filters} is a matrix giving the descriptions and masks for |
| the file types that \R knows about. Print it to see typical formats |
| for filter specifications. The examples below show how particular |
| filters may be selected. |
| |
| If you would like to display files in a particular directory, |
| give a fully qualified file mask (e.g., \code{"c:\\\\*.*"}) |
| in the \code{default} argument. If a directory is not given, the |
| dialog will start in the current directory the first time, and |
| remember the last directory used on subsequent invocations. |
| |
| There is a buffer limit on the total length of the selected filenames: |
| it is large but this function is not intended to select thousands of |
| files, when the limit might be reached. |
| } |
| \note{ |
| This is only available on Windows. |
| } |
| \seealso{ |
| \code{\link{file.choose}}, \code{\link{choose.dir}}. |
| |
| \code{\link{Sys.glob}} or \code{\link{list.files}} to select multiple |
| files by pattern. |
| } |
| \examples{ |
| if (interactive() && .Platform$OS.type == "windows") |
| choose.files(filters = Filters[c("zip", "All"),]) |
| } |
| \keyword{file} |