R: Force a grob into its components

grid.force {grid} | R Documentation

## Force a grob into its components

### Description

Some grobs only generate their content to draw at drawing time; this function replaces such grobs with their at-drawing-time content.

### Usage

    grid.force(x, ...)
    ## Default S3 method:
    grid.force(x, redraw = FALSE, ...)
    ## S3 method for class 'gPath'
    grid.force(x, strict = FALSE, grep = FALSE, global = FALSE,
                               redraw = FALSE, ...)
    ## S3 method for class 'grob'
    grid.force(x, draw = FALSE, ...)
    forceGrob(x)
    grid.revert(x, ...)
    ## S3 method for class 'gPath'
    grid.revert(x, strict = FALSE, grep = FALSE, global = FALSE,
                                redraw = FALSE, ...)
    ## S3 method for class 'grob'
    grid.revert(x, draw = FALSE, ...)

### Arguments

`x` | For the default method, `x` should not be specified. Otherwise, `x` should be a grob or a gPath. If `x` is character, it is assumed to be a gPath.
`strict` | A boolean indicating whether the `path` must be matched exactly.
`grep` | Whether the `path` should be treated as a regular expression.
`global` | A boolean indicating whether the function should affect just the first match of the `path`, or whether all matches should be affected.
`draw` | logical value indicating whether a grob should be drawn after it is forced.
`redraw` | logical value indicating whether to redraw the grid scene after the forcing operation.
`...` | Further arguments for use by methods.

### Details

Some grobs wait until drawing time to generate what content will actually be drawn (an axis, as produced by `grid.xaxis()`, with an `at` or `NULL` is a good example because it has to see what viewport it is going to be drawn in before it can decide what tick marks to draw).

The content of such grobs (e.g., the tick marks) are not usually visible to `grid.ls()` or accessible to `grid.edit()`.

The `grid.force()` function replaces a grob with its at-drawing-time contents. For example, an axis will be replaced by a vanilla gTree with lines and text representing the axis tick marks that were actually drawn. This makes the tick marks visible to `grid.ls()` and accessible to `grid.edit()`.

The `forceGrob()` function is the internal work horse for `grid.force()`, so will not normally be called directly by the user. It is exported so that methods can be written for custom grob classes if necessary.

The `grid.revert()` function reverses the effect of `grid.force()`, replacing forced content with the original grob.

### Warning

Forcing an explicit grob produces a result as if the grob were drawn in the current drawing context. It may not make sense to draw the result in a different drawing context.

### Note

These functions only have an effect for grobs that generate their content at drawing time using `makeContext()` and `makeContent()` methods (not for grobs that generate their content at drawing time using `preDrawDetails()` and `drawDetails()` methods).

### Author(s)

Paul Murrell

### Examples

    grid.newpage()
    pushViewport(viewport(width=.5, height=.5))
    # Draw xaxis
    grid.xaxis(name="xax")
    grid.ls()
    # Force xaxis
    grid.force()
    grid.ls()
    # Revert xaxis
    grid.revert()
    grid.ls()
    # Draw and force yaxis
    grid.force(yaxisGrob(), draw=TRUE)
    grid.ls()
    # Revert yaxis
    grid.revert()
    grid.ls()
    # Force JUST xaxis
    grid.force("xax")
    grid.ls()
    # Force ALL
    grid.force()
    grid.ls()
    # Revert JUST xaxis
    grid.revert("xax")
    grid.ls()

[Package grid version 3.1.2 Index]