1% File src/library/utils/man/select.list.Rd
2% Part of the R package, https://www.R-project.org
3% Copyright 1995-2018 R Core Team
4% Distributed under GPL 2 or later
5
6\name{select.list}
7\alias{select.list}
8\title{Select Items from a List}
9\description{
10  Select item(s) from a character vector.
11}
12\usage{
13select.list(choices, preselect = NULL, multiple = FALSE,
14            title = NULL, graphics = getOption("menu.graphics"))
15}
16\arguments{
17  \item{choices}{a character vector of items.}
18  \item{preselect}{a character vector, or \code{NULL}.  If non-null and
19    if the string(s) appear in the list, the item(s) are selected
20    initially.}
21  \item{multiple}{logical: can more than one item be selected?}
22  \item{title}{optional character string for window title, or
23    \code{NULL} for no title.}
24  \item{graphics}{logical: should a graphical widget be used?}
25}
26\details{
27  The normal default is \code{graphics = TRUE}.
28  \describe{
29    \item{On Windows,}{this brings up a modal dialog box with a (scrollable) list
30      of items, which can be selected by the mouse.  If \code{multiple} is
31      true, further items can be selected or deselected by holding the
32      control key down whilst selecting, and shift-clicking can be used to
33      select ranges.
34
35      Normal termination is via the \sQuote{OK} button or by hitting Enter or
36      double-clicking an item.  Selection can be aborted via the
37      \sQuote{Cancel} button or pressing Escape.}
38    \item{Under the macOS GUI,}{this brings up a modal dialog box
39      with a (scrollable) list of items, which can be selected by the mouse.}
40    \item{On other Unix-like platforms}{it will use a Tcl/Tk listbox
41      widget if possible.}
42  }
43
44  If \code{graphics} is FALSE or no graphical widget is available it
45  displays a text list from which the user can choose by number(s). The
46  \code{multiple = FALSE} case uses \code{\link{menu}}.  Preselection is
47  only supported for \code{multiple = TRUE}, where it is indicated by a
48  \code{"+"} preceding the item.
49
50  It is an error to use \code{select.list} in a non-interactive session.
51}
52\value{
53  A character vector of selected items.  If \code{multiple} is false and
54  no item was selected (or \code{Cancel} was used), \code{""} is
55  returned.   If \code{multiple} is true and no item was selected (or
56  \code{Cancel} was used) then a character vector of length 0 is returned.
57}
58\seealso{
59  \code{\link{menu}}, \code{\link{tk_select.list}} for a graphical
60  version using Tcl/Tk.
61}
62\examples{\dontrun{
63select.list(sort(.packages(all.available = TRUE)))
64}}
65\keyword{utilities}
66