windows {grDevices} | R Documentation |
Windows Graphics Devices
Description
Available only on Windows.
A graphics device is opened. For windows
, win.graph
,
x11
and X11
this is a window on the current
Windows display: the multiple names are for compatibility with other
systems. win.metafile
prints to a file and win.print
to
the Windows print system.
Usage
windows(width, height, pointsize, record, rescale, xpinch, ypinch,
bg, canvas, gamma, xpos, ypos, buffered, title,
restoreConsole, clickToConfirm, fillOddEven,
family, antialias)
win.graph(width, height, pointsize)
win.metafile(filename = "", width = 7, height = 7, pointsize = 12,
family, restoreConsole = TRUE,
xpinch = NA_real_, ypinch = NA_real_)
win.print(width = 7, height = 7, pointsize = 12, printer = "",
family, antialias, restoreConsole = TRUE)
Arguments
width , height |
the (nominal) width and height of the canvas of
the plotting window in inches. Default |
pointsize |
the default pointsize of plotted text, interpreted as
big points (1/72 inch). Values are rounded to the nearest integer:
values less than or equal to zero are reset to |
record |
logical: sets the initial state of the flag for
recording plots. Default |
rescale |
character, one of |
xpinch , ypinch |
double. Pixels per inch, horizontally and
vertically. Default |
bg |
color. The initial background color. Default
|
canvas |
color. The color of the canvas which is visible
when the background color is transparent. Should be a solid color
(and any alpha value will be ignored). Default |
gamma |
gamma correction fudge factor. Colours in R are sRGB; if your monitor does not conform to sRGB, you might be able to improve things by tweaking this parameter to apply additional gamma correction to the RGB channels. By default 1 (no additional gamma correction). |
xpos , ypos |
integer. Position of the top left of the window, in
pixels. Negative values are taken from the opposite edge of the
monitor. Missing values (the default) mean take the default from the
‘Rconsole’ file, which in turn defaults to
|
buffered |
logical. Should the screen output be double-buffered?
Default |
title |
character string, up to 100 bytes. With the default
|
filename |
the name of the output file: it will be an enhanced
Windows metafile, usually given extension ‘.emf’ or
‘.wmf’. Up to 511 characters are allowed. The page number is
substituted if an integer format is included in the character
string (see |
printer |
The name of a printer as known to Windows. The default causes a dialog box to come up for the user to choose a printer. |
restoreConsole |
logical: see the ‘Details’ below. Defaults to
|
clickToConfirm |
logical: if true confirmation of a new frame
will be by clicking on the device rather than answering a problem in
the console. Default |
fillOddEven |
logical controlling the polygon fill mode: see
|
family |
A length-one character vector specifying the default font family. See section ‘Fonts’. |
antialias |
A length-one character vector, requesting control
over font antialiasing. This is partially matched to
|
Details
All these devices are implemented as variants of the same device.
All arguments of windows
have defaults set by
windows.options
: the defaults given in the arguments section
are the defaults for the defaults. These defaults also apply to the
internal values of gamma
, xpinch
, ypinch
,
buffered
, restoreConsole
and antialias
for
win.graph
, x11
and X11
.
The size of a window is computed from information provided about the
display: it depends on the system being configured accurately.
By default a screen device asks Windows for the number of pixels per
inch. This can be overridden (it is often wrong) by specifying
xpinch
and ypinch
, most conveniently via
windows.options
. For example, a 13.3 inch 1280x800
screen (a typical laptop display) was reported as 96 dpi even though
it is physically about 114 dpi. These arguments may also be useful
to match the scale of output to the size of a metafile (which otherwise
depends on the system being configured accurately).
The different colours need to be distinguished carefully. Areas
outside the device region are coloured in the Windows application background
colour. The device region is coloured in the canvas colour. This is
over-painted by the background colour of a plot when a new page is
called for, but that background colour can be transparent (and is by
default). One difference between setting the canvas colour and the
background colour is that when a plot is saved the background
colour is copied but the canvas colour is not. The argument bg
sets the initial value of par("bg")
in base graphics and
gpar("fill")
in grid graphics
Recorded plot histories are of class "SavedPlots"
. They have a
print
method, and a subset method. As the individual plots are
of class "recordedplot"
they can be replayed by printing them:
see recordPlot
. The active plot history is stored in
variable .SavedPlots
in the workspace.
When a screen device is double-buffered (the default) the
screen is updated 100ms after last plotting call or every 500ms during
continuous plotting. These times can be altered by setting
options("windowsTimeout")
to a vector of two integers before
opening the device.
Line widths as controlled by par(lwd =)
are in multiples of
1/96inch. Multiples less than 1 are allowed, down to one pixel width.
For win.metafile
only one plot is allowed per file, and Windows
seems to disallow reusing the file. So the only way to allow
multiple plots is to use a parametrized filename
as in the
example. If the filename
is omitted (or specified as
""
), the output is copied to the clipboard when the device is
closed.
The restoreConsole
argument is a temporary fix for a problem
in the current implementation of several Windows graphics devices,
and is likely to be removed in an upcoming release. If set to
FALSE
, the console will not receive the focus after the new
device is opened.
There is support for semi-transparent colours of lines, fills and text on the screen devices. These work for saving (from the ‘File’ menu) to PDF, PNG, BMP, JPEG and TIFF, but will be ignored if saving to Metafile and PostScript. Limitations in the underlying Windows API mean that a semi-transparent object must be contained strictly within the device region (allowing for line widths and joins).
Value
A plot device is opened: nothing is returned to the R interpreter.
Resizing options
If a screen device is re-sized, the default behaviour ("R"
) is
to redraw the plot(s) as if the new size had been specified
originally. Using "fit"
will rescale the existing plot(s) to
fit the new device region, preserving the aspect ratio. Using
"fixed"
will leave the plot size unchanged, adding scrollbars
if part of the plot is obscured.
A graphics window will never be created at more than 85% of
the screen width or height, but can be resized to a larger size.
For the first two rescale
options the width and height are
rescaled proportionally if necessary, and if rescale = "fit"
the plot(s) are rescaled accordingly. If rescale = "fixed"
the initially displayed portion is selected within these constraints,
separately for width and height. In MDI mode,
the limit is 85% of the MDI client region.
Using strwidth
or strheight
after a window
has been rescaled (when using "fit"
) gives dimensions in the
original units, but only approximately as they are derived from the
metrics of the rescaled fonts (which are in integer sizes)
The displayed region may be bigger than the ‘paper’ size, and
area(s) outside the ‘paper’ are coloured in the Windows
application background colour. Graphics parameters such as
"din"
refer to the scaled plot if rescaling is in effect.
Fonts
The fonts used for text drawn in a Windows device may be controlled in
two ways. The file R_HOME\etc\Rdevga
can be used to
specify mappings for par(font =)
(or the grid equivalent).
Alternatively, a font family can be specified by a non-empty
family
argument (or by e.g. par(family =)
in the graphics
package) and this will be used for fonts 1:4 via the Windows font
database (see windowsFonts
).
How the fonts look depends on the antialiasing settings, both through
the antialias
argument and the machine settings. These are
hints to Windows GDI that may not be able to be followed, but
antialias = "none"
should ensure that no antialiasing is used.
For a screen device the default depends on the machine settings: it
will be "cleartype"
if that has been enabled. Note that the
greyscale antialiasing that is used only for small fonts (below about
9 pixels, around 7 points on a typical display).
When accessing a system through Remote Desktop, both the Remote Desktop settings and the user's local account settings are relevant to whether antialiasing is used.
Some fonts are intended only to be used with ClearType antialiasing,
for example the Meiryo
Japanese font.
Conventions
This section describes the implementation of the conventions for graphics devices set out in the ‘R Internals’ manual.
The default device size is 7 inches square, although this is often incorrectly implemented by Windows: see ‘Details’.
Font sizes are in big points.
The default font family is Arial.
Line widths are as a multiple of 1/96 inch, with a minimum of one pixel.
The minimum radius of a circle is 1 pixel.
-
pch = "."
withcex = 1
corresponds to a rectangle of sides the larger of one pixel and 0.01 inch. Colours are interpreted via the unprofiled colour mapping of the graphics card – this is assumed to conform to sRGB.
Note
x11()
, X11()
and win.graph()
are simple wrappers
calling windows()
, and mainly exist for compatibility reasons.
Further, x11()
and X11()
have their own help page
for Unix-alikes (where they also have more arguments).
See Also
windowsFonts
,
savePlot
, bringToTop
,
Devices
, pdf
,
x11
for Unix-alikes.
Examples
## Not run: ## A series of plots written to a sequence of metafiles
if(.Platform$OS.type == "windows")
win.metafile("Rplot%02d.wmf", pointsize = 10)
## End(Not run)