gpar.html
6.64 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head><title>R: Handling Grid Graphical Parameters</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<link rel="stylesheet" type="text/css" href="../../R.css">
</head><body>
<table width="100%" summary="page for gpar {grid}"><tr><td>gpar {grid}</td><td align="right">R Documentation</td></tr></table>
<h2>Handling Grid Graphical Parameters</h2>
<h3>Description</h3>
<p>
<code>gpar()</code> should be used to create a set of graphical
parameter settings. It returns an object of class <code>"gpar"</code>. This is
basically a list of name-value pairs.
</p>
<p>
<code>get.gpar()</code> can be used to query the current
graphical parameter settings.
</p>
<h3>Usage</h3>
<pre>
gpar(...)
get.gpar(names = NULL)
</pre>
<h3>Arguments</h3>
<table summary="R argblock">
<tr valign="top"><td><code>...</code></td>
<td>
Any number of named arguments. </td></tr>
<tr valign="top"><td><code>names</code></td>
<td>
A character vector of valid graphical parameter names.</td></tr>
</table>
<h3>Details</h3>
<p>
All grid viewports and (predefined) graphical objects have a slot
called <code>gp</code>, which contains a <code>"gpar"</code> object. When
a viewport is pushed onto the viewport stack and when a graphical object
is drawn, the settings in the <code>"gpar"</code> object are enforced.
In this way, the graphical output is modified by the <code>gp</code>
settings until the graphical object has finished drawing, or until the
viewport is popped off the viewport stack, or until some other
viewport or graphical object is pushed or begins drawing.
</p>
<p>
Valid parameter names are:
<table summary="Rd table">
<tr>
<td align="left">col </td> <td align="left"> Colour for lines and borders. </td>
</tr>
<tr>
<td align="left"> fill </td> <td align="left"> Colour for filling rectangles, polygons, ... </td>
</tr>
<tr>
<td align="left"> alpha </td> <td align="left"> Alpha channel for transparency </td>
</tr>
<tr>
<td align="left"> lty </td> <td align="left"> Line type </td>
</tr>
<tr>
<td align="left"> lwd </td> <td align="left"> Line width </td>
</tr>
<tr>
<td align="left"> lex </td> <td align="left"> Multiplier applied to line width </td>
</tr>
<tr>
<td align="left"> lineend </td> <td align="left"> Line end style (round, butt, square) </td>
</tr>
<tr>
<td align="left"> linejoin </td> <td align="left"> Line join style (round, mitre, bevel) </td>
</tr>
<tr>
<td align="left"> linemitre </td> <td align="left"> Line mitre limit (number greater than 1) </td>
</tr>
<tr>
<td align="left"> fontsize </td> <td align="left"> The size of text (in points) </td>
</tr>
<tr>
<td align="left"> cex </td> <td align="left"> Multiplier applied to fontsize </td>
</tr>
<tr>
<td align="left"> fontfamily </td> <td align="left"> The font family </td>
</tr>
<tr>
<td align="left"> fontface </td> <td align="left"> The font face (bold, italic, ...) </td>
</tr>
<tr>
<td align="left"> lineheight </td> <td align="left"> The height of a line as a multiple of the size of text </td>
</tr>
<tr>
<td align="left"> font </td> <td align="left"> Font face (alias for fontface; for backward compatibility) </td>
</tr>
</table>
<p>
The <code>alpha</code> setting is combined with the alpha channel for
individual colours by multiplying (with both alpha settings
normalised to the range 0 to 1).
</p>
<p>
The size of text is <code>fontsize</code>*<code>cex</code>. The size of a line
is <code>fontsize</code>*<code>cex</code>*<code>lineheight</code>.
</p>
<p>
The <code>cex</code> setting is cumulative; if a viewport is pushed
with a <code>cex</code> of 0.5 then another viewport is pushed with a
<code>cex</code> of 0.5, the effective <code>cex</code> is 0.25.
</p>
<p>
The <code>alpha</code> and <code>lex</code> settings are also cumulative.
</p>
<p>
Changes to the <code>fontfamily</code> may be ignored by some devices,
but is supported by PostScript, PDF, X11, Windows, and Quartz. The
<code>fontfamily</code> may be used to specify one
of the Hershey Font families (e.g., <code>HersheySerif</code>)
and this specification will be honoured
on all devices.
</p>
<p>
The specification of <code>fontface</code> can be an integer or a string.
If an integer, then it
follows the R base graphics
standard: 1 = plain, 2 = bold, 3 = italic, 4 = bold italic.
If a string, then valid values are: <code>"plain"</code>,
<code>"bold"</code>, <code>"italic"</code>, <code>"oblique"</code>, and
<code>"bold.italic"</code>.
For the special case of the HersheySerif font family,
<code>"cyrillic"</code>, <code>"cyrillic.oblique"</code>, and <code>"EUC"</code>
are also available.
</p>
<p>
Specifying the value <code>NULL</code> for a parameter is the same as not
specifying any value for that parameter, except for <code>col</code> and
<code>fill</code>, where <code>NULL</code> indicates not to draw a border or
not to fill an area (respectively).
</p>
<p>
All parameter values can be vectors of multiple values. (This will
not always make sense – for example, viewports will only take
notice of the first parameter value.)
</p>
<p>
The <code>gamma</code> parameter is deprecated.
</p>
<p>
<code>get.gpar()</code> returns all current graphical parameter settings.
</p>
<h3>Value</h3>
<p>
An object of class <code>"gpar"</code>.</p>
<h3>Author(s)</h3>
<p>
Paul Murrell
</p>
<h3>See Also</h3>
<p>
<code><a href="../../grDevices/html/Hershey.html">Hershey</a></code>.
</p>
<h3>Examples</h3>
<pre>
gp <- get.gpar()
utils::str(gp)
## These *do* nothing but produce a "gpar" object:
gpar(col = "red")
gpar(col = "blue", lty = "solid", lwd = 3, fontsize = 16)
get.gpar(c("col", "lty"))
grid.newpage()
vp <- viewport(w = .8, h = .8, gp = gpar(col="blue"))
grid.draw(gTree(children=gList(rectGrob(gp = gpar(col="red")),
textGrob(paste("The rect is its own colour (red)",
"but this text is the colour",
"set by the gTree (green)",
sep = "\n"))),
gp = gpar(col="green"), vp = vp))
grid.text("This text is the colour set by the viewport (blue)",
y = 1, just = c("center", "bottom"),
gp = gpar(fontsize=20), vp = vp)
grid.newpage()
## example with multiple values for a parameter
pushViewport(viewport())
grid.points(1:10/11, 1:10/11, gp = gpar(col=1:10))
popViewport()
</pre>
<hr><div align="center">[Package <em>grid</em> version 2.5.1 <a href="00Index.html">Index]</a></div>
</body></html>