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