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