1% File src/library/grid/man/grid.grab.Rd
2% Part of the R package, https://www.R-project.org
3% Copyright 1995-2007 R Core Team
4% Distributed under GPL 2 or later
5
6\name{grid.grab}
7\alias{grid.grab}
8\alias{grid.grabExpr}
9\title{ Grab the current grid output }
10\description{
11  Creates a gTree object from the current grid display list
12  or from a scene generated by user-specified code.
13}
14\usage{
15grid.grab(warn = 2, wrap = wrap.grobs, wrap.grobs = FALSE, ...)
16grid.grabExpr(expr, warn = 2, wrap = wrap.grobs, wrap.grobs = FALSE,
17              width = 7, height = 7, device = offscreen, ...)
18}
19\arguments{
20  \item{expr}{ An expression to be evaluated.  Typically,
21    some calls to grid drawing functions. }
22  \item{warn}{ An integer specifying the amount of warnings
23    to emit.  0 means no warnings, 1 means warn when it is
24    certain that the grab will not faithfully represent the
25    original scene. 2 means warn if there's any possibility
26    that the grab will not faithfully represent the
27    original scene.
28  }
29  \item{wrap}{ A logical indicating how the output should
30    be captured. If \code{TRUE}, each non-grob element on the
31    display list is captured by wrapping it in a grob.
32  }
33  \item{wrap.grobs}{ A logical indicating whether, if we are wrapping
34    elements (\code{wrap=TRUE}), we should wrap grobs (or just
35    wrap viewports).
36  }
37  \item{width, height}{ Size of the device used for temporary
38    rendering. }
39  \item{device}{ A function that opens a graphics device for temporary
40    rendering. By default this is an off-screen, in-memory device
41    based on the \code{pdf} device, but this default device may not be
42    satisfactory when using custom fonts.
43  }
44  \item{\dots}{ arguments passed to gTree, for example, a
45    name and/or class for the gTree that is created.}
46}
47\details{
48  There are four ways to capture grid output as a gTree.
49
50  There are two functions for capturing output:
51  use \code{grid.grab} to capture an existing drawing
52  and \code{grid.grabExpr} to capture the output from
53  an expression (without drawing anything).
54
55  For each of these functions, the output can be captured in
56  two ways.  One way tries to be clever and make a
57  gTree with a childrenvp slot containing all viewports on
58  the display list (including those
59  that are popped) and every
60  grob on the display list as a child of the new
61  gTree;  each child has a vpPath in the vp slot so that it is
62  drawn in the appropriate viewport.
63  In other words, the gTree contains all elements on the display
64  list, but in a slightly altered form.
65
66  The other way, \code{wrap=TRUE},
67  is to create a grob for every element on the
68  display list (and make all of those grobs children of the
69  gTree).  Only viewports are
70  wrapped unless \code{wrap.grobs} is also \code{TRUE}.
71
72  The first approach creates a more compact and elegant gTree,
73  which is more flexible to work with,
74  but is not guaranteed to faithfully replicate all possible
75  grid output.  The second approach is more brute force, and
76  harder to work with, but is more likely to replicate the original
77  output.
78
79  An example of a case that will NOT be replicated by wrapping,
80  with \code{wrap.grobs=TRUE}, is
81  a scene where the placement of one grob is dependent on another grob
82  (e.g., via \code{grobX} or \code{grobWidth}).
83}
84\value{
85  A gTree object.
86}
87\seealso{ \code{\link{gTree}}
88}
89\examples{
90pushViewport(viewport(width=.5, height=.5))
91grid.rect()
92grid.points(stats::runif(10), stats::runif(10))
93popViewport()
94grab <- grid.grab()
95grid.newpage()
96grid.draw(grab)
97}
98\keyword{ dplot }
99