1% File src/library/grid/man/grid.convert.Rd
2% Part of the R package, https://www.R-project.org
3% Copyright 1995-2013 R Core Team
4% Distributed under GPL 2 or later
5
6\name{grid.convert}
7\alias{convertUnit}
8\alias{convertX}
9\alias{convertY}
10\alias{convertWidth}
11\alias{convertHeight}
12\title{ Convert Between Different grid Coordinate Systems }
13\description{
14  These functions take a unit object and convert it to an
15  equivalent
16  unit object in a different coordinate system.
17}
18\usage{
19convertX(x, unitTo, valueOnly = FALSE)
20convertY(x, unitTo, valueOnly = FALSE)
21convertWidth(x, unitTo, valueOnly = FALSE)
22convertHeight(x, unitTo, valueOnly = FALSE)
23convertUnit(x, unitTo,
24             axisFrom = "x", typeFrom = "location",
25             axisTo = axisFrom, typeTo = typeFrom,
26             valueOnly = FALSE)
27}
28\arguments{
29  \item{x}{ A unit object. }
30  \item{unitTo}{ The coordinate system to convert the unit to.
31    See the \code{\link{unit}} function for valid coordinate systems.}
32  \item{axisFrom}{ Either \code{"x"} or \code{"y"} to indicate
33    whether the unit object represents a value in the x- or
34    y-direction. }
35  \item{typeFrom}{ Either \code{"location"} or \code{"dimension"}
36    to indicate whether the unit object represents a location or a
37    length. }
38  \item{axisTo}{ Same as \code{axisFrom}, but applies to the unit object
39    that is to be created. }
40  \item{typeTo}{ Same as \code{typeFrom}, but applies to the unit object
41    that is to be created. }
42  \item{valueOnly}{ A logical indicating.  If \code{TRUE} then
43    the function does not return a unit object, but rather only the
44    converted numeric values. }
45}
46\details{
47  The \code{convertUnit} function allows for general-purpose
48  conversions.  The other four functions are just more convenient
49  front-ends to it for the most common conversions.
50
51  The conversions occur within the current viewport.
52
53  It is not currently possible to convert to all valid coordinate systems
54  (e.g., "strwidth" or "grobwidth").  I'm not sure if all of these
55  are impossible, they just seem implausible at this stage.
56
57  In normal usage of grid, these functions should not be necessary.
58  If you want to express a location or dimension in inches rather
59  than user coordinates then you should simply do something like
60  \code{unit(1, "inches")} rather than something like
61  \code{unit(0.134, "native")}.
62
63  In some cases, however, it is necessary for the user to
64  perform calculations on a unit value and this function becomes
65  necessary.  In such cases, please take note of the warning below.
66}
67\value{
68  A unit object in the specified coordinate system
69  (unless \code{valueOnly} is \code{TRUE} in which case
70  the returned value is a numeric).
71}
72\author{ Paul Murrell }
73
74\section{Warning}{
75  The conversion is only valid for the current device size.
76  If the device is resized then at least some conversions will
77  become invalid.  For example, suppose that I create a unit
78  object as follows: \code{oneinch <- convertUnit(unit(1, "inches"),
79    "native")}.  Now if I resize the device, the unit object in
80  oneinch no longer corresponds to a physical length of 1 inch.
81  }
82\seealso{ \code{\link{unit}} }
83\examples{
84## A tautology
85convertX(unit(1, "inches"), "inches")
86## The physical units
87convertX(unit(2.54, "cm"), "inches")
88convertX(unit(25.4, "mm"), "inches")
89convertX(unit(72.27, "points"), "inches")
90convertX(unit(1/12*72.27, "picas"), "inches")
91convertX(unit(72, "bigpts"), "inches")
92convertX(unit(1157/1238*72.27, "dida"), "inches")
93convertX(unit(1/12*1157/1238*72.27, "cicero"), "inches")
94convertX(unit(65536*72.27, "scaledpts"), "inches")
95convertX(unit(1/2.54, "inches"), "cm")
96convertX(unit(1/25.4, "inches"), "mm")
97convertX(unit(1/72.27, "inches"), "points")
98convertX(unit(1/(1/12*72.27), "inches"), "picas")
99convertX(unit(1/72, "inches"), "bigpts")
100convertX(unit(1/(1157/1238*72.27), "inches"), "dida")
101convertX(unit(1/(1/12*1157/1238*72.27), "inches"), "cicero")
102convertX(unit(1/(65536*72.27), "inches"), "scaledpts")
103
104pushViewport(viewport(width=unit(1, "inches"),
105                       height=unit(2, "inches"),
106                       xscale=c(0, 1),
107                       yscale=c(1, 3)))
108  ## Location versus dimension
109  convertY(unit(2, "native"), "inches")
110  convertHeight(unit(2, "native"), "inches")
111  ## From "x" to "y" (the conversion is via "inches")
112  convertUnit(unit(1, "native"), "native",
113               axisFrom="x", axisTo="y")
114  ## Convert several values at once
115  convertX(unit(c(0.5, 2.54), c("npc", "cm")),
116                c("inches", "native"))
117popViewport()
118## Convert a complex unit
119convertX(unit(1, "strwidth", "Hello"), "native")
120}
121\keyword{dplot}
122