R: Graphics devices

devices {withr} | R Documentation

## Graphics devices

### Description

Temporarily use a graphics device.

### Usage

    with_bmp(new, code, ...)

    local_bmp(new, ..., .local_envir = parent.frame())

    with_cairo_pdf(new, code, ...)

    local_cairo_pdf(new, ..., .local_envir = parent.frame())

    with_cairo_ps(new, code, ...)

    local_cairo_ps(new, ..., .local_envir = parent.frame())

    with_pdf(new, code, width, height, onefile, family, title, fonts, version,
      paper, encoding, bg, fg, pointsize, pagecentre, colormodel, useDingbats,
      useKerning, fillOddEven, compress)

    local_pdf(new, width, height, onefile, family, title, fonts, version, paper,
      encoding, bg, fg, pointsize, pagecentre, colormodel, useDingbats, useKerning,
      fillOddEven, compress, .local_envir = parent.frame())

    with_postscript(new, code, onefile, family, title, fonts, encoding, bg, fg,
      width, height, horizontal, pointsize, paper, pagecentre, print.it, command,
      colormodel, useKerning, fillOddEven)

    local_postscript(new, onefile, family, title, fonts, encoding, bg, fg, width,
      height, horizontal, pointsize, paper, pagecentre, print.it, command,
      colormodel, useKerning, fillOddEven, .local_envir = parent.frame())

    with_svg(new, code, width = 7, height = 7, pointsize = 12,
      onefile = FALSE, family = "sans", bg = "white",
      antialias = c("default", "none", "gray", "subpixel"))

    local_svg(new, width = 7, height = 7, pointsize = 12, onefile = FALSE,
      family = "sans", bg = "white", antialias = c("default", "none", "gray",
      "subpixel"), .local_envir = parent.frame())

    with_tiff(new, code, ...)

    local_tiff(new, ..., .local_envir = parent.frame())

    with_xfig(new, code, onefile = FALSE, encoding = "none",
      paper = "default", horizontal = TRUE, width = 0, height = 0,
      family = "Helvetica", pointsize = 12, bg = "transparent",
      fg = "black", pagecentre = TRUE, defaultfont = FALSE,
      textspecial = FALSE)

    local_xfig(new, onefile = FALSE, encoding = "none", paper = "default",
      horizontal = TRUE, width = 0, height = 0, family = "Helvetica",
      pointsize = 12, bg = "transparent", fg = "black", pagecentre = TRUE,
      defaultfont = FALSE, textspecial = FALSE, .local_envir = parent.frame())

    with_png(new, code, ...)

    local_png(new, ..., .local_envir = parent.frame())

    with_jpeg(new, code, ...)

    local_jpeg(new, ..., .local_envir = parent.frame())

### Arguments

`new` | `[named character]` New graphics device
`code` | `[any]` Code to execute in the temporary environment
`...` | Additional arguments passed to the graphics device.
`.local_envir` | `[environment]` The environment to use for scoping.
`width` | the width of the device in inches.
`height` | the height of the device in inches.
`onefile` | should all plots appear in one file or in separate files?
`family` | one of the device-independent font families, `"sans"`, `"serif"` and `"mono"`, or a character string specify a font family to be searched for in a system-dependent way. See, the ‘Cairo fonts’ section in the help for `X11`.
`title` | title string to embed as the /Title field in the file. Defaults to `"R Graphics Output"`.
`fonts` | a character vector specifying R graphics font family names for additional fonts which will be included in the PDF file. Defaults to `NULL`.
`version` | a string describing the PDF version that will be required to view the output. This is a minimum, and will be increased (with a warning) if necessary. Defaults to `"1.4"`, but see ‘Details’.
`paper` | the target paper size. The choices are `"a4"`, `"letter"`, `"legal"` (or `"us"`) and `"executive"` (and these can be capitalized), or `"a4r"` and `"USr"` for rotated (‘landscape’). The default is `"special"`, which means that the `width` and `height` specify the paper size. A further choice is `"default"`; if this is selected, the papersize is taken from the option `"papersize"` if that is set and as `"a4"` if it is unset or empty. Defaults to `"special"`.
`encoding` | the name of an encoding file. See `postscript` for details. Defaults to `"default"`.
`bg` | the initial background colour: can be overridden by setting par("bg").
`fg` | the initial foreground color to be used. Defaults to `"black"`.
`pointsize` | the default pointsize of plotted text (in big points).
`pagecentre` | logical: should the device region be centred on the page? – is only relevant for `paper != "special"`. Defaults to `TRUE`.
`colormodel` | a character string describing the color model: currently allowed values are `"srgb"`, `"gray"` (or `"grey"`) and `"cmyk"`. Defaults to `"srgb"`. See section ‘Color models’.
`useDingbats` | logical. Should small circles be rendered via the Dingbats font? Defaults to `TRUE`, which produces smaller and better output. Setting this to `FALSE` can work around font display problems in broken PDF viewers: although this font is one of the 14 guaranteed to be available in all PDF viewers, that guarantee is not always honoured. See the ‘Note’ for a possible fix for some viewers.
`useKerning` | logical. Should kerning corrections be included in setting text and calculating string widths? Defaults to `TRUE`.
`fillOddEven` | logical controlling the polygon fill mode: see `polygon` for details. Defaults to `FALSE`.
`compress` | logical. Should PDF streams be generated with Flate compression? Defaults to `TRUE`.
`horizontal` | the orientation of the printed image, a logical. Defaults to true, that is landscape orientation on paper sizes with width less than height.
`print.it` | logical: should the file be printed when the device is closed? (This only applies if `file` is a real file name.) Defaults to false.
`command` | the command to be used for ‘printing’. Defaults to `"default"`, the value of option `"printcmd"`. The length limit is `2*PATH_MAX`, typically 8096 bytes on unix systems and 520 bytes on windows.
`antialias` | string, the type of anti-aliasing (if any) to be used; defaults to `"default"`.
`defaultfont` | logical: should the device use xfig's default font?
`textspecial` | logical: should the device set the textspecial flag for all text elements. This is useful when generating pstex from xfig figures.

### Value

`[any]`
The results of the evaluation of the `code` argument.

### Functions

- `with_bmp`: BMP device

- `with_cairo_pdf`: CAIRO_PDF device

- `with_cairo_ps`: CAIRO_PS device

- `with_pdf`: PDF device

- `with_postscript`: POSTSCRIPT device

- `with_svg`: SVG device

- `with_tiff`: TIFF device

- `with_xfig`: XFIG device

- `with_png`: PNG device

- `with_jpeg`: JPEG device

### See Also

`withr` for examples

`Devices`

### Examples

    # dimensions are in inches
    with_pdf(file.path(tempdir(), "test.pdf"), width = 7, height = 5,
      plot(runif(5))
    )

    # dimensions are in pixels
    with_png(file.path(tempdir(), "test.png"), width = 800, height = 600,
      plot(runif(5))
    )

[Package withr version 2.1.1 Index]