EVOLUTION-MANAGER

Edit File: viewports.html

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><title>R: Maintaining and Navigating the Grid Viewport Tree</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<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 style="text-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 &mdash; 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 = 1, recording=TRUE)
downViewport(name, strict=FALSE, recording=TRUE)
seekViewport(name, recording=TRUE)
upViewport(n = 1, recording=TRUE)
</pre>

<h3>Arguments</h3>

<table summary="R argblock">
<tr valign="top"><td><code>...</code></td>
<td>
<p>One or more objects of class <code>"viewport"</code>.</p>
</td></tr>
<tr valign="top"><td><code>n</code></td>
<td>
<p>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.</p>
</td></tr>
<tr valign="top"><td><code>name</code></td>
<td>
<p>A character value to identify a viewport in the tree.</p>
</td></tr>
<tr valign="top"><td><code>strict</code></td>
<td>
<p> A boolean indicating whether the vpPath must be
matched exactly. </p>
</td></tr>
<tr valign="top"><td><code>recording</code></td>
<td>
<p>A logical value to indicate whether the viewport
operation should be recorded on the Grid display list.</p>
</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.
</p>
<p>This can be useful for returning to your starting point by doing
something like <code>depth &lt;- downViewport()</code> then
<code>upViewport(depth)</code>.
</p>

<h3>Author(s)</h3>

<p>Paul Murrell</p>

<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 &lt;- 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 style="text-align: center;">[Package <em>grid</em> version 3.6.0 <a href="00Index.html">Index</a>]</div>
</body></html>