\HeaderA{textplot}{Display text information in a graphics plot.}{textplot}
\aliasA{replaceTabs}{textplot}{replaceTabs}
\methaliasA{textplot.character}{textplot}{textplot.character}
\methaliasA{textplot.data.frame}{textplot}{textplot.data.frame}
\methaliasA{textplot.default}{textplot}{textplot.default}
\methaliasA{textplot.matrix}{textplot}{textplot.matrix}
\keyword{hplot}{textplot}
\begin{Description}\relax
This function displays text output in a graphics window.  It is the equivalent of 'print' except that the output is displayed as a plot.
\end{Description}
\begin{Usage}
\begin{verbatim}
textplot(object, halign="center", valign="center", cex, ...)
## Default S3 method:
textplot(object, halign=c("center","left","right"),
         valign=c("center", "top", "bottom"), cex, ... )
## S3 method for class 'character':
textplot(object, halign = c("center", "left", "right"),
         valign = c("center", "top", "bottom"), cex, fixed.width=TRUE,
         cspace=1, lspace=1, mar=c(0, 0, 3, 0) + 0.1,
         tab.width = 8, ...)
## S3 method for class 'data.frame':
textplot(object, halign = c("center", "left", "right"),
         valign = c("center", "top", "bottom"), cex, ...)
## S3 method for class 'matrix':
textplot(object, halign = c("center", "left", "right"), valign = c("center", "top", "bottom"), cex, max.cex = 1, cmar = 2, rmar = 0.5, show.rownames = TRUE, show.colnames = TRUE, hadj = 1, vadj=NULL, row.valign = "center", heading.valign = "bottom", mar = c(0, 0, 0, 0) + 0.1, col.data = par("col"), col.rownames = par("col"), col.colnames = par("col"), wrap = TRUE, wrap.colnames = 10, wrap.rownames = 10, ...) 
replaceTabs(text, width=8)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{object}] Object to be displayed.
\item[\code{halign}] Alignment in the x direction, one of "center", "left",
or "right". 
\item[\code{valign}] Alignment in the y direction, one of "center", "top" ,
or "bottom"
\item[\code{cex}] Character size, see \code{\LinkA{par}{par}} for details. If
unset, the code will attempt to use the largest value which allows
the entire object to be displayed.
\item[\code{fixed.width}] Logical value indicating whether to emulate a
fixed-width font by aligning characters in each row of text. This is
usually necessary for text-formatted tables display properly.
Defaults to 'TRUE'.
\item[\code{cspace}] Space between characters as a
multiple of the width of the letter 'W'. This only applies when 
\code{fixed.width==TRUE}. 
\item[\code{lspace}] Line spacing. This only applies when
\code{fixed.width==TRUE}.
\item[\code{mar}] Figure margins, see the documentation for \code{par}.
\item[\code{rmar, cmar}] Space between rows or columns, in
fractions of the size of the letter 'M'.
\item[\code{show.rownames, show.colnames}] Logical value indicating whether row or
column names will be displayed.
\item[\code{hadj,vadj}] Vertical and horizontal location of elements within
matrix cells.  These have the same meaning as the \code{adj} graphics
paramter (see \code{\LinkA{par}{par}}).
\item[\code{col.data}] Colors for data elements.  If a single value is
provided, all data elements will be the same color.  If a matrix
matching the dimensions of the data is provided, each data element
will receive the specified color.
\item[\code{col.rownames, col.colnames}] Colors for row names and column
names, respectively.  Either may be specified as a scalar or a
vector of appropriate length.
\item[\code{tab.width}] Width of a single tab stop, in characters
\item[\code{max.cex}] Sets the largest text size as a ceiling
\item[\code{row.valign}] Sets the vertical alignment of the row as "top", "bottom", or (default) "center".
\item[\code{heading.valign}] Sets the vertical alignment of the heading as "top", (default) "bottom", or "center".
\item[\code{wrap}] If TRUE (default), will wrap column names and rownames 
\item[\code{wrap.colnames}] The number of characters after which column labels will be wrapped.  Default is 10. 
\item[\code{wrap.rownames}] The number of characters after which row headings will be wrapped.  Default is 10. 
\item[\code{text}] in the function 'replaceTabs', the text string to be processed 
\item[\code{width}] in the function 'replaceTabs', the number of spaces to replace tabs with 
\item[\code{...}] Optional arguments passed to the text plotting command or specialized object methods
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
A new plot is created and the object is displayed
using the largest font that will fit on in the plotting region.  The
\code{halign} and \code{valign} parameters can be used to control the
location of the string within the plotting region.

For matrixes and vectors a specialized textplot function is available, which plots each of the cells individually, with column widths set
according to the sizes of the column elements.  If present, row and
column labels will be displayed in a bold font.  

textplot also uses replaceTabs, a function to replace all tabs in a string with an appropriate number of spaces.  That function was also written by Gregory R. Warnes and included in the 'gplots' package.
\end{Details}
\begin{Value}
The character scaling factor (\code{cex}) used.
\end{Value}
\begin{Author}\relax
Originally written by Gregory R. Warnes \email{warnes@bst.rochester.edu} for the package 'gplots', modified by Peter Carl
\end{Author}
\begin{SeeAlso}\relax
\code{\LinkA{plot}{plot}}, \code{\LinkA{text}{text}}, 
\code{\LinkA{capture.output}{capture.output}, \bsl{}code\{\LinkA{capture.output}{capture.output}\} 
        }
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
## Not run: 
### simple examples
# show R version information
textplot(version)

# show the alphabet as a single string
textplot( paste(letters[1:26], collapse=" ") )

# show the alphabet as a matrix
textplot( matrix(letters[1:26], ncol=2))

### Make a nice 4 way display with two plots and two text summaries

data(iris)
par(mfrow=c(2,2))
plot( Sepal.Length ~ Species, data=iris, border="blue", col="cyan",
      main="Boxplot of Sepal Length by Species" )
plotmeans( Sepal.Length ~ Species, data=iris, barwidth=2, connect=FALSE,
           main="Means and 95% Confidence Intervals\nof Sepal Length by Species")

info <- sapply( split(iris$Sepal.Length, iris$Species),
                function(x) round(c(Mean=mean(x), SD=sd(x), N=gdata::nobs(x)),2) )

textplot( info, valign="top"  )
title("Sepal Length by Species")

reg <- lm( Sepal.Length ~ Species, data=iris )
textplot( capture.output(summary(reg)), valign="top")
title("Regression of Sepal Length by Species")

par(mfrow=c(1,1))

### Show how to control text color
cols <- c("red", "green", "magenta", "forestgreen")
mat <- cbind(name=cols, t(col2rgb(cols)), hex=col2hex(cols))

textplot(mat,
         col.data=matrix(cols, nrow=length(cols), byrow=FALSE, ncol=5),
         )

### Show how to manually tune the character size
data(iris)
reg <- lm( Sepal.Length ~ Species, data=iris )
text <- capture.output(summary(reg))

# do the plot and capture the character size used
textplot(text, valign="top")

# see what size was used
cex

# now redo the plot at 80% size
textplot( text, valign="top", cex=cex*0.80)


## End(Not run)
\end{ExampleCode}
\end{Examples}

