1% File src/library/grDevices/man/windows.Rd 2% Part of the R package, https://www.R-project.org 3% Copyright 1995-2018 R Core Team 4% Distributed under GPL 2 or later 5 6\name{windows} 7\alias{windows} 8\alias{win.graph} 9\alias{win.metafile} 10\alias{win.print} 11\alias{print.SavedPlots} 12\alias{[.SavedPlots} 13 14\title{Windows Graphics Devices} 15 16\description{ 17 Available only on Windows. 18 A graphics device is opened. For \code{windows}, \code{win.graph}, 19 \code{x11} and \code{X11} this is a window on the current 20 Windows display: the multiple names are for compatibility with other 21 systems. \code{win.metafile} prints to a file and \code{win.print} to 22 the Windows print system. 23} 24 25\usage{ 26windows(width, height, pointsize, record, rescale, xpinch, ypinch, 27 bg, canvas, gamma, xpos, ypos, buffered, title, 28 restoreConsole, clickToConfirm, fillOddEven, 29 family, antialias) 30 31win.graph(width, height, pointsize) 32 33win.metafile(filename = "", width = 7, height = 7, pointsize = 12, 34 family, restoreConsole = TRUE) 35 36win.print(width = 7, height = 7, pointsize = 12, printer = "", 37 family, antialias, restoreConsole = TRUE) 38} 39\arguments{ 40 \item{width, height}{the (nominal) width and height of the canvas of 41 the plotting window in inches. Default \code{7}.} 42 \item{pointsize}{the default pointsize of plotted text, interpreted as 43 big points (1/72 inch). Values are rounded to the nearest integer: 44 values less than or equal to zero are reset to \code{12}, the 45 default.} 46 \item{record}{logical: sets the initial state of the flag for 47 recording plots. Default \code{FALSE}.} 48 \item{rescale}{character, one of \code{c("R", "fit", "fixed")}. 49 Controls the action for resizing of the device. Default 50 \code{"R"}. See the \sQuote{Resizing options} section.} 51 \item{xpinch, ypinch}{double. Pixels per inch, horizontally and 52 vertically. Default \code{NA_real_}, which means to take the 53 value from Windows.} 54 \item{bg}{color. The initial background color. Default 55 \code{"transparent"}.} 56 \item{canvas}{color. The color of the canvas which is visible 57 when the background color is transparent. Should be a solid color 58 (and any alpha value will be ignored). Default \code{"white"}.} 59 \item{gamma}{gamma correction fudge factor. 60 Colours in R are sRGB; if your monitor does not conform to 61 sRGB, you might be able to improve things by tweaking this 62 parameter to apply additional gamma correction to the RGB channels. 63 By default 1 (no additional gamma correction).} 64 \item{xpos, ypos}{integer. Position of the top left of the window, in 65 pixels. Negative values are taken from the opposite edge of the 66 monitor. Missing values (the default) mean take the default from the 67 \file{\link{Rconsole}} file, which in turn defaults to 68 \code{xpos = -25, ypos = 0}: this puts the right edge of the window 25 69 pixels from the right edge of the monitor.} 70 \item{buffered}{logical. Should the screen output be double-buffered? 71 Default \code{TRUE}.} 72 \item{title}{character string, up to 100 bytes. With the default 73 \code{""}, a suitable title is created internally. A C-style format 74 for an integer will be substituted by the device number.} 75 \item{filename}{the name of the output file: it will be an enhanced 76 Windows metafile, usually given extension \file{.emf} or 77 \file{.wmf}. Up to 511 characters are allowed. The page number is 78 substituted if an integer format is included in the character 79 string (see \code{\link{postscript}} for further details) and 80 tilde-expansion (see \code{\link{path.expand}}) is performed. (The 81 result must be less than 600 characters long.) The default, 82 \code{""}, means the clipboard.} 83 \item{printer}{The name of a printer as known to Windows. The default 84 causes a dialog box to come up for the user to choose a printer.} 85 \item{restoreConsole}{logical: see the \sQuote{Details} below. Defaults to 86 \code{FALSE} for screen devices.} 87 \item{clickToConfirm}{logical: if true confirmation of a new frame 88 will be by clicking on the device rather than answering a problem in 89 the console. Default \code{TRUE}.} 90 \item{fillOddEven}{logical controlling the polygon fill mode: see 91 \code{\link{polygon}} for details. Default \code{TRUE}.} 92 \item{family}{A length-one character vector specifying the default 93 font family. See section \sQuote{Fonts}.} 94 \item{antialias}{A length-one character vector, requesting control 95 over font antialiasing. This is partially matched to 96 \code{"default"}, \code{"none"}, \code{"cleartype"} or 97 \code{"gray"}. See the \sQuote{Fonts} section.} 98} 99 100\note{ 101 \code{x11()}, \code{X11()} and \code{win.graph()} are simple wrappers 102 calling \code{windows()}, and mainly exist for compatibility reasons. 103 104 Further, \code{\link{x11}()} and \code{X11()} have their own help page 105 for Unix-alikes (where they also have more arguments). 106} 107\details{ 108 All these devices are implemented as variants of the same device. 109 110 All arguments of \code{windows} have defaults set by 111 \code{\link{windows.options}}: the defaults given in the arguments section 112 are the defaults for the defaults. These defaults also apply to the 113 internal values of \code{gamma}, \code{xpinch}, \code{ypinch}, 114 \code{buffered}, \code{restoreConsole} and \code{antialias} for 115 \code{win.graph}, \code{x11} and \code{X11}. 116 117 The size of a window is computed from information provided about the 118 display: it depends on the system being configured accurately. 119 By default a screen device asks Windows for the number of pixels per 120 inch. This can be overridden (it is often wrong) by specifying 121 \code{xpinch} and \code{ypinch}, most conveniently \emph{via} 122 \code{\link{windows.options}}. For example, a 13.3 inch 1280x800 123 screen (a typical laptop display) was reported as 96 dpi even though 124 it is physically about 114 dpi. 125 126 The different colours need to be distinguished carefully. Areas 127 outside the device region are coloured in the Windows application background 128 colour. The device region is coloured in the canvas colour. This is 129 over-painted by the background colour of a plot when a new page is 130 called for, but that background colour can be transparent (and is by 131 default). One difference between setting the canvas colour and the 132 background colour is that when a plot is saved the background 133 colour is copied but the canvas colour is not. The argument \code{bg} 134 sets the initial value of \code{\link{par}("bg")} in base graphics and 135 \code{\link{gpar}("fill")} in grid graphics 136 137 Recorded plot histories are of class \code{"SavedPlots"}. They have a 138 \code{print} method, and a subset method. As the individual plots are 139 of class \code{"recordedplot"} they can be replayed by printing them: 140 see \code{\link{recordPlot}}. The active plot history is stored in 141 variable \code{.SavedPlots} in the workspace. 142 143 When a screen device is double-buffered (the default) the 144 screen is updated 100ms after last plotting call or every 500ms during 145 continuous plotting. These times can be altered by setting 146 \code{options("windowsTimeout")} to a vector of two integers before 147 opening the device. 148 149 Line widths as controlled by \code{par(lwd =)} are in multiples of 150 1/96inch. Multiples less than 1 are allowed, down to one pixel width. 151 152 For \code{win.metafile} only one plot is allowed per file, and Windows 153 seems to disallow reusing the file. So the \emph{only} way to allow 154 multiple plots is to use a parametrized \code{filename} as in the 155 example. If the \code{filename} is omitted (or specified as 156 \code{""}), the output is copied to the clipboard when the device is 157 closed. 158 159 The \code{restoreConsole} argument is a temporary fix for a problem 160 in the current implementation of several Windows graphics devices, 161 and is likely to be removed in an upcoming release. If set to 162 \code{FALSE}, the console will not receive the focus after the new 163 device is opened. 164 165 There is support for semi-transparent colours of lines, fills and text 166 on the screen devices. These work for saving (from the \sQuote{File} 167 menu) to PDF, PNG, BMP, JPEG and TIFF, but will be ignored if saving 168 to Metafile and PostScript. Limitations in the underlying Windows API 169 mean that a semi-transparent object must be contained strictly within 170 the device region (allowing for line widths and joins). 171} 172 173\section{Resizing options}{ 174 If a screen device is re-sized, the default behaviour (\code{"R"}) is 175 to redraw the plot(s) as if the new size had been specified 176 originally. Using \code{"fit"} will rescale the existing plot(s) to 177 fit the new device region, preserving the aspect ratio. Using 178 \code{"fixed"} will leave the plot size unchanged, adding scrollbars 179 if part of the plot is obscured. 180 181 A graphics window will never be created at more than 85\% of 182 the screen width or height, but can be resized to a larger size. 183 For the first two \code{rescale} options the width and height are 184 rescaled proportionally if necessary, and if \code{rescale = "fit"} 185 the plot(s) are rescaled accordingly. If \code{rescale = "fixed"} 186 the initially displayed portion is selected within these constraints, 187 separately for width and height. In MDI mode, 188 the limit is 85\% of the MDI client region. 189 190 Using \code{\link{strwidth}} or \code{\link{strheight}} after a window 191 has been rescaled (when using \code{"fit"}) gives dimensions in the 192 original units, but only approximately as they are derived from the 193 metrics of the rescaled fonts (which are in integer sizes) 194 195 The displayed region may be bigger than the \sQuote{paper} size, and 196 area(s) outside the \sQuote{paper} are coloured in the Windows 197 application background colour. Graphics parameters such as 198 \code{"din"} refer to the scaled plot if rescaling is in effect. 199} 200 201\section{Fonts}{ 202 The fonts used for text drawn in a Windows device may be controlled in 203 two ways. The file \code{R_HOME\\etc\\\link{Rdevga}} can be used to 204 specify mappings for \code{par(font =)} (or the \pkg{grid} equivalent). 205 Alternatively, a font family can be specified by a non-empty 206 \code{family} argument (or by e.g.\sspace{}\code{par(family =)} in the graphics 207 package) and this will be used for fonts 1:4 via the Windows font 208 database (see \code{\link{windowsFonts}}). 209 210 How the fonts look depends on the antialiasing settings, both through 211 the \code{antialias} argument and the machine settings. These are 212 hints to Windows GDI that may not be able to be followed, but 213 \code{antialias = "none"} should ensure that no antialiasing is used. 214 For a screen device the default depends on the machine settings: it 215 will be \code{"cleartype"} if that has been enabled. Note that the 216 greyscale antialiasing that is used only for small fonts (below about 217 9 pixels, around 7 points on a typical display). 218 219 When accessing a system through Remote Desktop, both the Remote 220 Desktop settings \emph{and} the user's local account settings are 221 relevant to whether antialiasing is used. 222 223 Some fonts are intended only to be used with ClearType antialiasing, 224 for example the \code{Meiryo} Japanese font. 225} 226% http://blogs.msdn.com/b/rds/archive/2006/09/08/747023.aspx 227 228\section{Conventions}{ 229 This section describes the implementation of the conventions for 230 graphics devices set out in the \sQuote{R Internals} manual. 231 232 \itemize{ 233 \item The default device size is 7 inches square, although this is 234 often incorrectly implemented by Windows: see \sQuote{Details}. 235 \item Font sizes are in big points. 236 \item The default font family is Arial. 237 \item Line widths are as a multiple of 1/96 inch, with a minimum of 238 one pixel. 239 \item The minimum radius of a circle is 1 pixel. 240 \item \code{pch = "."} with \code{cex = 1} corresponds to a rectangle of sides 241 the larger of one pixel and 0.01 inch. 242 \item Colours are interpreted via the unprofiled colour mapping of 243 the graphics card -- this is \emph{assumed} to conform to sRGB. 244 } 245} 246 247\value{ 248 A plot device is opened: nothing is returned to the \R interpreter. 249} 250 251\seealso{ 252 \code{\link{windowsFonts}}, 253 \code{\link{savePlot}}, \code{\link{bringToTop}}, 254 \code{\link{Devices}}, \code{\link{postscript}}, 255 \code{\link{x11}} for Unix-alikes. 256} 257\examples{\dontrun{## A series of plots written to a sequence of metafiles 258if(.Platform$OS.type == "windows") 259 win.metafile("Rplot\%02d.wmf", pointsize = 10) 260}} 261\keyword{device} 262