\HeaderA{Grid Viewports}{Create a Grid Viewport}{Grid Viewports}
\aliasA{viewport}{Grid Viewports}{viewport}
\aliasA{vpList}{Grid Viewports}{vpList}
\aliasA{vpStack}{Grid Viewports}{vpStack}
\aliasA{vpTree}{Grid Viewports}{vpTree}
\keyword{dplot}{Grid Viewports}
\begin{Description}\relax
These functions create viewports, which describe rectangular regions
on a graphics device and define a number of coordinate systems within
those regions.
\end{Description}
\begin{Usage}
\begin{verbatim}
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 = "inherit",
         xscale = c(0, 1), yscale = c(0, 1),
         angle = 0,
         layout = NULL,
         layout.pos.row = NULL, layout.pos.col = NULL,
         name = NULL)
vpList(...)
vpStack(...)
vpTree(parent, children)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] A numeric vector or unit object specifying x-location.
\item[\code{y}] A numeric vector or unit object specifying y-location.
\item[\code{width}] A numeric vector or unit object specifying width.
\item[\code{height}] A numeric vector or unit object specifying height.
\item[\code{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[\code{just}] A string or numeric
vector specifying the justification of the viewport
relative to its (x, y) location.  If there are two values, the first
value specifies horizontal justification and the second value specifies
vertical justification.  Possible string values are: \code{"left"},
\code{"right"}, \code{"centre"}, \code{"center"}, \code{"bottom"},
and \code{"top"}.  For numeric values, 0 means left alignment
and 1 means right alignment.

\item[\code{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[\code{clip}] One of \code{"on"}, \code{"inherit"}, or
\code{"off"}, indicating whether to
clip to the extent of this viewport, inherit the clipping region
from the parent viewport, or turn clipping off altogether.
For back-compatibility, a logical value of \code{TRUE} corresponds
to \code{"on"} and \code{FALSE} corresponds to \code{"inherit"}.
\item[\code{xscale}] A numeric vector of length two indicating the minimum and
maximum on the x-scale.
\item[\code{yscale}] A numeric vector of length two indicating the minimum
and maximum on the y-scale.
\item[\code{angle}] A numeric value indicating the angle of rotation of the
viewport.  Positive values indicate the amount of rotation, in
degrees, anticlockwise from the positive x-axis.
\item[\code{layout}] A Grid layout object which splits the viewport into
subregions.
\item[\code{layout.pos.row}] A numeric vector giving the
rows occupied by this viewport in its
parent's layout.
\item[\code{layout.pos.col}] A numeric vector giving the
columns occupied by this viewport in its
parent's layout.
\item[\code{name}] A character value to uniquely identify the viewport
once it has been pushed onto the viewport tree.  
\item[\code{...}] Any number of grid viewport objects.
\item[\code{parent}] A grid viewport object.
\item[\code{children}] A vpList object.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
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.

Viewport names need not be unique.  When pushed, viewports
sharing the same parent must have unique names, which means that
if you push a viewport with the same name as an existing viewport,
the existing viewport will be replaced in the viewport tree.
A viewport name can be any string, but
grid uses the
reserved name \code{"ROOT"} for the top-level viewport.  Also,
when specifying a viewport name in \code{downViewport}
and \code{seekViewport}, it is possible to provide a viewport
path, which consists of several names concatenated using the
separator  (currently \code{::}).  Consequently, it is not
advisable to use this separator in viewport names.

The viewports in a \code{vpList} are pushed in parallel.  The
viewports in a \code{vpStack} are pushed in series.  When a
\code{vpTree} is pushed, the parent is pushed first, then the
children are pushed in parallel.
\end{Details}
\begin{Value}
An R object of class \code{viewport}.
\end{Value}
\begin{Author}\relax
Paul Murrell
\end{Author}
\begin{SeeAlso}\relax
\LinkA{Grid}{Grid},
\code{\LinkA{pushViewport}{pushViewport}},
\code{\LinkA{popViewport}{popViewport}},
\code{\LinkA{downViewport}{downViewport}},
\code{\LinkA{seekViewport}{seekViewport}},
\code{\LinkA{upViewport}{upViewport}},
\code{\LinkA{unit}{unit}},
\code{\LinkA{grid.layout}{grid.layout}},
\code{\LinkA{grid.show.layout}{grid.show.layout}}.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
# 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) {
  pushViewport(viewport(layout.pos.col=i,
                         layout.pos.row=j))
  pushViewport(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"))
  popViewport()
  pushViewport(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"))
  popViewport(2)
}

grid.newpage()
grid.rect(gp=gpar(fill="grey"))
pushViewport(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)
popViewport()
# Demonstrate turning clipping off
grid.newpage()
pushViewport(viewport(w=.5, h=.5, clip="on"))
grid.rect()
grid.circle(r=.6, gp=gpar(lwd=10))
pushViewport(viewport(clip="inherit"))
grid.circle(r=.6, gp=gpar(lwd=5, col="grey"))
pushViewport(viewport(clip="off"))
grid.circle(r=.6)
popViewport(3)
# Demonstrate vpList, vpStack, and vpTree
grid.newpage()
tree <- vpTree(viewport(w=0.8, h=0.8, name="A"),
               vpList(vpStack(viewport(x=0.1, y=0.1, w=0.5, h=0.5,
                                       just=c("left", "bottom"), name="B"),
                              viewport(x=0.1, y=0.1, w=0.5, h=0.5, 
                                       just=c("left", "bottom"), name="C"),
                              viewport(x=0.1, y=0.1, w=0.5, h=0.5, 
                                       just=c("left", "bottom"), name="D")),
                      viewport(x=0.5, w=0.4, h=0.9,
                               just="left", name="E")))
pushViewport(tree)
for (i in LETTERS[1:5]) {
  seekViewport(i)
  grid.rect()
  grid.text(current.vpTree(FALSE),
            x=unit(1, "mm"), y=unit(1, "npc") - unit(1, "mm"),
            just=c("left", "top"),
            gp=gpar(fontsize=8))
}
\end{ExampleCode}
\end{Examples}

