loading...

Modal dialog to select one or more items in a list.

Source: R/dlg_list.R

Display a list and allow user to select either one, or multiple items in that list.

dlg_list(
  choices,
  preselect = NULL,
  multiple = FALSE,
  title = NULL,
  ...,
  gui = .GUI
)

dlgList(
  choices,
  preselect = NULL,
  multiple = FALSE,
  title = NULL,
  ...,
  gui = .GUI
)

# S3 method for gui
dlg_list(
  choices,
  preselect = NULL,
  multiple = FALSE,
  title = NULL,
  ...,
  gui = .GUI
)

# S3 method for textCLI
dlg_list(
  choices,
  preselect = NULL,
  multiple = FALSE,
  title = NULL,
  ...,
  gui = .GUI
)

# S3 method for nativeGUI
dlg_list(
  choices,
  preselect = NULL,
  multiple = FALSE,
  title = NULL,
  rstudio = getOption("svDialogs.rstudio", TRUE),
  ...,
  gui = .GUI
)

Arguments

choices

The list of items. It is coerced to character strings.

preselect

A list of preselections, or NULL (then, the first element is selected in the list). Preselections not in choices are tolerated (but they are ignored without warning or error).

multiple

Is it a multiple selection dialog box?

title

The title of the dialog box, or NULL to use a default title instead.

...

Pass further arguments to methods.

gui

The 'gui' object concerned by this dialog box.

rstudio

Logical. Should 'RStudio' dialog boxes automatically be used if available? If FALSE, force using OS dialog boxes, but only in 'RStudio Desktop' (ignored in 'RStudio Server'). Can be changed globally with options(svDialogs.rstudio = TRUE|FALSE). TRUE by default.

Value

The modified 'gui' object is returned invisibly. A list with selected items, or a character vector of length 0 if the dialog box was cancelled is available from gui$res (see examples).

Note

RStudio does not provide (yet) a graphical list selector (as of version 1.1.447). Consequently, a Tk version is used (if 'tcltk' is available) for 'RStudio Desktop' and a textual version at the R Console is used in the other cases, for 'nativeGUI' as a temporary workaround (should be implemented in Shiny later on). Also note that the textual version only reports preselection when multiple == TRUE, and they are not used automatically if you do not respecify them in your feedback (limitation of utils::select.list(graphics = FALSE)). On MacOS, and outside of R(64).app, which has his own list selection dialog box, single and double quotes are temporarily replaced by their slanted versions (unicode characters u3032 and u2033, respectively) because the command that triggers the dialog box does not allow quotes inside strings. Regular quotes are reset on the output. This is the only hack we found that was working. Better solutions are welcome, of course!

Examples

if (FALSE) {
# Select one or several months
res <- dlg_list(month.name, multiple = TRUE)$res
if (!length(res)) {
  cat("You cancelled the choice\n")
} else {
  cat("You selected:\n")
  print(res)
}
}