1% File src/library/grid/man/viewport.Rd 2% Part of the R package, https://www.R-project.org 3% Copyright 1995-2020 R Core Team 4% Distributed under GPL 2 or later 5 6\name{Grid Viewports} 7\alias{viewport} 8\alias{vpList} 9\alias{vpStack} 10\alias{vpTree} 11\title{Create a Grid Viewport} 12\description{ 13 These functions create viewports, which describe rectangular regions 14 on a graphics device and define a number of coordinate systems within 15 those regions. 16} 17\usage{ 18viewport(x = unit(0.5, "npc"), y = unit(0.5, "npc"), 19 width = unit(1, "npc"), height = unit(1, "npc"), 20 default.units = "npc", just = "centre", 21 gp = gpar(), clip = "inherit", mask = "inherit", 22 xscale = c(0, 1), yscale = c(0, 1), 23 angle = 0, 24 layout = NULL, 25 layout.pos.row = NULL, layout.pos.col = NULL, 26 name = NULL) 27vpList(...) 28vpStack(...) 29vpTree(parent, children) 30} 31\arguments{ 32 \item{x}{A numeric vector or unit object specifying x-location.} 33 \item{y}{A numeric vector or unit object specifying y-location.} 34 \item{width}{A numeric vector or unit object specifying width.} 35 \item{height}{A numeric vector or unit object specifying height.} 36 \item{default.units}{A string indicating the default units to use 37 if \code{x}, \code{y}, \code{width}, or \code{height} 38 are only given as numeric vectors.} 39 \item{just}{A string or numeric 40 vector specifying the justification of the viewport 41 relative to its (x, y) location. If there are two values, the first 42 value specifies horizontal justification and the second value specifies 43 vertical justification. Possible string values are: \code{"left"}, 44 \code{"right"}, \code{"centre"}, \code{"center"}, \code{"bottom"}, 45 and \code{"top"}. For numeric values, 0 means left alignment 46 and 1 means right alignment. 47 } 48 \item{gp}{An object of class \code{"gpar"}, typically the output 49 from a call to the function \code{\link{gpar}}. This is basically 50 a list of graphical parameter settings.} 51 \item{clip}{One of \code{"on"}, \code{"inherit"}, or 52 \code{"off"}, indicating whether to 53 clip to the extent of this viewport, inherit the clipping region 54 from the parent viewport, or turn clipping off altogether. 55 For back-compatibility, a logical value of \code{TRUE} corresponds 56 to \code{"on"} and \code{FALSE} corresponds to \code{"inherit"}. 57 58 May also be a grob (or a gTree) that describes a clipping path.} 59 \item{mask}{One of \code{"none"} (or \code{FALSE}) 60 or \code{"inherit"} (or \code{TRUE}) 61 or a grob (or a gTree). This specifies that the viewport 62 should have no mask, or it should inherit the mask of its parent, 63 or it should have its own mask, as described by the grob.} 64 \item{xscale}{A numeric vector of length two indicating the minimum and 65 maximum on the x-scale. The limits may not be identical. } 66 \item{yscale}{A numeric vector of length two indicating the minimum 67 and maximum on the y-scale. The limits may not be identical. } 68 \item{angle}{A numeric value indicating the angle of rotation of the 69 viewport. Positive values indicate the amount of rotation, in 70 degrees, anticlockwise from the positive x-axis.} 71 \item{layout}{A Grid layout object which splits the viewport into 72 subregions.} 73 \item{layout.pos.row}{A numeric vector giving the 74 rows occupied by this viewport in its 75 parent's layout.} 76 \item{layout.pos.col}{A numeric vector giving the 77 columns occupied by this viewport in its 78 parent's layout.} 79 \item{name}{A character value to uniquely identify the viewport 80 once it has been pushed onto the viewport tree. } 81 \item{...}{Any number of grid viewport objects.} 82 \item{parent}{A grid viewport object.} 83 \item{children}{A vpList object.} 84} 85\details{ 86 The location and size of a viewport are relative to the coordinate 87 systems defined by the viewport's parent (either a graphical device 88 or another viewport). The location and size can be specified in a 89 very flexible way by specifying them with unit objects. 90 When specifying the location of a viewport, specifying 91 both \code{layout.pos.row} and \code{layout.pos.col} as \code{NULL} 92 indicates that 93 the viewport ignores its parent's layout and specifies its own 94 location and size (via its \code{locn}). If only one of 95 \code{layout.pos.row} and \code{layout.pos.col} is \code{NULL}, this 96 means occupy ALL of the appropriate row(s)/column(s). For example, 97 \code{layout.pos.row = 1} and \code{layout.pos.col = NULL} means 98 occupy all of row 1. Specifying non-\code{NULL} values for both 99 \code{layout.pos.row} and \code{layout.pos.col} means occupy the 100 intersection of the appropriate rows and columns. If a vector of 101 length two is 102 specified for \code{layout.pos.row} or \code{layout.pos.col}, this 103 indicates a range of rows or columns to occupy. For example, 104 \code{layout.pos.row = c(1, 3)} and \code{layout.pos.col = c(2, 4)} 105 means occupy cells in the intersection of rows 1, 2, and 3, and 106 columns, 2, 3, and 4. 107 108 Clipping obeys only the most recent viewport clip setting. 109 For example, if you clip to viewport1, then clip to viewport2, 110 the clipping region is determined wholly by viewport2, the 111 size and shape of viewport1 is irrelevant (until viewport2 112 is popped of course). 113 114 If a viewport is rotated (because of its own \code{angle} setting 115 or because it is within another viewport which is rotated) then 116 the \code{clip} flag is ignored. 117 118 Viewport names need not be unique. When pushed, viewports 119 sharing the same parent must have unique names, which means that 120 if you push a viewport with the same name as an existing viewport, 121 the existing viewport will be replaced in the viewport tree. 122 A viewport name can be any string, but 123 grid uses the 124 reserved name \code{"ROOT"} for the top-level viewport. Also, 125 when specifying a viewport name in \code{downViewport} 126 and \code{seekViewport}, it is possible to provide a viewport 127 path, which consists of several names concatenated using the 128 separator (currently \code{::}). Consequently, it is not 129 advisable to use this separator in viewport names. 130 131The viewports in a \code{vpList} are pushed in parallel. The 132 viewports in a \code{vpStack} are pushed in series. When a 133 \code{vpTree} is pushed, the parent is pushed first, then the 134 children are pushed in parallel. 135} 136\value{ 137 An R object of class \code{viewport}. 138} 139\author{Paul Murrell} 140\seealso{ 141 \link{Grid}, 142 \code{\link{pushViewport}}, 143 \code{\link{popViewport}}, 144 \code{\link{downViewport}}, 145 \code{\link{seekViewport}}, 146 \code{\link{upViewport}}, 147 \code{\link{unit}}, 148 \code{\link{grid.layout}}, 149 \code{\link{grid.show.layout}}. 150} 151 152\examples{ 153# Diagram of a sample viewport 154grid.show.viewport(viewport(x=0.6, y=0.6, 155 width=unit(1, "inches"), height=unit(1, "inches"))) 156# Demonstrate viewport clipping 157clip.demo <- function(i, j, clip1, clip2) { 158 pushViewport(viewport(layout.pos.col=i, 159 layout.pos.row=j)) 160 pushViewport(viewport(width=0.6, height=0.6, clip=clip1)) 161 grid.rect(gp=gpar(fill="white")) 162 grid.circle(r=0.55, gp=gpar(col="red", fill="pink")) 163 popViewport() 164 pushViewport(viewport(width=0.6, height=0.6, clip=clip2)) 165 grid.polygon(x=c(0.5, 1.1, 0.6, 1.1, 0.5, -0.1, 0.4, -0.1), 166 y=c(0.6, 1.1, 0.5, -0.1, 0.4, -0.1, 0.5, 1.1), 167 gp=gpar(col="blue", fill="light blue")) 168 popViewport(2) 169} 170 171grid.newpage() 172grid.rect(gp=gpar(fill="grey")) 173pushViewport(viewport(layout=grid.layout(2, 2))) 174clip.demo(1, 1, FALSE, FALSE) 175clip.demo(1, 2, TRUE, FALSE) 176clip.demo(2, 1, FALSE, TRUE) 177clip.demo(2, 2, TRUE, TRUE) 178popViewport() 179# Demonstrate turning clipping off 180grid.newpage() 181pushViewport(viewport(width=.5, height=.5, clip="on")) 182grid.rect() 183grid.circle(r=.6, gp=gpar(lwd=10)) 184pushViewport(viewport(clip="inherit")) 185grid.circle(r=.6, gp=gpar(lwd=5, col="grey")) 186pushViewport(viewport(clip="off")) 187grid.circle(r=.6) 188popViewport(3) 189# Demonstrate vpList, vpStack, and vpTree 190grid.newpage() 191tree <- vpTree(viewport(width=0.8, height=0.8, name="A"), 192 vpList(vpStack(viewport(x=0.1, y=0.1, width=0.5, height=0.5, 193 just=c("left", "bottom"), name="B"), 194 viewport(x=0.1, y=0.1, width=0.5, height=0.5, 195 just=c("left", "bottom"), name="C"), 196 viewport(x=0.1, y=0.1, width=0.5, height=0.5, 197 just=c("left", "bottom"), name="D")), 198 viewport(x=0.5, width=0.4, height=0.9, 199 just="left", name="E"))) 200pushViewport(tree) 201for (i in LETTERS[1:5]) { 202 seekViewport(i) 203 grid.rect() 204 grid.text(current.vpTree(FALSE), 205 x=unit(1, "mm"), y=unit(1, "npc") - unit(1, "mm"), 206 just=c("left", "top"), 207 gp=gpar(fontsize=8)) 208} 209} 210\keyword{dplot} 211