R: rNMR dialog box utilities

dialogUtils {rNMR}

R Documentation

rNMR dialog box utilities

Description

The functions detailed below display custom Tk dialogs in rNMR. Several of these functions replace Windows-specific functions available in Rgui for cross-platform use.

Usage

buttonDlg(message, buttons, checkBox = FALSE, default = buttons[1], 
	title = 'rNMR', parent = NULL)
err(message, parent = NULL, halt = TRUE)
myDialog(message, default, title = 'rNMR', entryWidth = 20, parent = NULL)
myDir(initialdir = "", parent = NULL, title = "", mustexist = TRUE)
myMsg(message = "", type = "ok", icon = "question", title = "rNMR", 
	parent = NULL)
myOpen(defaultextension = "", filetypes = "", initialfile = "", initialdir = "", 
	multiple = TRUE, title = "", parent = NULL)
mySave(defaultextension = "", filetypes = "", initialfile = "", initialdir = "", 
	title = "", parent = NULL)
mySelect(list, preselect = NULL, multiple = FALSE, title = NULL, index = FALSE,
	parent = NULL)

Arguments

`message`	character string; message to display in the Tk dialog.
`buttons`	character string or vector; names for the buttons to display. If "Apply to all" is provided as the third option, a checbox will be displayed in the GUI with that label.
`default`	(`buttonDialog`)character string; specifies which of the buttons should be the default. This will be the active button when the dialog opens and will be the value returned if the dialog is closed without one of the other buttons being pressed. Must match one of the values in `button`.
`checkBox`	logical; if `TRUE` the last button in the dialog will be a checkbox.
`title`	character string; title for the dialog.
`parent`	optional Tk toplevel object to set as a parent window for the newly created dialog. If provided, the dialog will appear near its parent and will bring the parent toplevel object to the front. This is particularly useful for displaying message or error dialogs in response to user interactions within rNMR GUIs.
`halt`	logical; stops code execution if `TRUE`.
`default`	(`myDialog`) character string; default text to be displayed in the dialog's text entry box.
`entryWidth`	numeric; width of the text entry box in characters.
`initialdir`	character string; default directory path.
`title`	character string; title for the Tk dialog.
`mustexist`	logical; if `TRUE` the user must select a previously existing directory.
`type`	character string; the type of buttons to display in the dialog, must be one of "abortretryignore", "ok", "retrycancel", "okcancel", "yesno", or "yesnocancel".
`icon`	character string; icon to use in the dialog, must be one of "error", "info", "question" or "warning".
`defaultextension`	(`myOpen`) character string; a string specifying the file extension (without ".") for the default filetype to be displayed in the dialog (must match one of the extensions provided in `filetypes`)
`filetypes`	adds the provided file types to the file types listbox in the open dialog if supported by the platform. Must be in list format, for example: list(txt = "Text File", xls = "Excel File")
`initialfile`	character string; specifies a filename to be displayed initially in the dialog.
`multiple`	logical; if `TRUE`, allows users to select more than one file or list item.
`defaultextension`	(`mySave`) character string; a string specifying the file extension (without ".") to be appended to the file name if one is not provided.
`list`	character string or vector; items to display in the list box.
`preselect`	character string or vector; items to be preselected in the list box.
`index`	logical; if `TRUE`, the indices for the selected list items are returned, rather than the list items themselves.

Details

buttonDlg: Displays a dialog with a message and buttons. If checkBox is set to TRUE, the last button will be a checkbox with a label containing the last item in buttons. With this option enabled, the text associated with the button pressed to close the dialog will be returned along with either TRUE or FALSE to indicate whether or not the checkbox was checked when the button was pressed. This is useful when confirming multiple file overwrites.
err: Displays an error dialog and halts command execution.
myDialog: A Tk version of R's winDialogString; displays a dialog box with a text entry widget.
myDir: A Tk version of R's choose.dir; displays a directory selection dialog.
myMsg: Displays a dialog with customizable buttons, icon, and message.
myOpen and mySave: Display file open and save dialogs, respectively.
mySelect: A Tk version of R's select.list; displays a list selection dialog.

Value

buttonDlg, err, and myMsg return the text associated with the button pressed to close the dialog. If checkBox is set to TRUE in buttonDlg, the return value will be a data.frame with two values, the first being the button text, the second a logical value indicating whether or not the dialog's checkbox was checked when the user pressed one of the buttons. myDir, myOpen, and mySave return the selected file or directory name. mySelect returns the selected list items as a character vector.

Author(s)

Ian A. Lewis ialewis@nmrfam.wisc.edu, Seth C. Schommer schommer@nmrfam.wisc.edu