The R Project SVN R

% File src/library/utils/man/dataentry.Rd

% Part of the R package, http://www.R-project.org

% Copyright 1995-2009 R Core Team

% Distributed under GPL 2 or later

\name{dataentry}

\title{Spreadsheet Interface for Entering Data}

\usage{

data.entry(\dots, Modes = NULL, Names = NULL)

dataentry(data, modes)

de(\dots, Modes = list(), Names = NULL)

}

\alias{data.entry}

\alias{dataentry}

\alias{de}

\alias{de.ncols}

\alias{de.restore}

\alias{de.setup}

\description{

  A spreadsheet-like editor for entering or editing data.

}

\arguments{

  \item{\dots}{A list of variables: currently these should be numeric or

    character vectors or list containing such vectors.}

  \item{Modes}{The modes to be used for the variables.}

  \item{Names}{The names to be used for the variables.}

  \item{data}{A list of numeric and/or character vectors.}

  \item{modes}{A list of length up to that of \code{data} giving the

    modes of (some of) the variables. \code{list()} is allowed.}

}

\details{

  The data entry editor is only available on some platforms and GUIs.

  Where available it provides a means to visually edit a matrix or

  a collection of variables (including a data frame) as described in the

  Notes section.

  \code{data.entry} has side effects, any changes made in the

  spreadsheet are reflected in the variables.  The functions \code{de},

  \code{de.ncols}, \code{de.setup} and \code{de.restore} are designed to

  help achieve these side effects. If the user passes in a matrix,

  \code{X} say, then the matrix is broken into columns before

  \code{dataentry} is called. Then on return the columns are collected

  and glued back together and the result assigned to the variable

  \code{X}.  If you don't want this behaviour use dataentry directly.

  The primitive function is \code{dataentry}. It takes a list of

  vectors of possibly different lengths and modes (the second argument)

  and opens a spreadsheet with these variables being the columns.

  The columns of the dataentry window are returned as vectors in a

  list when the spreadsheet is closed.

  \code{de.ncols} counts the number of columns which are supplied as arguments

  to \code{data.entry}. It attempts to count columns in lists, matrices

  and vectors.  \code{de.setup} sets things up so that on return the

  columns can be regrouped and reassigned to the correct name. This

  is handled by \code{de.restore}.

}

\value{

  \code{de} and \code{dataentry} return the edited value of their

  arguments. \code{data.entry} invisibly returns a vector of variable

  names but its main value is its side effect of assigning new version

  of those variables in the user's workspace.

}

\note{

  The details of interface to the data grid may differ by platform and

  GUI.  The following description applies to

#ifdef unix

  the X11-based implementation under Unix.

#endif

#ifdef windows

  the GraphApp-based implementation under Windows.

#endif

  You can navigate around the grid using the cursor keys or by clicking

  with the (left) mouse button on any cell.  The active cell is

  highlighted by thickening the surrounding rectangle.  Moving to the

  right or down will scroll the grid as needed: there is no constraint

  to the rows or columns currently in use.

  There are alternative ways to navigate using the keys.  Return and

  (keypad) Enter and LineFeed all move down. Tab moves right and

  Shift-Tab move left.  Home moves to the top left.

  PageDown or Control-F moves down a page, and PageUp or

  Control-B up by a page.  End will show the last used column and the

  last few rows used (in any column).

  Using any other key starts an editing process on the currently

  selected cell: moving away from that cell enters the edited value

  whereas Esc cancels the edit and restores the previous value.  When

  the editing process starts the cell is cleared.

#ifdef windows

  The cursor changes to an I-beam to indicate that the cell is in enter mode.

#endif

  In numerical columns

  (the default) only letters making up a valid number (including

  \code{-.eE}) are accepted, and entering an invalid edited value (such

  as blank) enters \code{NA} in that cell.  The last entered value can

  be deleted using the  BackSpace or Del(ete) key.  Only a limited

  number of characters (currently 29) can be entered in a cell, and if

  necessary only the start or end of the string will be displayed, with the

  omissions indicated by \code{>} or \code{<}.  (The start is shown

  except when editing.)

#ifdef windows

  Double-clicking on a cell selects the cell and makes it into an

  editable field (a cursor will appear at the end of the text and it

  will change to the text highlight colour).  The edited text is

  entered by selecting another cell, for example by hitting Return.

  There is no way to cancel the edits.  The field will be expanded to

  the right if necessary to accommodate existing long strings, so it is

  preferable not to edit in the right-most displayed column.  (The

  editable field is itself scrollable.)

#endif

  Entering a value in a cell further down a column than the last used

  cell extends the variable and fills the gap (if any) by \code{NA}s (not

  shown on screen).

  The column names can only be selected by clicking in them.  This gives

  a popup menu to select the column type (currently Real (numeric) or

  Character) or to change the name.  Changing the type converts the

  current contents of the column (and converting from Character to Real

  may generate \code{NA}s.)

#ifdef unix

  If changing the name is selected the

  header cell becomes editable (and is cleared).  As with all cells, the

  value is entered by moving away from the cell by clicking elsewhere or

  by any of the keys for moving down (only).

#endif

#ifdef windows

  Enter the changes made in the popup window by clicking on its close box.

#endif

  New columns are created by entering values in them (and not by just

  assigning a new name).  The mode of the column is auto-detected from

  the first value entered: if this is a valid number it gives a numeric

  column.  Unused columns are ignored, so

  adding data in \code{var5} to a three-column grid adds one extra

  variable, not two.

#ifdef windows

  There is a popup-menu accessed by right-clicking anywhere in the window

  that refers to the currently selected cell. This can copy the value to

  or paste from the clipboard, or paste in common values in that column.

  Copying and pasting can also be accessed by the usual keyboard shortcuts

  Control-C and Control-V.

  Columns can be resized by selecting and dragging a line (the cursor

  will change) within limits: columns must be between 4 and 50 chars wide.

  The Autosize item on the popup menu will resize the currently selected

  column.

#endif

#ifdef unix

  The \code{Copy} button copies the currently selected cell:

  \code{paste} copies the last copied value to the current cell, and

  right-clicking selects a cell \emph{and} copies in the value.

  Initially the value is blank, and attempts to paste a blank value will

  have no effect.

#endif

  Control-L will refresh the display, recalculating field widths to fit

  the current entries.

  In the default mode the column widths are chosen to fit the contents

  of each column, with a default of 10 characters for empty columns.

  you can specify fixed column widths by setting option

  \code{de.cellwidth} to the required fixed width (in characters).

  (set it to zero to return to variable widths).  The displayed

  width of any field is limited to

#ifdef unix

  600 pixels (and by the window width).

#endif

#ifdef windows

  50 characters (and by the window width).

  The initial size of the data editor window is taken from the default

  dimensions of a pager (see \code{\link{Rconsole}}), but adjusted

  downwards to show a whole number of rows and columns.

#endif

}

#ifdef unix

\section{Resources}{

  The data entry window responds to X resources of class

  \code{R_dataentry}.  Resources \code{foreground}, \code{background} and

  \code{geometry} are utilized.

}

#endif

\seealso{

  \code{\link{vi}}, \code{\link{edit}}: \code{edit} uses

  \code{dataentry} to edit data frames.

}

\examples{

# call data entry with variables x and y

\dontrun{data.entry(x, y)}

}

\keyword{utilities}

\keyword{file}