Rcmdr.Utilities {Rcmdr} | R Documentation |
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.
activeDataSet(dsname, flushModel=TRUE) 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, log=TRUE) 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, listHeight = 4, title)
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? |
flushModel |
set (or reset) the active model to NULL? Should normally be TRUE when the active
data set is changed; an exception is when variables are simply added to, deleted from, or modified in
the data set set. |
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. |
listHeight |
Maximum number of elements displayed simultaneously in list box. |
log |
echo command to the log window, as well as executing it and printing its output. |
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. |
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, and also prints the
output produced by the command.
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).
John Fox jfox@mcmaster.ca
T. Lumley (2001) Programmer's niche: Macros in R. R News, 1(3), 11–13.