% File src/library/grid/man/grid.convert.Rd
% Part of the R package, https://www.R-project.org
% Copyright 1995-2013 R Core Team
% Distributed under GPL 2 or later

\name{grid.convert}
\alias{convertUnit}
\alias{convertX}
\alias{convertY}
\alias{convertWidth}
\alias{convertHeight}
\title{ Convert Between Different grid Coordinate Systems }
\description{
  These functions take a unit object and convert it to an
  equivalent
  unit object in a different coordinate system.
}
\usage{
convertX(x, unitTo, valueOnly = FALSE)
convertY(x, unitTo, valueOnly = FALSE)
convertWidth(x, unitTo, valueOnly = FALSE)
convertHeight(x, unitTo, valueOnly = FALSE)
convertUnit(x, unitTo,
             axisFrom = "x", typeFrom = "location",
             axisTo = axisFrom, typeTo = typeFrom,
             valueOnly = FALSE)
}
\arguments{
  \item{x}{ A unit object. }
  \item{unitTo}{ The coordinate system to convert the unit to.
    See the \code{\link{unit}} function for valid coordinate systems.}
  \item{axisFrom}{ Either \code{"x"} or \code{"y"} to indicate
    whether the unit object represents a value in the x- or
    y-direction. }
  \item{typeFrom}{ Either \code{"location"} or \code{"dimension"}
    to indicate whether the unit object represents a location or a
    length. }
  \item{axisTo}{ Same as \code{axisFrom}, but applies to the unit object
    that is to be created. }
  \item{typeTo}{ Same as \code{typeFrom}, but applies to the unit object
    that is to be created. }
  \item{valueOnly}{ A logical indicating.  If \code{TRUE} then
    the function does not return a unit object, but rather only the
    converted numeric values. }
}
\details{
  The \code{convertUnit} function allows for general-purpose
  conversions.  The other four functions are just more convenient
  front-ends to it for the most common conversions.

  The conversions occur within the current viewport.

  It is not currently possible to convert to all valid coordinate systems
  (e.g., "strwidth" or "grobwidth").  I'm not sure if all of these
  are impossible, they just seem implausible at this stage.

  In normal usage of grid, these functions should not be necessary.
  If you want to express a location or dimension in inches rather
  than user coordinates then you should simply do something like
  \code{unit(1, "inches")} rather than something like
  \code{unit(0.134, "native")}.

  In some cases, however, it is necessary for the user to
  perform calculations on a unit value and this function becomes
  necessary.  In such cases, please take note of the warning below.
}
\value{
  A unit object in the specified coordinate system
  (unless \code{valueOnly} is \code{TRUE} in which case
  the returned value is a numeric).
}
\author{ Paul Murrell }

\section{Warning}{
  The conversion is only valid for the current device size.
  If the device is resized then at least some conversions will
  become invalid.  For example, suppose that I create a unit
  object as follows: \code{oneinch <- convertUnit(unit(1, "inches"),
    "native")}.  Now if I resize the device, the unit object in
  oneinch no longer corresponds to a physical length of 1 inch.
  }
\seealso{ \code{\link{unit}} }
\examples{
## A tautology
convertX(unit(1, "inches"), "inches")
## The physical units
convertX(unit(2.54, "cm"), "inches")
convertX(unit(25.4, "mm"), "inches")
convertX(unit(72.27, "points"), "inches")
convertX(unit(1/12*72.27, "picas"), "inches")
convertX(unit(72, "bigpts"), "inches")
convertX(unit(1157/1238*72.27, "dida"), "inches")
convertX(unit(1/12*1157/1238*72.27, "cicero"), "inches")
convertX(unit(65536*72.27, "scaledpts"), "inches")
convertX(unit(1/2.54, "inches"), "cm")
convertX(unit(1/25.4, "inches"), "mm")
convertX(unit(1/72.27, "inches"), "points")
convertX(unit(1/(1/12*72.27), "inches"), "picas")
convertX(unit(1/72, "inches"), "bigpts")
convertX(unit(1/(1157/1238*72.27), "inches"), "dida")
convertX(unit(1/(1/12*1157/1238*72.27), "inches"), "cicero")
convertX(unit(1/(65536*72.27), "inches"), "scaledpts")

pushViewport(viewport(width=unit(1, "inches"),
                       height=unit(2, "inches"),
                       xscale=c(0, 1),
                       yscale=c(1, 3)))
  ## Location versus dimension
  convertY(unit(2, "native"), "inches")
  convertHeight(unit(2, "native"), "inches")
  ## From "x" to "y" (the conversion is via "inches")
  convertUnit(unit(1, "native"), "native",
               axisFrom="x", axisTo="y")
  ## Convert several values at once
  convertX(unit(c(0.5, 2.54), c("npc", "cm")),
                c("inches", "native"))
popViewport()
## Convert a complex unit
convertX(unit(1, "strwidth", "Hello"), "native")
}
\keyword{dplot}