grid.grab.html
3.32 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head><title>R: Grab the current grid output</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<link rel="stylesheet" type="text/css" href="../../R.css">
</head><body>
<table width="100%" summary="page for grid.grab {grid}"><tr><td>grid.grab {grid}</td><td align="right">R Documentation</td></tr></table>
<h2>Grab the current grid output</h2>
<h3>Description</h3>
<p>
Creates a gTree object from the current grid display list
or from a scene generated by user-specified code.
</p>
<h3>Usage</h3>
<pre>
grid.grab(warn = 2, wrap = FALSE, ...)
grid.grabExpr(expr, warn = 2, wrap = FALSE, ...)
</pre>
<h3>Arguments</h3>
<table summary="R argblock">
<tr valign="top"><td><code>expr</code></td>
<td>
An expression to be evaluated. Typically,
some calls to grid drawing functions. </td></tr>
<tr valign="top"><td><code>warn</code></td>
<td>
An integer specifying the amount of warnings
to emit. 0 means no warnings, 1 means warn when it is
certain that the grab will not faithfully represent the
original scene. 2 means warn if there's any possibility
that the grab will not faithfully represent the
original scene.
</td></tr>
<tr valign="top"><td><code>wrap</code></td>
<td>
A logical indicating how the output should
be captured. If <code>TRUE</code>, each non-grob element on the
display list is captured by wrapping it in a grob.
</td></tr>
<tr valign="top"><td><code>...</code></td>
<td>
arguments passed to gTree, for example, a
name and/or class for the gTree that is created.</td></tr>
</table>
<h3>Details</h3>
<p>
There are four ways to capture grid output as a gTree.
</p>
<p>
There are two functions for capturing output:
use <code>grid.grab</code> to capture an existing drawing
and <code>grid.grabExpr</code> to capture the output from
an expression (without drawing anything).
</p>
<p>
For each of these functions, the output can be captured in
two ways. One way tries to be clever and make a
gTree with a childrenvp slot containing all viewports on
the display list (including those
that are popped) and every
grob on the display list as a child of the new
gTree; each child has a vpPath in the vp slot so that it is
drawn in the appropriate viewport.
In other words, the gTree contains all elements on the display
list, but in a slightly altered form.
</p>
<p>
The other way, <code>wrap=TRUE</code>,
is to create a grob for every element on the
display list (and make all of those grobs children of the
gTree).
</p>
<p>
The first approach creates a more compact and elegant gTree,
which is more flexible to work with,
but is not guaranteed to faithfully replicate all possible
grid output. The second approach is more brute force, and
harder to work with, but
should always faithfully replicate the original output.
</p>
<h3>Value</h3>
<p>
A gTree object.</p>
<h3>See Also</h3>
<p>
<code><a href="grid.grob.html">gTree</a></code>
</p>
<h3>Examples</h3>
<pre>
pushViewport(viewport(w=.5, h=.5))
grid.rect()
grid.points(runif(10), runif(10))
popViewport()
grab <- grid.grab()
grid.newpage()
grid.draw(grab)
</pre>
<hr><div align="center">[Package <em>grid</em> version 2.5.1 <a href="00Index.html">Index]</a></div>
</body></html>