src/library/grid/man/viewport.Rd - R - Git at Google

 % File src/library/grid/man/viewport.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 Viewports}
 \alias{viewport}
 \alias{vpList}
 \alias{vpStack}
 \alias{vpTree}
 \title{Create a Grid Viewport}
 \description{
   These functions create viewports, which describe rectangular regions
   on a graphics device and define a number of coordinate systems within
   those regions.
 }
 \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 = "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)
 }
 \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 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{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}{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{xscale}{A numeric vector of length two indicating the minimum and
     maximum on the x-scale.  The limits may not be identical. }
   \item{yscale}{A numeric vector of length two indicating the minimum
     and maximum on the y-scale. The limits may not be identical. }
   \item{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{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.}
   \item{name}{A character value to uniquely identify the viewport
     once it has been pushed onto the viewport tree.  }
   \item{...}{Any number of grid viewport objects.}
   \item{parent}{A grid viewport object.}
   \item{children}{A vpList object.}
 }
 \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.

     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.
 }
 \value{
   An R object of class \code{viewport}.
 }
 \author{Paul Murrell}
 \seealso{
   \link{Grid},
   \code{\link{pushViewport}},
   \code{\link{popViewport}},
   \code{\link{downViewport}},
   \code{\link{seekViewport}},
   \code{\link{upViewport}},
   \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) {
   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))
 }
 }
 \keyword{dplot}
	% File src/library/grid/man/viewport.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 Viewports}
	\alias{viewport}
	\alias{vpList}
	\alias{vpStack}
	\alias{vpTree}
	\title{Create a Grid Viewport}
	\description{
	These functions create viewports, which describe rectangular regions
	on a graphics device and define a number of coordinate systems within
	those regions.
	}
	\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 = "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)
	}
	\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 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{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}{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{xscale}{A numeric vector of length two indicating the minimum and
	maximum on the x-scale. The limits may not be identical. }
	\item{yscale}{A numeric vector of length two indicating the minimum
	and maximum on the y-scale. The limits may not be identical. }
	\item{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{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.}
	\item{name}{A character value to uniquely identify the viewport
	once it has been pushed onto the viewport tree. }
	\item{...}{Any number of grid viewport objects.}
	\item{parent}{A grid viewport object.}
	\item{children}{A vpList object.}
	}
	\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.

	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.
	}
	\value{
	An R object of class \code{viewport}.
	}
	\author{Paul Murrell}
	\seealso{
	\link{Grid},
	\code{\link{pushViewport}},
	\code{\link{popViewport}},
	\code{\link{downViewport}},
	\code{\link{seekViewport}},
	\code{\link{upViewport}},
	\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) {
	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))
	}
	}
	\keyword{dplot}