% File src/library/graphics/man/mtext.Rd
% Part of the R package, http://www.R-project.org
% Copyright 1995-2011 R Core Team
% Distributed under GPL 2 or later

\name{mtext}
\title{Write Text into the Margins of a Plot}
% mtext is defined via do_mtext(.) in  src/main/plot.c ---
\description{
  Text is written in one of the four margins of the current figure region
  or one of the outer margins of the device region.
}
\usage{
mtext(text, side = 3, line = 0, outer = FALSE, at = NA,
      adj = NA, padj = NA, cex = NA, col = NA, font = NA, \dots)
}
\alias{mtext}
\arguments{
  \item{text}{a character or \link{expression} vector specifying
    the \emph{text} to be written.  Other objects are coerced by
    \code{\link{as.graphicsAnnot}}.}
  \item{side}{on which side of the plot (1=bottom, 2=left, 3=top, 4=right).}
  \item{line}{on which MARgin line, starting at 0 counting outwards.}
  \item{outer}{use outer margins if available.}
  \item{at}{give location of each string in user coordinates.  If the
     component of \code{at} corresponding to a particular text item is
     not a finite value (the default), the location will be determined
     by \code{adj}.}
  \item{adj}{adjustment for each string in reading direction.  For
    strings parallel to the axes, \code{adj = 0} means left or bottom
    alignment, and \code{adj = 1} means right or top alignment.

    If \code{adj} is not a finite value (the default), the value of
    \code{par("las")} determines the adjustment.  For strings plotted
    parallel to the axis the default is to centre the string.}
  \item{padj}{adjustment for each string perpendicular to the reading
    direction (which is controlled by \code{adj}).  For strings parallel
    to the axes, \code{padj = 0} means right or top alignment,
    and \code{padj = 1} means left or bottom alignment.

    If \code{padj} is not a finite value (the default), the value of
    \code{par("las")} determines the adjustment.  For strings plotted
    perpendicular to the axis the default is to centre the string.}
  \item{cex}{character expansion factor.  \code{NULL} and \code{NA}
    are equivalent to \code{1.0}.  This is an absolute measure, not
    scaled by \code{par("cex")} or by setting \code{par("mfrow")}
    or \code{par("mfcol")}.  Can be a vector.}
  \item{col}{color to use.  Can be a vector.  \code{NA} values (the
    default) mean use \code{par("col")}.}
  \item{font}{font for text.  Can be a vector.  \code{NA} values (the
    default) mean use \code{par("font")}.}
  \item{\dots}{Further graphical parameters (see \code{\link{par}}),
    including \code{family}, \code{las} and \code{xpd}. (The latter
    defaults to the figure region unless \code{outer = TRUE}, otherwise
    the device region.  It can only be increased.)}
}
\details{
  The user coordinates in the outer margins always range from zero to
  one, and are not affected by the user coordinates in the figure
  region(s) --- \R differs here from other implementations of S.

  All of the named arguments can be vectors, and recycling will take
  place to plot as many strings as the longest of the vector arguments.

  Note that a vector \code{adj} has a different meaning from
  \code{\link{text}}.  \code{adj = 0.5} will centre the string, but for
  \code{outer = TRUE} on the device region rather than the plot region.

  Parameter \code{las} will determine the orientation of the string(s).
  For strings plotted perpendicular to the axis the default justification
  is to place the end of the string nearest the axis on the specified
  line.  (Note that this differs from S, which uses \code{srt} if
  \code{at} is supplied and \code{las} if it is not.  Parameter
  \code{srt} is ignored in \R.)

  Note that if the text is to be plotted perpendicular to the axis,
  \code{adj} determines the justification of the string \emph{and} the
  position along the axis unless \code{at} is specified.

  Graphics parameter \code{"ylbias"} (see \code{\link{par}}) determines
  how the text baseline is placed relative to the nominal line.
}
\section{Side Effects}{The given text is written onto the current plot.}
\references{
  Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)
  \emph{The New S Language}.
  Wadsworth & Brooks/Cole.
}
\seealso{
  \code{\link{title}}, \code{\link{text}}, \code{\link{plot}},
  \code{\link{par}};
  \code{\link{plotmath}} for details on mathematical annotation.
}
\examples{
plot(1:10, (-4:5)^2, main = "Parabola Points", xlab = "xlab")
mtext("10 of them")
for(s in 1:4)
    mtext(paste("mtext(..., line= -1, {side, col, font} = ", s,
          ", cex = ", (1+s)/2, ")"), line = -1,
          side = s, col = s, font = s, cex = (1+s)/2)
mtext("mtext(..., line= -2)", line = -2)
mtext("mtext(..., line= -2, adj = 0)", line = -2, adj = 0)
##--- log axis :
plot(1:10, exp(1:10), log = "y", main = "log =\"y\"", xlab = "xlab")
for(s in 1:4) mtext(paste("mtext(...,side=", s ,")"), side = s)
}
\keyword{aplot}