Rcmdr (version 0.9-10)

Rcmdr.Utilities: Rcmdr Utility Functions

Description

These functions support writing additions to the Rcmdr package. Additional R code can be placed in files with file type .R in the etc subdirectory of the package. Add menus, submenus, and menu items by editing the file Rcmdr-menus.txt in the same directory.

Usage

activeDataSet(dsname)
activeModel(model)
checkActiveDataSet()
checkActiveModel()
checkBoxes(window=top, frame, boxes, initialValues=NULL, labels)  # macro
checkFactors(n=1)
checkNumeric(n=1)
checkReplace(name, type="Variable")
checkTwoLevelFactors(n=1)
checkVariables(n=1)
dialogSuffix(window=top, onOK=onOK, rows=1, columns=1, focus=top, bindReturn=TRUE, 
    preventGrabFocus=FALSE)  # macro
doItAndPrint(command)
errorCondition(window=top, recall=NULL, message, model=FALSE)  # macro
## S3 method for class 'listbox':
getFrame(object)
## S3 method for class 'listbox':
getSelection(object)
groupsBox(recall=NULL, label="Plot by:", initialLabel="Plot by groups",
    plotLinesByGroup=FALSE, positionLegend=FALSE, 
    plotLinesByGroupsText="Plot lines by group")  # macro
groupsLabel(frame=top, groupsBox=groupsBox, columnspan=1)  # macro
justDoIt(command)
initializeDialog(window=top, title="")  # macro
is.valid.name(x)
listDataSets(envir = .GlobalEnv, ...)
listFactors(dataSet=.activeDataSet)
listGeneralizedLinearModels(envir = .GlobalEnv, ...)
listLinearModels(envir = .GlobalEnv, ...)
listNumeric{dataSet=.activeDataSet}
listTwoLevelFactors(dataSet=.activeDataSet)
listVariables(dataSet=.activeDataSet)
logger(command)
modelFormula(frame=top, hasLhs=TRUE)  # macro
OKCancelHelp(window=top, helpSubject=NULL, model=FALSE)  # macro
radioButtons(window=top, name, buttons, values=NULL, initialValue=..values[1], 
    labels, title)  # macro
subOKCancelHelp(window=subdialog, helpSubject=NULL)  # macro
subsetBox(window=top, model=FALSE)  # macro
variableListBox(parentWindow, variableList=.variables, bg="white",
    selectmode="single", export="FALSE", initialSelection=NULL, title)

Arguments

bg
background color.
bindReturn
if TRUE, the Return key is bound to the onOK function in the dialog.
boxes
vector of quoted names for check boxes, used to generate each box and its associated variable.
buttons
vector of quoted names for buttons in a set of related radio buttons.
columnspan
number of dialog-box columns to be spanned by frame.
command
a character string that evaluates to an R command.
dataSet, dsname
the quoted name of a data frame in memory.
envir
the environment to be searched; should generally be left at the default.
export
export selection?
focus
Tk window to get the focus.
frame
frame or quoted name for frame depending upon the function.
groupsBox
listbox object for selecting groups variable.
hasLhs
does the model formula have a left-hand side?
helpSubject
the quoted name of a help subject, to be called as help(helpSubject) when the dialog Help button is pressed.
initialLabel
label for groups button before a selection is made.
initialSelection
index of item initially selected, 0-base indexing.
initialValue
for a set of related radio buttons.
initialValues
for a set of related check boxes.
label
label prefix for groups button after a selection is made.
labels
A vector of character strings to label a set of radio buttons or check boxes.
message
error message.
model
the name of a model, as a character string, or TRUE or FALSE, depending upon the function.
name
quoted name.
n
number of variables to check for.
object
a listbox object.
onOK
function to execute when the OK button is pressed.
plotLinesByGroup
include a check box for plotting lines by group?
plotLinesByGroupsText
the label for the plot-lines-by-group check box.
positionLegend
include a check box for a legend?
preventGrabFocus
prevent the dialog box from grabbing the focus.
recall
function to call after error --- usually the function that initiates the dialog.
rows, columns
numbers of rows and columns of widgets in the dialog box.
values
vector of quoted values associated with radio buttons or check boxes.
selectmode
"single" or "multiple".
title
Window or dialog-box-element title.
type
quoted type of object to check; used to generate check-replace dialog box.
variableList
a vector of variable names.
window, parentWindow
a Tk window.
x
a putative R object name, as a character string.
...
Disregard.

Details

There are several groups of functions exported by the Rcmdr package and documented briefly here. To see how these functions work, it is simplest to examine the dialog-generating functions in the Rcmdr package. Executing and logging commands: The functions doItAndPrint, justDoIt, and logger control the execution, logging, and printing of commands generated by menus and dialogs. logger(command) adds command to the log/script window and to the output window. justDoIt(command) causes command to be executed. doItAndPrint(command) does both of these operations. Checking for errors: The function is.valid.name checks whether a character string specifies a valid name for an R object. The functions checkActiveDataSet, checkActiveModel, checkFactors, checkNumeric, checkTwoLevelFactors, and checkVariables check for the existence of objects and bring up an error-information dialog if they are absent (or insufficiently numerous, in the case of different kinds of variables). The function checkReplace opens a dialog to query whether an existing object should be replaced. The function errorCondition reports an error to the user and (optionally) re-starts a dialog. Information: Several functions return vectors of object names: listDataSets, listGeneralizedLinearModels, listFactors, listLinearModels, listNumeric, listTwoLevelFactors, listVariables. The functions activeDataSet and activeModel respectively report or set the active data set and model. Building dialog boxes: Several functions simplify the process of constructing Tk dialogs: initializing a dialog box, initializeDialog, and completing the definition of a dialog box, dialogSuffix; a set of check boxes, checkBoxes; a set of radio buttons, radioButtons; a list box with associated scrollbars and state variable, variableListBox (and the associated functions getFrame and getSelection); a button and subdialog for selecting a "grouping" variable, groupsBox; displaying the currently defined groups in a dialog, groupsLabel; a dialog-box structure for entering a model formula, modelFormula; a text box for entering a subsetting expression, subsetBox; OK, Cancel, and Help buttons for dialogs, OKCancelHelp, and subdialogs, subOKCancelHelp. Some of these functions, marked # macro under Usage, are "macro-like" in their behaviour, in that they execute in the environment from which they are called. These were defined with an adaptation (used with permission) of Thomas Lumley's defmacro function, described in Lumley (2001).

References

T. Lumley (2001) Programmer's niche: Macros in R. R News, 1(3), 11--13.