R: Maintaining and Navigating the Grid Viewport Tree

Working with Viewports {grid} | R Documentation

## Maintaining and Navigating the Grid Viewport Tree

### Description

Grid maintains a tree of viewports — nested drawing contexts.

These functions provide ways to add or remove viewports and to navigate amongst viewports in the tree.

### Usage

    pushViewport(..., recording=TRUE)
    popViewport(n, recording=TRUE)
    downViewport(name, strict=FALSE, recording=TRUE)
    seekViewport(name, recording=TRUE)
    upViewport(n, recording=TRUE)

### Arguments

`...` | One or more objects of class `"viewport"`.
`n` | An integer value indicating how many viewports to pop or navigate up. The special value `0` indicates to pop or navigate viewports right up to the root viewport.
`name` | A character value to identify a viewport in the tree.
`strict` | A boolean indicating whether the vpPath must be matched exactly.
`recording` | A logical value to indicate whether the viewport operation should be recorded on the Grid display list.

### Details

Objects created by the `viewport()` 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.

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 `pushViewport()` and removed from the tree using `popViewport()`.

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 `upViewport` to navigate to the parent of the current viewport, without removing the current viewport from the viewport tree. Use `downViewport` to navigate to a viewport further down the viewport tree and `seekViewport` to navigate to a viewport anywhere else in the tree.

If a viewport is pushed and it has the same `name` as a viewport at the same level in the tree, then it replaces the existing viewport in the tree.

### Value

`downViewport` returns the number of viewports it went down.
This can be useful for returning to your starting point by doing something like `depth <- downViewport()` then `upViewport(depth)`.

### Author(s)

Paul Murrell

### See Also

`viewport` and `vpPath`.

### Examples

    # 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)

[Package grid version 2.8.1 Index]