devices {withr}

Graphics devices

Description

Temporarily use a graphics device.

Usage

with_bmp(new, code, ...)

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

with_cairo_pdf(new, code, ...)

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

with_cairo_ps(new, code, ...)

local_cairo_ps(new = list(), ..., .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 = list(),
  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 = list(),
  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 = list(),
  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 = list(), ..., .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 = list(),
  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 = list(), ..., .local_envir = parent.frame())

with_jpeg(new, code, ...)

local_jpeg(new = list(), ..., .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.

On unix-alikes (incl.\ Mac), 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 FALSE. If TRUE, this can produce smaller and better output, but there can 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.

For Unix-alikes (including macOS) 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))
)