viewports.html
6.17 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
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head><title>R: Maintaining and Navigating the Grid Viewport Tree</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 Working with Viewports {grid}"><tr><td>Working with Viewports {grid}</td><td align="right">R Documentation</td></tr></table>
<h2>Maintaining and Navigating the Grid Viewport Tree</h2>
<h3>Description</h3>
<p>
Grid maintains a tree of viewports — nested drawing
contexts.
</p>
<p>
These functions provide ways to add or remove viewports
and to navigate amongst viewports in the tree.
</p>
<h3>Usage</h3>
<pre>
pushViewport(..., recording=TRUE)
popViewport(n, recording=TRUE)
downViewport(name, strict=FALSE, recording=TRUE)
seekViewport(name, recording=TRUE)
upViewport(n, recording=TRUE)
</pre>
<h3>Arguments</h3>
<table summary="R argblock">
<tr valign="top"><td><code>...</code></td>
<td>
One or more objects of class <code>"viewport"</code>.</td></tr>
<tr valign="top"><td><code>n</code></td>
<td>
An integer value indicating how many viewports to
pop or navigate up. The special value <code>0</code> indicates to
pop or navigate viewports right up to the root viewport.</td></tr>
<tr valign="top"><td><code>name</code></td>
<td>
A character value to identify a viewport in the tree.</td></tr>
<tr valign="top"><td><code>strict</code></td>
<td>
A boolean indicating whether the vpPath must be
matched exactly. </td></tr>
<tr valign="top"><td><code>recording</code></td>
<td>
A logical value to indicate whether the viewport
operation should be recorded on the Grid display list.</td></tr>
</table>
<h3>Details</h3>
<p>
Objects created by the <code>viewport()</code> function are only
descriptions
of a drawing context. A viewport object must be pushed onto the
viewport tree before it has any effect on drawing.
</p>
<p>
The viewport tree always has a single root viewport (created by the
system) which corresponds to the entire device (and default
graphical parameter settings). Viewports may be added to the tree
using <code>pushViewport()</code> and removed from the tree using
<code>popViewport()</code>.
</p>
<p>
There is only ever one current viewport, which is the current
position within the viewport tree. All drawing and
viewport operations are relative to the current viewport.
When a viewport is pushed it becomes the current viewport.
When a viewport is popped, the parent viewport becomes
the current viewport. Use <code>upViewport</code> to navigate to the parent
of the current viewport, without removing the current viewport
from the viewport tree. Use <code>downViewport</code> to navigate to
a viewport further down the viewport tree and <code>seekViewport</code>
to navigate to a viewport anywhere else in the tree.
</p>
<p>
If a viewport is pushed and it has the same <code>name</code> as a
viewport at the same level in the tree, then it replaces the
existing viewport in the tree.
</p>
<h3>Value</h3>
<p>
<code>downViewport</code> returns the number of viewports it went down.
<br>
This can be useful for returning to your starting point by doing
something like <code>depth <- downViewport()</code> then
<code>upViewport(depth)</code>.</p>
<h3>Author(s)</h3>
<p>
Paul Murrell
</p>
<h3>See Also</h3>
<p>
<code><a href="viewport.html">viewport</a></code> and <code><a href="vpPath.html">vpPath</a></code>.
</p>
<h3>Examples</h3>
<pre>
# push the same viewport several times
grid.newpage()
vp <- viewport(width=0.5, height=0.5)
pushViewport(vp)
grid.rect(gp=gpar(col="blue"))
grid.text("Quarter of the device",
y=unit(1, "npc") - unit(1, "lines"), gp=gpar(col="blue"))
pushViewport(vp)
grid.rect(gp=gpar(col="red"))
grid.text("Quarter of the parent viewport",
y=unit(1, "npc") - unit(1, "lines"), gp=gpar(col="red"))
popViewport(2)
# push several viewports then navigate amongst them
grid.newpage()
grid.rect(gp=gpar(col="grey"))
grid.text("Top-level viewport",
y=unit(1, "npc") - unit(1, "lines"), gp=gpar(col="grey"))
if (interactive()) Sys.sleep(1.0)
pushViewport(viewport(width=0.8, height=0.7, name="A"))
grid.rect(gp=gpar(col="blue"))
grid.text("1. Push Viewport A",
y=unit(1, "npc") - unit(1, "lines"), gp=gpar(col="blue"))
if (interactive()) Sys.sleep(1.0)
pushViewport(viewport(x=0.1, width=0.3, height=0.6,
just="left", name="B"))
grid.rect(gp=gpar(col="red"))
grid.text("2. Push Viewport B (in A)",
y=unit(1, "npc") - unit(1, "lines"), gp=gpar(col="red"))
if (interactive()) Sys.sleep(1.0)
upViewport(1)
grid.text("3. Up from B to A",
y=unit(1, "npc") - unit(2, "lines"), gp=gpar(col="blue"))
if (interactive()) Sys.sleep(1.0)
pushViewport(viewport(x=0.5, width=0.4, height=0.8,
just="left", name="C"))
grid.rect(gp=gpar(col="green"))
grid.text("4. Push Viewport C (in A)",
y=unit(1, "npc") - unit(1, "lines"), gp=gpar(col="green"))
if (interactive()) Sys.sleep(1.0)
pushViewport(viewport(width=0.8, height=0.6, name="D"))
grid.rect()
grid.text("5. Push Viewport D (in C)",
y=unit(1, "npc") - unit(1, "lines"))
if (interactive()) Sys.sleep(1.0)
upViewport(0)
grid.text("6. Up from D to top-level",
y=unit(1, "npc") - unit(2, "lines"), gp=gpar(col="grey"))
if (interactive()) Sys.sleep(1.0)
downViewport("D")
grid.text("7. Down from top-level to D",
y=unit(1, "npc") - unit(2, "lines"))
if (interactive()) Sys.sleep(1.0)
seekViewport("B")
grid.text("8. Seek from D to B",
y=unit(1, "npc") - unit(2, "lines"), gp=gpar(col="red"))
pushViewport(viewport(width=0.9, height=0.5, name="A"))
grid.rect()
grid.text("9. Push Viewport A (in B)",
y=unit(1, "npc") - unit(1, "lines"))
if (interactive()) Sys.sleep(1.0)
seekViewport("A")
grid.text("10. Seek from B to A (in ROOT)",
y=unit(1, "npc") - unit(3, "lines"), gp=gpar(col="blue"))
if (interactive()) Sys.sleep(1.0)
seekViewport(vpPath("B", "A"))
grid.text("11. Seek from\nA (in ROOT)\nto A (in B)")
popViewport(0)
</pre>
<hr><div align="center">[Package <em>grid</em> version 2.5.1 <a href="00Index.html">Index]</a></div>
</body></html>