\name{Grid}
\alias{Grid}
\title{Grid Graphics}
\description{
  General information about the grid graphics package.
}
\details{
  Grid graphics provides an alternative to the standard R graphics.
  The user is able to define arbitrary rectangular regions (called
  \emph{viewports}) on the graphics device and define a number of
  coordinate systems for each region.  Drawing can be specified to occur
  in any viewport using any of the available coordinate systems.
  
  Grid graphics and standard R graphics do not mix!

  Type \code{library(help = grid)} to see a list of (public)
  Grid graphics functions.
}
\author{Paul Murrell}
\seealso{
  \code{\link{viewport}},
  \code{\link{grid.layout}}, and
  \code{\link{unit}}.
}
\examples{
## Diagram of a simple layout 
grid.show.layout(grid.layout(4,2,
                     heights=unit(rep(1, 4),
                                  c("lines", "lines", "lines", "null")),
                     widths=unit(c(1, 1), "inches")))
## Diagram of a sample viewport
grid.show.viewport(viewport(x=0.6, y=0.6,
                            w=unit(1, "inches"), h=unit(1, "inches")))
## A flash plotting example
grid.multipanel(vp=viewport(0.5, 0.5, 0.8, 0.8))
}
\keyword{dplot}
\eof
\name{absolute.size}
\alias{absolute.size}
\title{ Absolute Size of a Grob }
\description{
  This function converts a unit object into absolute units.
  Absolute units are unaffected, but non-absolute units are
  converted into \code{"null"} units.
}
\usage{
absolute.size(unit)
}
\arguments{
  \item{unit}{ An object of class \code{"unit"}. }
}
\details{
  Absolute units are things like \code{"inches"}, \code{"cm"},
  and \code{"lines"}.  Non-absolute units are \code{"npc"}
  and \code{"native"}.

  This function is designed to be used in \code{width.details}
  and \code{height.details} methods.
}
\value{
  An object of class \code{"unit"}.
}
\author{ Paul Murrell }
\seealso{
  The code for \code{width.details}
  and \code{height.details} methods.

  The file \file{grid/doc/notes/parentchild.ps}.
}
\keyword{ dplot }
\eof
\name{convertNative}
\alias{convertNative}
\title{ Convert a Unit Object to Native units }
\description{
  \bold{This function is deprecated in grid version 0.8 and will be
    made defunct in grid version 0.9}

  You should use the \code{grid.convert()} function or one of its
  close allies instead.
  
  This function returns a numeric vector containing the specified
  x or y locations or dimensions, converted to "user" or "data"
  units, relative to the current viewport.
}
\usage{
convertNative(unit, dimension="x", type="location")
}
\arguments{
  \item{unit}{ A unit object. }
  \item{dimension}{ Either "x" or "y". }
  \item{type}{ Either "location" or "dimension". }
}
\value{
  A numeric vector.
}
\author{ Paul Murrell }
\section{WARNING }{ If you draw objects based on output from these conversion
    functions, then resize your device, the objects will be drawn 
    incorrectly -- the base R display list will not recalculate these
    conversions.  This means that you can only rely on the results of 
    these calculations if the size of your device is fixed.} 
\seealso{ \code{\link{grid.convert}}, \code{\link{unit}} }

\examples{
grid.newpage()
push.viewport(viewport(width=unit(.5, "npc"),
                       height=unit(.5, "npc")))
grid.rect()
w <- convertNative(unit(1, "inches"))
h <- convertNative(unit(1, "inches"), "y")
# This rectangle starts off life as 1in square, but if you
# resize the device it will no longer be 1in square
grid.rect(width=unit(w, "native"), height=unit(h, "native"),
          gp=gpar(col="red"))
pop.viewport(1)

# How to use grid.convert(), etc instead
convertNative(unit(1, "inches")) ==
  grid.convertX(unit(1, "inches"), "native", valueOnly=TRUE)
convertNative(unit(1, "inches"), "y", "dimension") ==
  grid.convertHeight(unit(1, "inches"), "native", valueOnly=TRUE)
}
\keyword{ dplot }
\eof
\name{current.viewport}
\alias{current.viewport}
\title{Get the Default Grid Viewport}
\description{
  Returns the viewport that Grid is going to draw into.
}
\usage{
current.viewport(vp=NULL)
}
\arguments{
  \item{vp}{A Grid viewport object.}
}
\details{
  This function should only be used without the \code{vp}
  argument (i.e., only to return the current viewport).

  The \code{vp} argument only exists for historical reasons.
  It will be removed in future versions.
}
\value{
  A Grid viewport object.
}
\author{Paul Murrell}
\seealso{
  \code{\link{viewport}}
}
\keyword{dplot}
\eof
\name{dataViewport}
\alias{dataViewport}
\title{ Create a Viewport with Scales based on Data }
\description{
  This is a convenience function for producing a viewport with
  x- and/or y-scales based on numeric values passed to the function.
}
\usage{
dataViewport(xData = NULL, yData = NULL, xscale = NULL, yscale = NULL,
             extension = 0.05, ...)
}
\arguments{
  \item{xData}{ A numeric vector of data. }
  \item{yData}{ A numeric vector of data. }
  \item{xscale}{ A numeric vector (length 2). }
  \item{yscale}{ A numeric vector (length 2). }
  \item{extension}{ A numeric. }
  \item{\dots}{ All other arguments will be passed to a call to
    the \code{viewport()} function. }
}
\details{
  If \code{xscale} is not specified then the values in \code{x} are
  used to generate an x-scale based on the range of \code{x}, extended
  by the proportion specified in \code{extension}.  Similarly for the
  y-scale.
}
\value{
  A grid viewport object.
}
\author{ Paul Murrell }
\seealso{
  \code{\link{viewport}} and
  \code{\link{plotViewport}}.
}
\keyword{dplot}
\eof
\name{gpar}
\alias{gpar}
\title{Function to produce a Graphical Parameter Object}
\description{
  This function returns an object of class \code{"gpar"}.  This is
  basically a list of name-value pairs.
}
\usage{
gpar(...)
}
\arguments{
  \item{\dots}{ Any number of named arguments. }
}
\details{
  All grid viewports and (predefined) graphical objects have a slot
  called \code{gp}, which contains a \code{"gpar"} object.  When
  a viewport is pushed onto the viewport stack and when a graphical object
  is drawn, the settings in the \code{"gpar"} object are enforced.
  In this way, the graphical output is modified by the \code{gp}
  settings until the graphical object has finished drawing, or until the
  viewport is popped off the viewport stack, or until some other
  viewport or graphical object is pushed or begins drawing.

  Valid parameter names are:
  \tabular{ll}{
    col \tab Colour for lines and borders. \cr
    fill \tab Colour for filling rectangles, polygons, ... \cr
    lty \tab Line type \cr
    lwd \tab Line width \cr
    fontsize \tab The size of text (in points) \cr
    fontfamily \tab The font family \cr
    fontface \tab The font face (bold, italic, ...) \cr
    lineheight \tab The height of a line as a multiple of fontsize \cr
    font \tab Font face (alias for fontface;  for
    backward compatibility) \cr
  }

  For most devices, the \code{fontfamily} is specified when the device
  is first opened and may not be changed thereafter -- i.e., specifying
  a different font family via \code{fontfamily} will be ignored.  This
  will hopefully change in future versions of R.  Also, there is an
  important exception:  \code{fontfamily} may be used to specify one
  of the Hershey Font families (e.g., \code{HersheySerif})
  and this specification will be honoured
  on all devices.

  The specification of \code{fontface} follows the R base graphics
  standard:  1 = plain, 2 = bold, 3 = italic, 4 = bold italic.
  
  Specifying the value \code{NULL} for a parameter is the same as not
  specifying any value for that parameter, except for \code{col} and
  \code{fill}, where \code{NULL} indicates not to draw a border or
  not to fill an area (respectively).

  All parameter values can be vectors of multiple values.  (This will
  not always make sense -- for example, viewports will only take
  notice of the first parameter value.)
}
\value{
  An object of class \code{"gpar"}.
}
\seealso{
  \code{\link{Hershey}}.
}
\author{Paul Murrell}
\examples{
gpar(col = "red")
gpar(col = "blue", lty = "solid", lwd = 3, fontsize = 16)
grid.newpage()
vp <- viewport(w = .8, h = .8, gp = gpar(col="blue"))
grid.collection(grid.rect(gp = gpar(col="red"), draw = FALSE),
                grid.text(paste("The rect is its own colour (red)",
                                "but this text is the colour",
                                "set by the collection (green)", sep = "\n"),
                          draw = FALSE),
                gp = gpar(col="green"), vp = vp)
grid.text("This text is the colour set by the viewport (blue)",
          y = 1, just = c("center", "bottom"),
          gp = gpar(fontsize=20), vp = vp)
grid.newpage()
## example with multiple values for a parameter
push.viewport(viewport())
grid.points(1:10/11, 1:10/11, gp = gpar(col=1:10))
pop.viewport()
}
\keyword{ dplot }
\eof
\name{grid-internal}
%% <FIXME>
%% These had aliases but no corresponding code object:
%% <LIST>
%% \alias{.unit}
%% \alias{.unit.arithmetic}
%% \alias{.unit.list}
%% \alias{clear.display.list}
%% \alias{clearpage}
%% \alias{common.draw.axis}
%% \alias{convert.gpar}
%% \alias{copy}
%% \alias{demo.locator}
%% \alias{editDetails.frame}
%% \alias{grid.height}
%% \alias{grid.init.viewport.stack}
%% \alias{height.default}
%% \alias{height.frame}
%% \alias{height.lines}
%% \alias{height.text}
%% \alias{justifyX}
%% \alias{justifyY}
%% \alias{pop.saved.Rpars}
%% \alias{push.saved.Rpars}
%% \alias{set.viewport}
%% \alias{stack.viewports}
%% \alias{unit.list.c}
%% \alias{unstack.viewports}
%% \alias{viewport.layout<-}
%% \alias{width.default}
%% \alias{width.frame}
%% \alias{width.lines}
%% \alias{width.text}
%% \alias{grid.width}
%% </LIST>
%% </FIXME>

%% These are now registered but unexported S3 methods:
%% <LIST>
%% \alias{[.unit}
%% \alias{[.unit.arithmetic}
%% \alias{[.unit.list}
%% \alias{Ops.unit}
%% \alias{Summary.unit}
%% \alias{as.character.unit}
%% \alias{as.character.unit.arithmetic}
%% \alias{as.character.unit.list}
%% \alias{print.grob}
%% \alias{print.unit}
%% \alias{print.viewport}
%% \alias{draw.details.arrows}
%% \alias{draw.details.circle}
%% \alias{draw.details.collection}
%% \alias{draw.details.default}
%% \alias{draw.details.frame}
%% \alias{draw.details.glist}
%% \alias{draw.details.lines}
%% \alias{draw.details.line.to}
%% \alias{draw.details.move.to}
%% \alias{draw.details.points}
%% \alias{draw.details.polygon}
%% \alias{draw.details.rect}
%% \alias{draw.details.segments}
%% \alias{draw.details.text}
%% \alias{draw.details.viewport}
%% \alias{draw.details.xaxis}
%% \alias{draw.details.yaxis}
%% \alias{editDetails.default}
%% \alias{editDetails.xaxis}
%% \alias{editDetails.yaxis}
%% \alias{height.details.default}
%% \alias{height.details.frame}
%% \alias{height.details.rect}
%% \alias{height.details.text}
%% \alias{height.details.viewport}
%% \alias{height.post.details.default}
%% \alias{height.pre.details.default}
%% \alias{width.details.default}
%% \alias{width.details.frame}
%% \alias{width.details.rect}
%% \alias{width.details.text}
%% \alias{width.details.viewport}
%% \alias{width.post.details.default}
%% \alias{width.pre.details.default}
%% </LIST>

%% These are no longer in the namespace:
%% <LIST>
%% \alias{.GRID.STATE}
%% \alias{.grid.gpar.names}
%% \alias{.grid.loaded}
%% \alias{.grid.unit.list}
%% \alias{absolute}
%% \alias{absolute.units}
%% \alias{absolute.units.unit}
%% \alias{absolute.units.unit.arithmetic}
%% \alias{absolute.units.unit.list}
%% \alias{col.spec}
%% \alias{draw.all}
%% \alias{draw.frame.child}
%% \alias{get.gpar}
%% \alias{get.value}
%% \alias{get.value.default}
%% \alias{get.value.grob}
%% \alias{grid.Call}
%% \alias{grid.Call.graphics}
%% \alias{grid.top.level.vp}
%% \alias{height}
%% \alias{height.post}
%% \alias{height.pre}
%% \alias{inc.display.list}
%% \alias{is.even}
%% \alias{is.gpar}
%% \alias{is.grob}
%% \alias{is.layout}
%% \alias{is.odd}
%% \alias{is.unit.arithmetic}
%% \alias{is.unit.list}
%% \alias{is.viewport}
%% \alias{layout.heights}
%% \alias{layout.ncol}
%% \alias{layout.nrow}
%% \alias{layout.respect}
%% \alias{layout.widths}
%% \alias{make.xaxis.labels}
%% \alias{make.xaxis.major}
%% \alias{make.xaxis.ticks}
%% \alias{make.yaxis.labels}
%% \alias{make.yaxis.major}
%% \alias{make.yaxis.ticks}
%% \alias{mod.dims}
%% \alias{new.col}
%% \alias{new.row}
%% \alias{num.col.specs}
%% \alias{num.row.specs}
%% \alias{origin.bottom}
%% \alias{origin.left}
%% \alias{origin.right}
%% \alias{origin.top}
%% \alias{pop.saved.gpars}
%% \alias{pop.vp}
%% \alias{push.saved.gpars}
%% \alias{push.vp}
%% \alias{record}
%% \alias{record.default}
%% \alias{record.grob}
%% \alias{record.viewport}
%% \alias{recycle.data}
%% \alias{row.spec}
%% \alias{saved.pars}
%% \alias{set.gpar}
%% \alias{set.value.grob}
%% \alias{swap.origin.horizontal}
%% \alias{swap.origin.vertical}
%% \alias{unit.arithmetic}
%% \alias{unit.arithmetic.rep}
%% \alias{unit.length.unit}
%% \alias{unit.length.unit.arithmetic}
%% \alias{unit.length.unit.list}
%% \alias{unit.list}
%% \alias{unit.list.from.list}
%% \alias{unit.list.rep}
%% \alias{unset.gpar}
%% \alias{updateCol}
%% \alias{updateRow}
%% \alias{valid.data}
%% \alias{valid.just}
%% \alias{valid.layout}
%% \alias{valid.origin}
%% \alias{valid.pch}
%% \alias{valid.unit}
%% \alias{valid.units}
%% \alias{valid.viewport}
%% \alias{validGP}
%% \alias{width}
%% \alias{width.post}
%% \alias{width.pre}
%% </LIST>

%% Part of the sensible export list but (currently?) documented as
%% internal (or waiting for documentation to be written):
%% <LIST>
\alias{draw.details}
\alias{editDetails}
\alias{grid.legend}
\alias{grid.multipanel}
\alias{grid.panel}
\alias{grid.prop.list}
\alias{grid.strip}
\alias{height.post.details}
\alias{height.pre.details}
\alias{layoutRegion}
\alias{viewport.layout}
\alias{viewport.transform}
\alias{width.post.details}
\alias{width.pre.details}
%% </LIST>
%% Currently (?) exported as used in the grid.layout.Rd \example ...
%% <LIST>
\alias{layout.torture}
%% </LIST>

\title{Internal Grid Functions}
\description{
  Internal Grid functions
}
\details{
  These are not to be called by the user (or in some cases are just
  waiting for proper documentation to be written :).
}
\keyword{ internal }
\eof
\name{grid.arrows}
\alias{grid.arrows}
\title{ Draw Arrows }
\description{
  This will draw arrows at either end of a line or an existing
  line.to, lines, or segments grob.
}
\usage{
grid.arrows(x = c(0.25, 0.75), y = 0.5, default.units = "npc",
            grob = NULL,
            angle = 30, length = unit(0.25, "inches"),
            ends = "last", type = "open",
            gp = gpar(), draw = TRUE, vp = NULL)
}
\arguments{
  \item{x}{A numeric vector or unit object specifying x-values.}
  \item{y}{A numeric vector or unit object specifying y-values.}
  \item{default.units}{A string indicating the default units to use
    if \code{x} or \code{y} are only given as numeric vectors.}  
  \item{grob}{ A grob to add arrows to;  currently can only be
    a line.to, lines, or segments grob. }
  \item{angle}{ A numeric specifying (half) the width of the arrow head
    (in degrees). }
  \item{length}{ A unit object specifying the length of the arrow head. }
  \item{ends}{ One of \code{"first"}, \code{"last"}, or \code{"both"},
    indicating which end of the line to add arrow heads. }
  \item{type}{ Either \code{"open"} or \code{"closed"} to indicate
    the type of arrow head.   }
  \item{gp}{An object of class \code{gpar}, typically the output
    from a call to the function \code{gpar}.  This is basically
    a list of graphical parameter settings.}
  \item{draw}{A logical value indicating whether graphics output
    should be produced.}
  \item{vp}{A Grid viewport object (or NULL).}
}
\details{
  If the grob argument is specified, this overrides any x
  and/or y arguments.
}
\value{
  An object of class \code{"grob"}.
}
\author{ Paul Murrell }
\seealso{
  \link{Grid},
  \code{\link{viewport}},
  \code{\link{grid.line.to}},
  \code{\link{grid.lines}},
  \code{\link{grid.segments}}
}
\examples{
push.viewport(viewport(layout=grid.layout(2, 4)))
push.viewport(viewport(layout.pos.col=1,
                       layout.pos.row=1))
grid.rect(gp=gpar(col="grey"))
grid.arrows()
pop.viewport()
push.viewport(viewport(layout.pos.col=2,
                       layout.pos.row=1))
grid.rect(gp=gpar(col="grey"))
grid.arrows(angle=15, type="closed")
pop.viewport()
push.viewport(viewport(layout.pos.col=3,
                       layout.pos.row=1))
grid.rect(gp=gpar(col="grey"))
grid.arrows(angle=5, length=unit(0.1, "npc"),
            type="closed", gp=gpar(fill="white"))
pop.viewport()
push.viewport(viewport(layout.pos.col=4,
                       layout.pos.row=1))
grid.rect(gp=gpar(col="grey"))
grid.arrows(x=unit(0:80/100, "npc"),
            y=unit(1 - (0:80/100)^2, "npc"))
pop.viewport()
push.viewport(viewport(layout.pos.col=1,
                       layout.pos.row=2))
grid.rect(gp=gpar(col="grey"))
grid.arrows(ends="both")
pop.viewport()
push.viewport(viewport(layout.pos.col=2,
                       layout.pos.row=2))
grid.rect(gp=gpar(col="grey"))
# Recycling arguments
grid.arrows(x=unit(1:10/11, "npc"), y=unit(1:3/4, "npc"))
pop.viewport()
push.viewport(viewport(layout.pos.col=3,
                       layout.pos.row=2))
grid.rect(gp=gpar(col="grey"))
gs <- grid.segments(x0=unit(1:4/5, "npc"),
                    x1=unit(1:4/5, "npc"))
grid.arrows(grob=gs, length=unit(0.1, "npc"),
            type="closed", gp=gpar(fill="white"))
pop.viewport()
push.viewport(viewport(layout.pos.col=4,
                       layout.pos.row=2))
grid.rect(gp=gpar(col="grey"))
gl <- grid.lines(x=unit(0:80/100, "npc"),
                 y=unit((0:80/100)^2, "npc"))
grid.arrows(grob=gl, angle=15, type="closed", gp=gpar(fill="black"))
pop.viewport()
push.viewport(viewport(layout.pos.col=1,
                       layout.pos.row=2))
grid.move.to(x=0.5, y=0.8)
pop.viewport()
push.viewport(viewport(layout.pos.col=4,
                       layout.pos.row=1))
glt <- grid.line.to(x=0.5, y=0.2, gp=gpar(lwd=3))
grid.arrows(grob=glt, ends="first", gp=gpar(lwd=3))
pop.viewport(2)
grid.edit(gl, y=unit((0:80/100)^3, "npc"))
}
\keyword{dplot}
\eof
\name{grid.circle}
\alias{grid.circle}
\title{ Draw a Circle }
\description{
  This function draws a circle.  
}
\usage{
grid.circle(x=0.5, y=0.5, r=0.5, default.units="npc",
            gp=gpar(), draw=TRUE, vp=NULL)
}
\arguments{
  \item{x}{A numeric vector or unit object specifying x-locations.}
  \item{y}{A numeric vector or unit object specifying y-locations.}
  \item{r}{A numeric vector or unit object specifying radii.}
  \item{default.units}{A string indicating the default units to use
    if \code{x}, \code{y}, \code{width}, or \code{height}
    are only given as numeric vectors.}  
  \item{gp}{An object of class \code{gpar}, typically the output
    from a call to the function \code{gpar}.  This is basically
    a list of graphical parameter settings.}
  \item{draw}{A logical value indicating whether graphics output
    should be produced.}
  \item{vp}{A Grid viewport object (or NULL).}
}
\details{
  The radius may be given in any
  units;  if the units are \emph{relative} (e.g., \code{"npc"} or
  \code{"native"}) then the radius will be different depending on
  whether it is interpreted as a width or as a height.  In such cases,
  the smaller of these two values will be the result.  To see the
  effect, type \code{grid.circle()} and adjust the size of the window.

  The \code{"grob"} object contains an object of class \code{"circle"}.
}
\value{
  An object of class \code{"grob"}.
}
\author{Paul Murrell}
\seealso{
  \link{Grid},
  \code{\link{viewport}}
}
\keyword{dplot}
\eof
\name{grid.collection}
\alias{grid.collection}
\title{Create a Coherent Group of Grid Graphical Objects}
\description{
  This function creates a graphical object which contains
  several other graphical objects.  When it is drawn, it draws
  all of its children.  

  It may be convenient to name the elements of the collection.
}
\usage{
grid.collection(..., gp=gpar(), draw=TRUE, vp=NULL)
}
\arguments{
  \item{\dots}{Zero or more objects of class \code{"grob"}.}
  \item{gp}{An object of class \code{gpar}, typically the output
    from a call to the function \code{gpar}.  This is basically
    a list of graphical parameter settings.}
  \item{draw}{A logical value to indicate whether to produce
    graphical output.}
  \item{vp}{A Grid viewport object (or NULL).}
}
\value{
  An object of class \code{"grob"} containing a list structure
  of class \code{"collection"}.
}
\author{Paul Murrell}
\seealso{
  \code{\link{grid.grob}}.
}
\examples{
grid.newpage()
lc <- grid.collection(l1=grid.lines(draw=FALSE),
                      l2=grid.lines(c(.5, .5), draw=FALSE))
grid.edit(lc, gp=gpar(col="blue"))
grid.edit(lc, "children", "l2", gp=gpar(col="red"))
}
\keyword{dplot}
\eof
\name{grid.convert}
\alias{grid.convert}
\alias{grid.convertX}
\alias{grid.convertY}
\alias{grid.convertWidth}
\alias{grid.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{
grid.convertX(x, unitTo, valueOnly = FALSE) 
grid.convertY(x, unitTo, valueOnly = FALSE) 
grid.convertWidth(x, unitTo, valueOnly = FALSE) 
grid.convertHeight(x, unitTo, valueOnly = FALSE) 
grid.convert(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{grid.convert()} 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, this function 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 <- grid.convert(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
grid.convertX(unit(1, "inches"), "inches")
## The physical units
grid.convertX(unit(2.54, "cm"), "inches")
grid.convertX(unit(25.4, "mm"), "inches")
grid.convertX(unit(72.27, "points"), "inches")
grid.convertX(unit(1/12*72.27, "picas"), "inches")
grid.convertX(unit(72, "bigpts"), "inches")
grid.convertX(unit(1157/1238*72.27, "dida"), "inches")
grid.convertX(unit(1/12*1157/1238*72.27, "cicero"), "inches")
grid.convertX(unit(65536*72.27, "scaledpts"), "inches")
push.viewport(viewport(width=unit(1, "inches"),
                       height=unit(2, "inches"),
                       xscale=c(0, 1),
                       yscale=c(1, 3)))
  ## Location versus dimension
  grid.convertY(unit(2, "native"), "inches")
  grid.convertHeight(unit(2, "native"), "inches")
  ## From "x" to "y" (the conversion is via "inches")
  grid.convert(unit(1, "native"), "native",
               axisFrom="x", axisTo="y")
  ## Convert several values at once
  grid.convertX(unit(c(0.5, 2.54), c("npc", "cm")),
                c("inches", "native"))
pop.viewport()
## Convert a complex unit
grid.convertX(unit(1, "strwidth", "Hello"), "native")
}
\keyword{dplot}
\eof
\name{grid.copy}
\alias{grid.copy}
\title{Make a Copy of a Grid Graphical Object}
\description{
  Grid graphical objects are references to list structures, which means
  that copies of graphical objects \dQuote{point} to the same list
  structure.

  This function copies graphical objects by \emph{value}, which means
  that the copy \dQuote{points} to a separate list structure.
}
\usage{
grid.copy(grob)
}
\arguments{
  \item{grob}{An object of class \code{"grob"}.}
}
\value{
  An object of class \code{"grob"}.
}
\author{Paul Murrell}
\seealso{
  \code{\link{grid.grob}}.
}
\examples{
## Create a graphical object
l <- grid.lines(draw=FALSE)
## View the list.struct
grid.get(l)
## Copy by reference
l2 <- l
## Edit the common list.struct
grid.edit(l2, gp=gpar(col="green"))
## We have modified "l"
grid.get(l)
## Copy by value
l3 <- grid.copy(l)
}
\keyword{dplot}
\eof
\name{grid.display.list}
\alias{grid.display.list}
\title{Control the Grid Display List}
\description{
  Turn the Grid display list on or off.
}
\usage{
grid.display.list(on=TRUE)
}
\arguments{
  \item{on}{A logical value to indicate whether the display list
    should be on or off.}
}
\details{
  All drawing and viewport-setting operations are (by default)
  recorded in the Grid display list.  This allows redrawing
  to occur following an editing operation.

  This display list could get very large so it may be useful to
  turn it off in some cases;  this will of course disable redrawing.
}
\value{
  None.
}
\author{Paul Murrell}

\section{WARNING}{
  Turning the display list on causes the display list to be erased!
}
\keyword{dplot}
\eof
\name{grid.draw}
\alias{grid.draw}
\title{Draw a Grid Graphical Object}
\description{
  Produces graphical output from a graphical object.
}
\usage{
grid.draw(x, recording=TRUE)
}
\arguments{
  \item{x}{An object of class \code{"grob"} or NULL.}
  \item{recording}{A logical value to indicate whether the drawing
    operation should be recorded on the Grid display list.}
}
\details{
  This function doesn't do much itself beyond some system bookkeeping.

  It calls the generic function \code{draw.details}, dispatching on the
  class of the \code{list.struct} within the graphical object, and
  the actual drawing occurs in the appropriate method.
}
\value{
  None.
}
\author{Paul Murrell}
\seealso{
  \code{\link{grid.grob}}.
}

\examples{
grid.newpage()
## Create a graphical object, but don't draw it
l <- grid.lines(draw=FALSE)
## Draw it
grid.draw(l)
}
\keyword{dplot}
\eof
\name{grid.edit}
\alias{grid.edit}
\title{Edit the Description of a Grid Graphical Object}
\description{
  Changes the value of one or more elements of the list structure
  within a graphical object and redraws the graphical object.
}
\usage{
grid.edit(grob, ..., redraw=TRUE)
}
\arguments{
  \item{grob}{An object of class \code{"grob"}.}
  \item{\dots}{Zero or more element-specifiers, plus a single
    new value or a list of new values.
    The new value is required.  Each specifier
    may be a single character or numeric value.  }
  \item{redraw}{A logical value to indicate whether to redraw the
    graphical object.}
}
\details{
  This function acts on the graphical object specified by \code{grob} and
  the element-specifiers.  It sets the values in the list structure
  of that graphical object
  which correspond to the new values.  If \code{redraw}
  is \code{TRUE} it then redraws everything to reflect the change.

  Before redrawing, it calls the generic function \code{edit.details},
  dispatching on the
  class of the list structure within the graphical object, so that
  further consequences of the editing (such as editing children of
  the graphical object) can occur.
}
\value{
  None.
}
\author{Paul Murrell}
\seealso{
  \code{\link{grid.grob}}
}
\examples{
grid.newpage()
xa <- grid.xaxis(vp=viewport(width=.5, height=.5))
grid.edit(xa, gp=gpar(col="red"))
grid.edit(xa, "ticks", gp=gpar(col="green"))
}
\keyword{dplot}
\eof
\name{grid.frame}
\alias{grid.frame}
\title{ Create a Frame for Packing Objects }
\description{
  This function, together with \code{grid.pack} is part of a
  GUI-builder-like interface to constructing graphical images.
  The idea is that you create a frame with this function then
  use \code{grid.pack} to pack objects into the frame.
}
\usage{
grid.frame(layout=NULL, vp=NULL, gp=gpar(), draw=FALSE)
}
\arguments{
  \item{layout}{ A Grid layout, or NULL. This can be used to initialise
    the frame with a number of rows and columns, with initial widths
    and heights, etc. }
  \item{vp}{ An object of class \code{viewport}, or NULL. }
  \item{gp}{ An object of class \code{gpar};  typically the output from
    a call to the function \code{gpar}.}
\item{draw}{ Should the frame be drawn.  Nothing will actually be
  drawn, but it will put the frame on the display list, which means
  that the output will be dynamically updated as objects are packed
  into the frame.  Possibly useful for debugging.}
}
\value{
  An object of class \code{"grob"}.
}
\author{ Paul Murrell }
\seealso{
  \code{\link{grid.pack}}
}
\examples{
grid.newpage()
gf <- grid.frame(draw=TRUE)
grid.pack(gf, grid.rect(draw=FALSE, gp=gpar(fill="grey")))
grid.pack(gf, grid.text("hi there", draw=FALSE), side="right")
}
\keyword{dplot}
\eof
\name{grid.get}
\alias{grid.get}
\title{Get the Contents of a Grid Graphical Object}
\description{
  A Grid graphical object contains a list structure;  this
  function returns that list structure.
}
\usage{
grid.get(grob, ...)
}
\arguments{
  \item{grob}{An object of class \code{"grob"}.}
  \item{\dots}{Zero or more element-specifiers.  Each specifier
    may be a single character or numeric value.}
}
\details{
  If there are no specifiers then the value returned is just the
  list structure of the \code{grob}.  If there is a specifier
  and the list structure of the \code{grob} has a corresponding
  element, and that element is an object of class \code{"grob"},
  then the return value is the list structure within that element.
  And so on ...

  Typically, users will not need to call this function, even
  when writing their own graphical objects.  Most graphical object
  methods will work only with the list structure.
}
\value{
  A list structure.
}
\author{Paul Murrell}
\seealso{
  \code{\link{grid.grob}}.
}
\examples{
xa <- grid.xaxis(draw=FALSE)
grid.get(xa)
grid.get(xa, "ticks")

temp <- grid.collection(axis=grid.xaxis(draw=FALSE), draw=FALSE)
grid.get(temp, "children", "axis", "ticks")
}
\keyword{dplot}
\eof
\name{grid.grill}
\alias{grid.grill}
\title{Draw a Grill}
\description{
  This function draws a grill within a Grid viewport.
}
\usage{
grid.grill(h = unit(seq(0.25, 0.75, 0.25), "npc"),
           v = unit(seq(0.25, 0.75, 0.25), "npc"),
           default.units = "npc", gp=gpar(col = "grey"), vp = NULL)
}
\arguments{
  \item{h}{A numeric vector or unit object
    indicating the horizontal location of the
    vertical grill lines.}
  \item{v}{A numeric vector or unit object
    indicating the vertical location of the
    horizontal grill lines.}
  \item{default.units}{A string indicating the default units to use
    if \code{h} or \code{v} are only given as numeric vectors.}
  \item{gp}{An object of class \code{gpar}, typically the output
    from a call to the function \code{gpar}.  This is basically
    a list of graphical parameter settings.}
  \item{vp}{A Grid viewport object.}
}
\value{
  None.
}
\author{Paul Murrell}
\seealso{
  \link{Grid},
  \code{\link{viewport}}.
}
\keyword{dplot}
\eof
\name{grid.grob}
\alias{grid.grob}
\title{Create a Grid Graphical Object}
\description{
  Creates a Grid graphical object.
}
\usage{
grid.grob(list.struct, cl = NULL, draw = TRUE)
}
\arguments{
  \item{list.struct}{A list (preferably with each element named).}
  \item{cl}{A string giving the class attribute for the \code{list.struct}}
  \item{draw}{A logical value to indicate whether to produce
    graphical output.}
}
\details{
  A Grid graphical object provides a pointer to the
  \code{list.struct}.  This has the important consequence that
  copies of the graphical object refer to the same \code{list.struct}.
  
  All Grid primitives (\code{grid.lines}, \code{grid.rect}, ...) and
  some higher-level Grid functions (e.g., \code{grid.xaxis} and
  \code{grid.yaxis}) return graphical objects.

  Grid provides several useful functions for graphical objects
  (e.g., \code{grid.draw} and \code{grid.edit}) which are designed to make
  it easier to produce new graphical objects.
}
\value{
  An object of class \code{"grob"}.
}
\author{Paul Murrell}
\seealso{
  \code{\link{grid.draw}},
  \code{\link{grid.edit}},
  \code{\link{grid.get}},
  \code{\link{grid.copy}}.
}

\examples{
## Create a graphical object
l <- grid.lines(draw=FALSE)
## View the list.struct
grid.get(l)
## Copy by reference
l2 <- l
## Edit the common list.struct
grid.edit(l2, gp=gpar(col="green"))
## Copy by value
l3 <- grid.copy(l)
}
\keyword{dplot}
\eof
\name{grid.layout}
\alias{grid.layout}
\title{Create a Grid Layout}
\description{
  This function returns a Grid layout, which describes a subdivision
  of a rectangular region.
}
\usage{
grid.layout(nrow = 1, ncol = 1,
        widths = unit(rep(1, ncol), "null"),
        heights = unit(rep(1, nrow), "null"),
        default.units = "null", respect = FALSE)
}
\arguments{
  \item{nrow}{An integer describing the number of rows in the layout.}
  \item{ncol}{An integer describing the number of columns in the layout.}
  \item{widths}{A numeric vector or unit object
    describing the widths of the columns
    in the layout.}
  \item{heights}{A numeric vector or unit object
    describing the heights of the rows
    in the layout.}
  \item{default.units}{A string indicating the default units to use
    if \code{widths} or \code{heights} are only given as numeric vectors.}  
  \item{respect}{A logical value indicating whether
    row heights and column widths should respect each other.}
}
\details{
  The unit objects given for the \code{widths} and \code{heights}
  of a layout may use a special \code{units} that only has
  meaning for layouts.  This is the \code{"null"} unit, which
  indicates what relative fraction of the available width/height the
  column/row occupies.  See the reference for a better description
  of relative widths and heights in layouts.
}
\section{WARNING}{
  This function must NOT be confused with the base R graphics function
  \code{layout}.  In particular, do not use \code{layout} in
  combination with Grid graphics.  The documentation for
  \code{layout} may provide some useful information and this
  function should behave identically in comparable situations.  The
  \code{grid.layout} 
  function has \emph{added} the ability to specify a broader range
  of units for row heights and column widths, and allows for nested
  layouts (see \code{viewport}).
}
\value{
  A Grid layout object.
}
\references{Murrell, P. R. (1999), Layouts: A Mechanism for Arranging
  Plots on a Page, \emph{Journal of Computational and Graphical
  Statistics}, \bold{8}, 121--134.}
\author{Paul Murrell}
\seealso{
  \link{Grid},
  \code{\link{grid.show.layout}},
  \code{\link{viewport}},
  \code{\link{layout}}}

\examples{
## A variety of layouts (some a bit mid-bending ...)
layout.torture()
}
\keyword{dplot}
\eof
\name{grid.lines}
\alias{grid.lines}
\title{Draw Lines in a Grid Viewport}
\description{
  This function draws a series of lines within a Grid viewport.
}
\usage{
grid.lines(x = unit(c(0, 1), "npc", units.per.obs),
       y = unit(c(0, 1), "npc", units.per.obs), 
       default.units = "npc", units.per.obs = FALSE,
       gp=gpar(), draw = TRUE, vp = NULL)
}
\arguments{
  \item{x}{A numeric vector or unit object specifying x-values.}
  \item{y}{A numeric vector or unit object specifying y-values.}
  \item{default.units}{A string indicating the default units to use
    if \code{x} or \code{y} are only given as numeric vectors.}  
  \item{units.per.obs}{A logical value to indicate whether each
    individual (x, y) location has its own unit(s) specified.}
  \item{gp}{An object of class \code{gpar}, typically the output
    from a call to the function \code{gpar}.  This is basically
    a list of graphical parameter settings.}
  \item{draw}{A logical value indicating whether graphics output
    should be produced.}
  \item{vp}{A Grid viewport object (or NULL).}
}
\value{
  An object of class \code{"grob"}.
}
\details{
  The \code{"grob"} object contains an object of class \code{"lines"}.
}
\author{Paul Murrell}
\seealso{
  \link{Grid},
  \code{\link{viewport}}
}
\keyword{dplot}
\eof
\name{grid.locator}
\alias{grid.locator}
\title{ Capture a Mouse Click }
\description{
  Allows the user to click the mouse once within the current
  graphics
  device and returns the location of the mouse click within the
  current viewport, in the specified coordinate system.
}
\usage{
grid.locator(unit = "native")
}
\arguments{
  \item{unit}{ The coordinate system in which to return the location
    of the mouse click.
        See the \code{\link{unit}} function for valid coordinate systems.}
}
\details{
  This function is modal (like the base function \code{locator}) so
  the command line and graphics drawing is blocked until
  the use has clicked the mouse  in the current device.
}
\value{
  A unit object representing the location of the mouse click within the
  current viewport, in the specified coordinate system.
}
\author{ Paul Murrell }
\seealso{ \code{\link{viewport}}, \code{\link{unit}},
  \code{\link{locator}} }
\examples{
if (interactive()) {
  ## Need to write a more sophisticated unit as.character method
  unittrim <- function(unit) {
    sub("^([0-9]+|[0-9]+[.][0-9])[0-9]*", "\\\\1", as.character(unit))
  }
  do.click <- function(unit) {
    click.locn <- grid.locator(unit)
    grid.segments(unit.c(click.locn$x, unit(0, "npc")),
                  unit.c(unit(0, "npc"), click.locn$y),
                  click.locn$x, click.locn$y,
                  gp=gpar(lty="dashed", col="grey"))
    grid.points(click.locn$x, click.locn$y, pch=16, size=unit(1, "mm"))
    clickx <- unittrim(click.locn$x)
    clicky <- unittrim(click.locn$y)
    grid.text(paste("(", clickx, ", ", clicky, ")", sep=""),
              click.locn$x + unit(2, "mm"), click.locn$y,
              just="left")
  }
  do.click("inches")
  push.viewport(viewport(width=0.5, height=0.5,
                         xscale=c(0, 100), yscale=c(0, 10)))
  grid.rect()
  grid.xaxis()
  grid.yaxis()
  do.click("native")
  pop.viewport()  
}
}
\keyword{dplot}
\eof
\name{grid.move.to}
\alias{grid.move.to}
\alias{grid.line.to}
\title{ Move to a Specified Position }
\description{
  Grid has the notion of a current location.  This function
  sets that location.
}
\usage{
grid.move.to(x=0, y=0, default.units="npc", draw=TRUE, vp=NULL)
grid.line.to(x=1, y=1, default.units="npc", draw=TRUE, gp=gpar(), vp=NULL)
}
\arguments{
  \item{x}{A numeric value or a unit object specifying an x-value.}
  \item{y}{A numeric value or a unit object specifying a y-value.}
  \item{default.units}{A string indicating the default units to use
    if \code{x} or \code{y} are only given as numeric values.}  
  \item{draw}{A logical value indicating whether graphics output
    should be produced.}
  \item{gp}{An object of class \code{gpar}, typically the output
    from a call to the function \code{gpar}.  This is basically
    a list of graphical parameter settings.}
  \item{vp}{A Grid viewport object (or NULL).}
}
\author{Paul Murrell}
\seealso{
  \link{Grid},
  \code{\link{viewport}}
}

\examples{
grid.newpage()
grid.move.to(0.5, 0.5)
grid.line.to(1, 1)
grid.line.to(0.5, 0)
push.viewport(viewport(x=0, y=0, w=0.25, h=0.25, just=c("left", "bottom")))
grid.rect()
grid.grill()
grid.line.to(0.5, 0.5)
pop.viewport()
}
\keyword{dplot}
\eof
\name{grid.newpage}
\alias{grid.newpage}
\title{Move to a New Page on a Grid Device}
\description{
  This function erases the current device or moves to a new page.
}
\usage{
grid.newpage(recording = TRUE)
}
\arguments{
  \item{recording}{A logical value to indicate whether the new-page
    operation should be saved onto the Grid display list.}
}
\value{
  None.
}
\author{Paul Murrell}
\seealso{
  \link{Grid}
}
\keyword{dplot}
\eof
\name{grid.pack}
\alias{grid.pack}
\title{ Pack an Object within a Frame }
\description{
  This function, together with \code{grid.frame} is part of a
  GUI-builder-like interface to constructing graphical images.
  The idea is that you create a frame with \code{grid.frame} then
  use this function to pack objects into the frame.
}
\usage{
grid.pack(frame, grob, grob.name="", draw=TRUE, side=NULL,
          row=NULL, row.before=NULL, row.after=NULL,
          col=NULL, col.before=NULL, col.after=NULL,
          width=NULL, height=NULL,
          force.width=FALSE, force.height=FALSE, border=NULL)
}
\arguments{
  \item{frame}{ An object of class \code{frame}, typically the output
  from a call to \code{grid.frame}. }
  \item{grob}{ An object of class \code{grob}.  The object to be
    packed. }
  \item{grob.name}{ The name of the grob within the frame.  This is
    crucial if you intend to access the object again, for example, to
    edit it.}
  \item{draw}{ A boolean indicating whether the output should be updated. }
  \item{side}{ One of \code{"left"}, \code{"top"}, \code{"right"},
    \code{"bottom"} to indicate which side to pack the object on. }
  \item{row}{ Which row to add the object to.  Must be between 1 and
    the-number-of-rows-currently-in-the-frame + 1, or \code{NULL} in
    which case the object occupies all rows. }
  \item{row.before}{ Add the object to a new row just before this row. }
  \item{row.after}{ Add the object to a new row just after this row. }
  \item{col}{ Which col to add the object to.  Must be between 1 and
    the-number-of-cols-currently-in-the-frame + 1, or \code{NULL} in
    which case the object occupies all cols.  }
  \item{col.before}{Add the object to a new col just before this col.}
  \item{col.after}{ Add the object to a new col just after this col. }
  \item{width}{ Specifies the width of the column that the object is
    added to (rather than allowing the width to be taken from the object). }
  \item{height}{ Specifies the height of the row that the object is
    added to (rather than allowing the height to be taken from the
    object). }
  \item{force.width}{ A logical value indicating whether the width of
    the column that the grob is being packed into should be EITHER the
    width specified in the call to \code{grid.pack} OR the maximum of
    that width and the pre-existing width. }
  \item{force.height}{ A logical value indicating whether the height of
    the column that the grob is being packed into should be EITHER the
    height specified in the call to \code{grid.pack} OR the maximum of
    that height and the pre-existing height. }
  \item{border}{ A \code{unit} object of length 4 indicating the borders
    around the object. }
}
\details{
  This is (meant to be) a very flexible function.  There are many
  different
  ways to specify where the new object is to be added relative to the
  objects already in the frame.  The function checks that the
  specification is not self-contradictory.

  NOTE that the width/height of the row/col that the object is added to
  is taken from the object itself unless the \code{width}/\code{height}
  is specified.
}
\value{
  None.
}
\author{ Paul Murrell }
\seealso{
  \code{\link{grid.frame}}
}
\keyword{dplot}
\eof
\name{grid.place}
\alias{grid.place}
\title{ Place an Object within a Frame }
\description{
  This function provides a simpler interface to the \code{grid.pack()}
  function.  This can be used to place objects within the existing
  rows and columns of a frame layout.  You lose the ability to
  add new rows and columns and you lose the ability to affect the
  heights and widths of the rows and columns, \emph{but} you avoid
  some of the speed penalty of dealing with frames without having
  to specify a complicated combination of arguments to \code{grid.pack}.
}
\usage{
grid.place(frame, grob, grob.name="", draw=TRUE, row=1, col=1)
}
\arguments{
  \item{frame}{ An object of class \code{frame}, typically the output
  from a call to \code{grid.frame}. }
  \item{grob}{ An object of class \code{grob}.  The object to be
    packed. }
  \item{grob.name}{ The name of the grob within the frame.  This is
    crucial if you intend to access the object again, for example, to
    edit it.}
  \item{draw}{ A boolean indicating whether the output should be updated. }
  \item{row}{ Which row to add the object to.  Must be between 1 and
    the-number-of-rows-currently-in-the-frame. }
  \item{col}{ Which col to add the object to.  Must be between 1 and
    the-number-of-cols-currently-in-the-frame.  }
}
\author{ Paul Murrell }
\seealso{
  \code{\link{grid.frame}} and
  \code{\link{grid.pack}}
}
\keyword{dplot}
\eof
\name{grid.plot.and.legend}
\alias{grid.plot.and.legend}
\title{ A Simple Plot and Legend Demo }
\description{
  This function is just a wrapper for a simple demonstration of how
  a basic plot and legend can be drawn from scratch using grid.
}
\usage{
grid.plot.and.legend()
}
\author{ Paul Murrell }
\examples{
grid.plot.and.legend()
}
\keyword{dplot}
\eof
\name{grid.points}
\alias{grid.points}
\title{Draw Data Symbols in a Grid Viewport}
\description{
  This function draws data symbols.
}
\usage{
grid.points(x = runif(10),
            y = runif(10)),
            pch = 1, size = unit(1, "char"),
            default.units = "native", 
            gp=gpar(), draw = TRUE, vp = NULL)
}
\arguments{
  \item{x}{A numeric vector or unit object specifying x-values.}
  \item{y}{A numeric vector or unit object specifying y-values.}
  \item{pch}{A numeric or character vector
    indicating what sort of plotting symbol to use.}
  \item{size}{A unit object specifying the size of the plotting symbols.}
  \item{default.units}{A string indicating the default units to use
    if \code{x} or \code{y} are only given as numeric vectors.}  
  \item{gp}{An object of class \code{gpar}, typically the output
    from a call to the function \code{gpar}.  This is basically
    a list of graphical parameter settings.}
  \item{draw}{A logical value indicating whether graphics output
    should be produced.}
  \item{vp}{A Grid viewport object (or NULL).}
}
\value{
  An object of class \code{"grob"}.
}
\details{
  The \code{"grob"} object contains an object of class \code{"points"}.
}
\author{Paul Murrell}
\seealso{
  \link{Grid},
  \code{\link{viewport}}
}
\keyword{dplot}
\eof
\name{grid.polygon}
\alias{grid.polygon}
\title{ Draw a Polygon }
\description{
  This function draws a polygon.  The final point will automatically
  be connected to the initial point.
}
\usage{
grid.polygon(x=c(0, 0.5, 1, 0.5), y=c(0.5, 1, 0.5, 0),
             default.units="npc",
             gp=gpar(), draw=TRUE, vp=NULL)
}
\arguments{
  \item{x}{A numeric vector or unit object specifying x-locations.}
  \item{y}{A numeric vector or unit object specifying y-locations.}
  \item{default.units}{A string indicating the default units to use
    if \code{x}, \code{y}, \code{width}, or \code{height}
    are only given as numeric vectors.}  
  \item{gp}{An object of class \code{gpar}, typically the output
    from a call to the function \code{gpar}.  This is basically
    a list of graphical parameter settings.}
  \item{draw}{A logical value indicating whether graphics output
    should be produced.}
  \item{vp}{A Grid viewport object (or NULL).}
}
\value{
  An object of class \code{"grob"}.
}
\details{
  The \code{"grob"} object contains an object of class \code{"polygon"}.
}
\author{Paul Murrell}
\seealso{
  \link{Grid},
  \code{\link{viewport}}
}
\keyword{dplot}
\eof
\name{grid.pretty}
\alias{grid.pretty}
\title{ Generate a Sensible Set of Breakpoints }
\description{
  Produces a pretty set of breakpoints within the range given.
}
\usage{
grid.pretty(range)
}
\arguments{
  \item{range}{ A numeric vector }
}
\value{
  A numeric vector of breakpoints.
}
\author{ Paul Murrell }
\keyword{dplot}
\eof
\name{grid.rect}
\alias{grid.rect}
\title{Draw a rectangle in a Grid Viewport}
\description{
  This function draws a rectangle.
}
\usage{
grid.rect(x = unit(0.5, "npc"), y = unit(0.5, "npc"),
      width = unit(1, "npc"), height = unit(1, "npc"),
      just = "centre", default.units = "npc", 
      gp=gpar(), draw = TRUE, vp = NULL)
}
\arguments{
  \item{x}{A numeric vector or unit object specifying x-location.}
  \item{y}{A numeric vector or unit object specifying y-location.}
  \item{width}{A numeric vector or unit object specifying width.}
  \item{height}{A numeric vector or unit object specifying height.}
  \item{just}{The justification of the rectangle about its (x, y)
    location.  If two values are given, the first specifies
    horizontal justification and the second specifies vertical
    justification.}
  \item{default.units}{A string indicating the default units to use
    if \code{x}, \code{y}, \code{width}, or \code{height}
    are only given as numeric vectors.}  
  \item{gp}{An object of class \code{gpar}, typically the output
    from a call to the function \code{gpar}.  This is basically
    a list of graphical parameter settings.}
  \item{draw}{A logical value indicating whether graphics output
    should be produced.}
  \item{vp}{A Grid viewport object (or NULL).}
}
\value{
  An object of class \code{"grob"}.
}
\details{
  The \code{"grob"} object contains an object of class \code{"rect"}.
}
\author{Paul Murrell}
\seealso{
  \link{Grid},
  \code{\link{viewport}}
}
\keyword{dplot}
\eof
\name{grid.segments}
\alias{grid.segments}
\title{ Draw Line Segments in a Grid Viewport }
\description{
  This function draws line segments.
}
\usage{
grid.segments(x0 = unit(0, "npc"), y0 = unit(0, "npc"),
              x1 = unit(1, "npc"), y1 = unit(1, "npc"),
              default.units = "npc", units.per.obs = FALSE,
              gp = gpar(), draw = TRUE, vp = NULL)
}
\arguments{
  \item{x0}{ Numeric indicating the starting x-values of the line segments. }
  \item{y0}{ Numeric indicating the starting y-values of the line
    segments. }
  \item{x1}{ Numeric indicating the stopping x-values of the line
    segments. }
  \item{y1}{ Numeric indicating the stopping y-values of the line segments.}
  \item{gp}{ An object of class \code{gpar}. }
  \item{default.units}{ A string. }
  \item{units.per.obs}{ A boolean indicating whether distinct units are
    given for each x/y-value. }
  \item{draw}{ A logical value indicating whether graphics output
    should be produced.}
  \item{vp}{A Grid viewport object (or NULL)}
}
\value{
  An object of class \code{"grob"}.
}
\author{ Paul Murrell                }
\seealso{
  \link{Grid},
  \code{\link{viewport}}
}
\keyword{dplot}
\eof
\name{grid.set}
\alias{grid.set}
\title{Set the Contents of a Grid Graphical Object}
\description{
  A Grid graphical object contains a list structure;  this
  function sets the value of that list structure.
}
\usage{
grid.set(grob, ...)
}
\arguments{
  \item{grob}{An object of class \code{"grob"}.}
  \item{\dots}{Zero or more element-specifiers, plus a list structure.
    The list structure is required.  Each specifier
    may be a single character or numeric value.  }
}
\details{
  If there are no specifiers then the contents of the \code{grob}
  are set to be the list structure.   If there is a specifier
  and the list structure of the \code{grob} has a corresponding
  element, and that element is an object of class \code{"grob"},
  then the contents of that element are set to be the list structure.
  And so on \ldots

  This is ONLY for setting the list structure contents of a
  graphical object.  See \code{grid.edit} for setting the values
  of the elements of the list structure.
  
  This function should not normally be called by the user.
}
\value{
  None.
}
\author{Paul Murrell}
\seealso{
  \code{\link{grid.grob}}.
}
\keyword{dplot}
\eof
\name{grid.show.layout}
\alias{grid.show.layout}
\title{Draw a Diagram of a Grid Layout}
\description{
  This function uses Grid graphics to draw a diagram of a
  Grid layout.
}
\usage{
grid.show.layout(l, newpage=TRUE,
             cell.border = "blue", cell.fill = "light blue",
             cell.label = TRUE, vp = NULL) 
}
\arguments{
  \item{l}{A Grid layout object.}
  \item{newpage}{A logical value indicating whether to move on
    to a new page before drawing the diagram.}
  \item{cell.border}{The colour used to draw the borders of the cells
    in the layout.}
  \item{cell.fill}{The colour used to fill the cells in the layout.}
  \item{cell.label}{A logical indicating whether the layout cells
    should be labelled.}
  \item{vp}{A Grid viewport object (or NULL).}
}
\details{
  A viewport is created within \code{vp} to provide a margin for
  annotation, and the layout is drawn within that new viewport.
  The margin is filled with light grey, the new viewport is filled
  with white and framed with a black border, and the layout regions
  are filled with light blue and framed with a blue border.
  The diagram is annotated with the widths and heights (including units)
  of the columns and rows of the layout using red text.
}
\value{
  None.
}
\author{Paul Murrell}
\seealso{
  \link{Grid},
  \code{\link{viewport}},
  \code{\link{grid.layout}}
}

\examples{
## Diagram of a simple layout 
grid.show.layout(grid.layout(4,2,
                     heights=unit(rep(1, 4),
                                  c("lines", "lines", "lines", "null")),
                     widths=unit(c(1, 1), "inches")))
}
\keyword{dplot}
\eof
\name{grid.show.viewport}
\alias{grid.show.viewport}
\title{Draw a Diagram of a Grid Viewport}
\description{
  This function uses Grid graphics to draw a diagram of
  a Grid viewport.
}
\usage{
grid.show.viewport(v, parent.layout = NULL, newpage = TRUE, vp = NULL)
}
\arguments{
  \item{v}{A Grid viewport object.}
  \item{parent.layout}{A grid layout object.  If this is not NULL and
    the viewport given in \code{v} has its location specified relative
    to the layout, then the diagram shows the layout and which cells
    \code{v} occupies within the layout.}
  \item{newpage}{A logical value to indicate whether to move to
    a new page before drawing the diagram.}
  \item{vp}{A Grid viewport object (or NULL).}
}
\details{
  A viewport is created within \code{vp} to provide a margin for
  annotation, and the diagram is drawn within that new viewport.
  The margin is filled with light grey, the new viewport is filled
  with white and framed with a black border, and the viewport region
  is filled with light blue and framed with a blue border.
  The diagram is annotated with the width and height (including units)
  of the viewport, the (x, y) location of the viewport, and
  the x- and y-scales of the viewport, using red lines and text.
}
\value{
  None.
}
\author{Paul Murrell}
\seealso{
  \link{Grid},
  \code{\link{viewport}}
}

\examples{
## Diagram of a sample viewport
grid.show.viewport(viewport(x=0.6, y=0.6,
                            w=unit(1, "inches"), h=unit(1, "inches")))
grid.show.viewport(viewport(layout.pos.row=2, layout.pos.col=2:3),
                   grid.layout(3, 4))
}
\keyword{dplot}
\eof
\name{grid.text}
\alias{grid.text}
\title{Draw Text in a Grid Viewport}
\description{
  This function draws a piece of text.
}
\usage{
grid.text(label, x = unit(0.5, "npc"), y = unit(0.5, "npc"), 
          just = "centre", rot = 0,
          check.overlap = FALSE, default.units = "npc",
          gp=gpar(), draw = TRUE, vp = NULL)
}
\arguments{
  \item{label}{A vector of strings or expressions to draw.}
  \item{x}{A numeric vector or unit object specifying x-values.}
  \item{y}{A numeric vector or unit object specifying y-values.}
  \item{just}{The justification of the text about its (x, y)
    location.  If two values are given, the first specifies
    horizontal justification and the second specifies vertical
    justification.}
  \item{rot}{The angle to rotate the text.}
  \item{check.overlap}{A logical value to indicate whether to
    check for and omit overlapping text.}
  \item{default.units}{A string indicating the default units to use
    if \code{x} or \code{y}
    are only given as numeric vectors.}  
  \item{gp}{An object of class \code{gpar}, typically the output
    from a call to the function \code{gpar}.  This is basically
    a list of graphical parameter settings.}
  \item{draw}{A logical value indicating whether graphics output
    should be produced.}
  \item{vp}{A Grid viewport object (or NULL).}
}
\value{
  An object of class \code{"grob"}.
}
\details{
  If the \code{label} argument is an expression, the output is
  formatted as a mathematical annotation, as for base graphics text.
  
  The \code{"grob"} object contains an object of class \code{"text"}.
}
\author{Paul Murrell}
\seealso{
  \link{Grid},
  \code{\link{viewport}}
}

\examples{
# Clipping of overlapping text
grid.newpage()
x <- runif(20)
y <- runif(20)
rot <- runif(20, 0, 360)
grid.text("SOMETHING NICE AND BIG", x=x, y=y, rot=rot,
          gp=gpar(fontsize=20, col="grey"))
grid.text("SOMETHING NICE AND BIG", x=x, y=y, rot=rot,
          gp=gpar(fontsize=20), check=TRUE)
# Specifying the justification of text
grid.newpage()
draw.text <- function(just, i, j) {
  grid.text("ABCD", x=x[j], y=y[i], just=just)
  grid.text(deparse(substitute(just)), x=x[j], y=y[i] + unit(2, "lines"),
            gp=gpar(col="grey", fontsize=8))
}
x <- unit(1:4/5, "npc")
y <- unit(1:4/5, "npc")
grid.grill(h=y, v=x, gp=gpar(col="grey"))
draw.text(c("bottom"), 1, 1)
draw.text(c("left", "bottom"), 2, 1)
draw.text(c("right", "bottom"), 3, 1)
draw.text(c("centre", "bottom"), 4, 1)
draw.text(c("centre"), 1, 2)
draw.text(c("left", "centre"), 2, 2)
draw.text(c("right", "centre"), 3, 2)
draw.text(c("centre", "centre"), 4, 2)
draw.text(c("top"), 1, 3)
draw.text(c("left", "top"), 2, 3)
draw.text(c("right", "top"), 3, 3)
draw.text(c("centre", "top"), 4, 3)
draw.text(c(), 1, 4)
draw.text(c("left"), 2, 4)
draw.text(c("right"), 3, 4)
draw.text(c("centre"), 4, 4)
# A simple mathematical annotation example
grid.newpage()
grid.text(expression(z[i] == sqrt(x[i]^2 + y[i]^2)),
  gp=gpar(cex=2))
}
\keyword{dplot}
\eof
\name{grid.xaxis}
\alias{grid.xaxis}
\title{Draw an X-Axis on a Grid Viewport}
\description{
  This function draws an x-axis.
}
\usage{
grid.xaxis(at = NULL, label = TRUE, main = TRUE, gp = gpar(),
           draw = TRUE, vp = NULL)
}
\arguments{
  \item{at}{A numeric vector of x-value locations for the tick marks.}
  \item{label}{A logical value indicating whether to draw the labels
    on the tick marks.}
  \item{main}{A logical value indicating whether to draw the axis
    at the bottom (\code{TRUE}) or at the top (\code{FALSE}) of the
    viewport.}
  \item{gp}{An object of class \code{gpar}, typically the output
    from a call to the function \code{gpar}.  This is basically
    a list of graphical parameter settings.}
  \item{draw}{A logical value indicating whether graphics output
    should be produced.}
  \item{vp}{A Grid viewport obect (or \code{NULL}).}
}
\value{
  An object of class \code{"grob"}.
}
\details{
  The \code{"grob"} object contains an object of class \code{"xaxis"}.
}
\author{Paul Murrell}
\seealso{
  \link{Grid},
  \code{\link{viewport}},
  \code{\link{grid.yaxis}}
}
\keyword{dplot}
\eof
\name{grid.yaxis}
\alias{grid.yaxis}
\title{Draw a Y-Axis on a Grid Viewport}
\description{
  This function draws a y-axis.
}
\usage{
grid.yaxis(at = NULL, label = TRUE, main = TRUE, gp  =gpar(),
           draw = TRUE, vp = NULL)
}
\arguments{
  \item{at}{A numeric vector of y-value locations for the tick marks.}
  \item{label}{A logical value indicating whether to draw the labels
    on the tick marks.}
  \item{main}{A logical value indicating whether to draw the axis
    at the left (\code{TRUE}) or at the right (\code{FALSE}) of the
    viewport.}
  \item{gp}{An object of class \code{gpar}, typically the output
    from a call to the function \code{gpar}.  This is basically
    a list of graphical parameter settings.}
  \item{draw}{A logical value indicating whether graphics output
    should be produced.}
  \item{vp}{A Grid viewport obect (or \code{NULL}).}
}
\value{
  An object of class \code{"grob"}.
}
\details{
  The \code{"grob"} object contains an object of class \code{"yaxis"}.
}
\author{Paul Murrell}
\seealso{
  \link{Grid},
  \code{\link{viewport}},
  \code{\link{grid.xaxis}}
}
\keyword{dplot}
\eof
\name{height.details}
\alias{height.details}
\title{ Height of a Grob }
\description{
  This generic function is called during the evaluation of
  \code{"grobheight"} units.  It should return an object of
  class \code{"unit"}.
}
\usage{
height.details(x)
}
\arguments{
  \item{x}{ A graphical object list structure. }
}
\value{
  An object of class \code{"unit"}.
}
\author{ Paul Murrell }
\seealso{
  The code for some methods, such as \code{height.details.rect}
  and \code{height.details.text}.
  The function \code{\link{absolute.size}}.
}
\keyword{dplot}
\eof
\name{plotViewport}
\alias{plotViewport}
\title{ Create a Viewport with a Standard Plot Layout }
\description{
  This is a convenience function for producing a viewport with
  the common S-style plot layout -- i.e., a central
  plot region surrounded by margins given in terms of a
  number of lines of text.
}
\usage{
plotViewport(margins, ...)
}
\arguments{
  \item{margins}{ A numeric vector interpreted in the same way
    as \code{par(mar)} in base graphics. }
  \item{\dots}{ All other arguments will be passed to a call to
  the \code{viewport()} function. }
}
\value{
  A grid viewport object.
}
\author{ Paul Murrell }
\seealso{
  \code{\link{viewport}} and
  \code{\link{dataViewport}}.
}
\keyword{dplot}
\eof
\name{pop.viewport}
\alias{pop.viewport}
\title{Pop a Viewport off the Grid Viewport Stack}
\description{
  Grid maintains a viewport stack --- a list of nested drawing
  contexts.
  
  This function makes the parent of the specified viewport the
  new default viewport.
}
\usage{
pop.viewport(n=1, recording=TRUE)
}
\arguments{
  \item{n}{An integer giving the number of viewports to pop.
    Defaults to 1.}
  \item{recording}{A logical value to indicate whether the set-viewport
    operation should be recorded on the Grid display list.}
}
\value{
  None.
}
\author{Paul Murrell}
\seealso{
  \code{\link{push.viewport}}.
}
\keyword{dplot}
\eof
\name{push.viewport}
\alias{push.viewport}
\title{Push a Viewport onto the Grid Viewport Stack}
\description{
  Grid maintains a viewport stack --- a list of nested drawing
  contexts.
  
  This function makes the specified viewport the default viewport
  and makes its parent the previous default viewport (i.e.,
  nests the specified context within the previous default context).
}
\usage{
push.viewport(..., recording=TRUE)
}
\arguments{
  \item{\dots}{One or more objects of class \code{"viewport"}, or
    \code{NULL}.}
  \item{recording}{A logical value to indicate whether the set-viewport
    operation should be recorded on the Grid display list.}
}
\value{
  None.
}
\author{Paul Murrell}
\seealso{
  \code{\link{pop.viewport}}.
}
\keyword{dplot}
\eof
\name{unit}
\alias{unit}
\alias{is.unit}
\title{Function to Create a Unit Object}
\description{
  This function creates a unit object --- a vector of unit values.
  A unit value is typically just a single numeric value with an
  associated unit.
}
\usage{
unit(x, units, data=NULL)
is.unit(unit)
}
\arguments{
  \item{x}{A numeric vector.}
  \item{units}{A character vector specifying the units for the
    corresponding numeric values.}
  \item{data}{This argument is used to supply extra information
    for special \code{unit} types.}
  \item{unit}{Any object.}
}
\details{
  Unit objects allow the user to specify locations and dimensions
  in a large number of different coordinate systems.  All drawing
  occurs relative to a viewport and the \code{units} specifies
  what coordinate system to use within that viewport.
  
  Possible \code{units} (coordinate systems) are:
  \describe{
    \item{\code{"npc"}}{Normalised Parent Coordinates (the default).
      The origin of the viewport is (0, 0) and the viewport has a width
      and height of 1 unit.  For example, (0.5, 0.5) is the centre of
      the viewport.}
    \item{\code{"cm"}}{Centimetres.}
    \item{\code{"inches"}}{Inches.  1 in = 2.54 cm.}
    \item{\code{"mm"}}{Millimetres.  10 mm = 1 cm.}
    \item{\code{"points"}}{Points.  72.27 pt = 1 in.}
    \item{\code{"picas"}}{Picas.  1 pc = 12 pt.}
    \item{\code{"bigpts"}}{Big Points.  72 bp = 1 in.}
    \item{\code{"dida"}}{Dida. 1157 dd = 1238 pt.}
    \item{\code{"cicero"}}{Cicero.  1 cc = 12 dd.}
    \item{\code{"scaledpts"}}{Scaled Points.  65536 sp = 1 pt.}
    \item{\code{"lines"}}{Lines of text.  Locations and dimensions
      are in terms of multiples of the default text size of the viewport
      (as specified by the viewport's \code{fontsize} and \code{lineheight}).}
    \item{\code{"mylines"}}{Same as \code{"lines"}, except will be
      influenced by grob's own gpar settings.}
    \item{\code{"char"}}{Multiples of nominal font height of the
      viewport (as specified by the viewport's \code{fontsize}).}
    \item{\code{"mychar"}}{Same as \code{"char"}, except will be
      influenced by grob's own gpar settings.}
    \item{\code{"native"}}{Locations and dimensions are relative to
      the viewport's \code{xscale} and \code{yscale}.}
    \item{\code{"snpc"}}{Square Normalised Parent Coordinates.
      Same as Normalised Parent Coordinates, except gives the same answer for
      horizontal and vertical locations/dimensions.  It uses the
      \emph{lesser} of npc-width and npc-height.  This is useful for making
      things which are a proportion of the viewport, but have to be square 
      (or have a fixed aspect ratio).}
    \item{\code{"strwidth"}}{Multiples of the width of the string
      specified in the \code{data} argument.  The font size is
      determined by the pointsize of the viewport.}
    \item{\code{"strheight"}}{Multiples of the height of the string
      specified in the \code{data} argument.  The font size is
      determined by the pointsize of the viewport.}
    \item{\code{"grobwidth"}}{Multiples of the width of the grob
      specified in the \code{data} argument.}
    \item{\code{"grobheight"}}{Multiples of the height of the grob
      specified in the \code{data} argument.}
  }

  The \code{data} argument must be a list when the \code{unit.length()}
  is greater than 1.  For example,
  \code{unit(rep(1, 3), c("npc", "strwidth", "inches"),
        data=list(NULL, "my string", NULL))}.
      
  It is possible to subset unit objects in the normal way
  (e.g., \code{unit(1:5, "npc")[2:4]}), but a special function
  \code{unit.c} is provided for combining unit objects.

  Certain arithmetic and summary operations are defined for
  unit objects.  In particular, it is possible to add and subtract
  unit objects (e.g., \code{unit(1, "npc") - unit(1, "inches")}),
  and to specify the minimum or maximum of a list
  of unit objects (e.g., \code{min(unit(0.5, "npc"), unit(1,
    "inches"))}).

  The \code{is.unit()} function returns a boolean value indicating
  whether the supplied argument is of class \code{"unit"}.
}
\section{WARNING}{
  A special function \code{unit.length} is provided for
  determining the number of unit values in a unit object.

  The \code{length} function will work in some cases, but in general
  will not give the right answer.

  There is also a special function \code{unit.c} for concatenating
  several unit objects.

  The \code{c} function will not give the right answer.
}
\value{
  An object of class \code{"unit"}. 
}
\author{Paul Murrell}
\seealso{
  \code{\link{unit.c}}, \code{\link{unit.rep}},
  \code{\link{unit.pmin}}, \code{\link{unit.pmax}}, and
  \code{\link{unit.length}}
}

\examples{
unit(1, "npc")
unit(1:3/4, "npc")
unit(1:3/4, "npc") + unit(1, "inches")
min(unit(0.5, "npc"), unit(1, "inches"))
unit.c(unit(0.5, "npc"), unit(2, "inches") + unit(1:3/4, "npc"),
       unit(1, "strwidth", "hi there"))
}
\keyword{dplot}
\eof
\name{unit.c}
\alias{unit.c}
\title{Combine Unit Objects}
\description{
  This function produces a new unit object by combining the
  unit objects specified as arguments.
}
\usage{
unit.c(...)
}
\arguments{
  \item{\dots}{An arbitrary number of unit objects.}
}
\value{
  An object of class \code{unit}.
}
\author{Paul Murrell}
\seealso{
  \code{\link{unit}}.
}
\keyword{dplot}
\eof
\name{unit.length}
\alias{unit.length}
\title{Length of a Unit Object}
\description{
  The length of a unit object is defined as the number of unit
  values in the unit object.
}
\usage{
unit.length(unit)
}
\arguments{
  \item{unit}{A unit object.}
}
\value{
  An object of class \code{unit}.
}
\author{Paul Murrell}
\seealso{
  \code{\link{unit}}
}
\keyword{dplot}
\eof
\name{unit.pmin}
\alias{unit.pmin}
\alias{unit.pmax}
\title{ Parallel Unit Minima and Maxima }
\description{
  Returns a unit object whose i'th value is the minimum (or maximum)
  of the i'th values of the arguments.  
}
\usage{
unit.pmin(...)
unit.pmax(...)
}
\arguments{
  \item{\dots}{ One or more unit objects. }
}
\details{
  The length of the result is the maximum of the lengths of the
  arguments;  shorter arguments are recycled in the usual manner.
}
\value{
  A unit object.
}
\author{ Paul Murrell }
\examples{
max(unit(1:3, "cm"), unit(0.5, "npc"))
unit.pmax(unit(1:3, "cm"), unit(0.5, "npc"))
}
\keyword{dplot}
\eof
\name{unit.rep}
\alias{unit.rep}
\title{ Replicate Elements of Unit Objects }
\description{
  Replicates the units according to the values given in \code{times} and
  \code{length.out}.
}
\usage{
unit.rep(x, times, length.out)
}
\arguments{
  \item{x}{ An object of class \code{"unit"}. }
  \item{times}{integer.  A vector giving the number of times to repeat
    each element.  Either of length 1 or \code{length(x)}. }
  \item{length.out}{integer.  (Optional.)  The desired length of the
    output vector.}
}
\value{
  An object of class \code{"unit"}.
}
\author{ Paul Murrell }
 
\seealso{
  \code{\link{rep}}
}

\examples{
unit.rep(unit(1:3, "npc"), 3)
unit.rep(unit(1:3, "npc"), 1:3)
unit.rep(unit(1:3, "npc") + unit(1, "inches"), 3)
unit.rep(max(unit(1:3, "npc") + unit(1, "inches")), 3)
unit.rep(max(unit(1:3, "npc") + unit(1, "strwidth", "a"))*4, 3)
unit.rep(unit(1:3, "npc") + unit(1, "strwidth", "a")*4, 3)
}
\keyword{dplot}
\eof
\name{viewport}
\alias{viewport}
\title{Create a Grid Viewport}
\description{
  This function creates a viewport, which describes a rectangular region
  on a graphics device and defines a number of coordinate systems within
  that region.
}
\usage{
viewport(x = unit(0.5, "npc"), y = unit(0.5, "npc"),
         width = unit(1, "npc"), height = unit(1, "npc"),
         default.units = "npc", just = "centre", 
         gp = gpar(), clip = FALSE,
         xscale = c(0, 1), yscale = c(0, 1),
         angle = 0,
         layout = NULL, layout.pos.row = NULL, layout.pos.col = NULL)
}
\arguments{
  \item{x}{A numeric vector or unit object specifying x-location.}
  \item{y}{A numeric vector or unit object specifying y-location.}
  \item{width}{A numeric vector or unit object specifying width.}
  \item{height}{A numeric vector or unit object specifying height.}
  \item{default.units}{A string indicating the default units to use
    if \code{x}, \code{y}, \code{width}, or \code{height}
    are only given as numeric vectors.}  
  \item{just}{A string vector specifying the justification of the viewport
    relative to its (x, y) location.  If there are two values, the first
    value specifes horizontal justification and the second value specifies
    vertical justification.  Possible values are: \code{"left"},
    \code{"right"}, \code{"centre"}, \code{"center"}, \code{"bottom"},
    and \code{"top"}.}
  \item{gp}{An object of class \code{gpar}, typically the output
    from a call to the function \code{gpar}.  This is basically
    a list of graphical parameter settings.}
  \item{clip}{A logical flag indicating whether to clip to the
    extent of the viewport.}
  \item{xscale}{A numeric vector of length two indicating the minimum and
    maximum on the x-scale.}
  \item{yscale}{A numeric vector of length two indicating the minimum
    and maximum on the y-scale.}
  \item{angle}{A numeric value indicating the angle of rotation of the
    viewport.  Positive values indicate the amount of rotation, in
    degrees, anitclockwise from the positive x-axis.}
  \item{layout}{A Grid layout object which splits the viewport into
    subregions.}
  \item{layout.pos.row}{A numeric vector giving the
    rows occupied by this viewport in its
    parent's layout.}
  \item{layout.pos.col}{A numeric vector giving the
    columns occupied by this viewport in its
    parent's layout.}
}
\details{
  The location and size of a viewport are relative to the coordinate
  systems defined by the viewport's parent (either a graphical device
  or another viewport).  The location and size can be specified in a
  very flexible way by specifying them with unit objects.
  When specifying the location of a viewport, specifying
  both \code{layout.pos.row} and \code{layout.pos.col} as \code{NULL}
  indicates that
  the viewport ignores its parent's layout and specifies its own
  location and size (via its \code{locn}).  If only one of
  \code{layout.pos.row} and \code{layout.pos.col} is \code{NULL}, this
  means occupy ALL of the appropriate row(s)/column(s).  For example,
  \code{layout.pos.row = 1} and \code{layout.pos.col = NULL} means
  occupy all of row 1.  Specifying non-\code{NULL} values for both
  \code{layout.pos.row} and \code{layout.pos.col} means occupy the
  intersection of the appropriate rows and columns.  If a vector of
  length two is
  specified for \code{layout.pos.row} or \code{layout.pos.col}, this
  indicates a range of rows or columns to occupy.  For example,
  \code{layout.pos.row = c(1, 3)} and \code{layout.pos.col = c(2, 4)}
  means occupy cells in the intersection of rows 1, 2, and 3, and
  columns, 2, 3, and 4.

    Clipping obeys only the most recent viewport clip setting.
    For example, if you clip to viewport1, then clip to viewport2,
    the clipping region is determined wholly by viewport2, the
    size and shape of viewport1 is irrelevant (until viewport2
    is popped of course).

    If a viewport is rotated (because of its own \code{angle} setting
    or because it is within another viewport which is rotated) then
    the \code{clip} flag is ignored.  
}
\value{
  An R object of class \code{viewport}.
}
\author{Paul Murrell}
\seealso{
  \link{Grid},
  \code{\link{unit}},
  \code{\link{grid.layout}},
  \code{\link{grid.show.layout}}.
}

\examples{
# Diagram of a sample viewport
grid.show.viewport(viewport(x=0.6, y=0.6,
                   w=unit(1, "inches"), h=unit(1, "inches")))
# Demonstrate viewport clipping
clip.demo <- function(i, j, clip1, clip2, title) {
  push.viewport(viewport(layout.pos.col=i,
                         layout.pos.row=j))
  push.viewport(viewport(width=0.6, height=0.6, clip=clip1))
  grid.rect(gp=gpar(fill="white"))
  grid.circle(r=0.55, gp=gpar(col="red", fill="pink"))
  pop.viewport()
  push.viewport(viewport(width=0.6, height=0.6, clip=clip2))
  grid.polygon(x=c(0.5, 1.1, 0.6, 1.1, 0.5, -0.1, 0.4, -0.1),
               y=c(0.6, 1.1, 0.5, -0.1, 0.4, -0.1, 0.5, 1.1),
               gp=gpar(col="blue", fill="light blue"))
  pop.viewport(2)
}

grid.newpage()
grid.rect(gp=gpar(fill="grey"))
push.viewport(viewport(layout=grid.layout(2, 2)))
clip.demo(1, 1, FALSE, FALSE)
clip.demo(1, 2, TRUE, FALSE)
clip.demo(2, 1, FALSE, TRUE)
clip.demo(2, 2, TRUE, TRUE)
pop.viewport()
}
\keyword{dplot}
\eof
\name{width.details}
\alias{width.details}
\title{ Width of a Grob }
\description{
  This generic function is called during the evaluation of
  \code{"grobwidth"} units.
  It should return an object of class \code{"unit"}.
}
\usage{
width.details(x)
}
\arguments{
  \item{x}{ A graphical object list structure. }
}
\value{
  An object of class \code{"unit"}.
}
\author{ Paul Murrell }
\seealso{
  The code for some methods, such as \code{width.details.rect}
  and \code{width.details.text}.
  The function \code{\link{absolute.size}}.
}
\keyword{dplot}
\eof
