gpar                  package:grid                  R Documentation

_H_a_n_d_l_i_n_g _G_r_i_d _G_r_a_p_h_i_c_a_l _P_a_r_a_m_e_t_e_r_s

_D_e_s_c_r_i_p_t_i_o_n:

     'gpar()' should be used to create a set of graphical parameter
     settings.  It returns an object of class '"gpar"'.  This is
     basically a list of name-value pairs.

     'get.gpar()' can be used to query the current graphical parameter
     settings.

_U_s_a_g_e:

     gpar(...)
     get.gpar(names = NULL)

_A_r_g_u_m_e_n_t_s:

     ...: Any number of named arguments. 

   names: A character vector of valid graphical parameter names.

_D_e_t_a_i_l_s:

     All grid viewports and (predefined) graphical objects have a slot
     called 'gp', which contains a '"gpar"' object.  When a viewport is
     pushed onto the viewport stack and when a graphical object is
     drawn, the settings in the '"gpar"' object are enforced. In this
     way, the graphical output is modified by the 'gp' 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.

     Valid parameter names are:

       col         Colour for lines and borders.
       fill        Colour for filling rectangles, polygons, ...
       alpha       Alpha channel for transparency
       lty         Line type
       lwd         Line width
       lex         Multiplier applied to line width
       lineend     Line end style (round, butt, square)
       linejoin    Line join style (round, mitre, bevel)
       linemitre   Line mitre limit (number greater than 1)
       fontsize    The size of text (in points)
       cex         Multiplier applied to fontsize
       fontfamily  The font family
       fontface    The font face (bold, italic, ...)
       lineheight  The height of a line as a multiple of the size of text
       font        Font face (alias for fontface;  for backward compatibility)

     Colours can be specified in one of the forms returned by 'rgb', as
     a name (see 'colors') or as a positive integer index into the
     current palette (with zero or negative values being taken as
     transparent).

     The 'alpha' setting is combined with the alpha channel for
     individual colours by multiplying (with both alpha settings
     normalised to the range 0 to 1).

     The size of text is 'fontsize'*'cex'.  The size of a line is
     'fontsize'*'cex'*'lineheight'.

     The 'cex' setting is cumulative;  if a viewport is pushed with a
     'cex' of 0.5 then another viewport is pushed with a 'cex' of 0.5,
     the effective 'cex' is 0.25.

     The 'alpha' and 'lex' settings are also cumulative.

     Changes to the 'fontfamily' may be ignored by some devices, but is
     supported by PostScript, PDF, X11, Windows, and Quartz.  The
     'fontfamily' may be used to specify one of the Hershey Font
     families (e.g., 'HersheySerif') and this specification will be
     honoured on all devices.

     The specification of 'fontface' 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: '"plain"', '"bold"', '"italic"', '"oblique"',
     and '"bold.italic"'. For the special case of the HersheySerif font
     family, '"cyrillic"', '"cyrillic.oblique"', and '"EUC"' are also
     available.

     Specifying the value 'NULL' for a parameter is the same as not
     specifying any value for that parameter, except for 'col' and
     'fill', where 'NULL' indicates not to draw a border or not to fill
     an area (respectively).

     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.)

     The 'gamma' parameter is defunct since R 2.7.0.

     'get.gpar()' returns all current graphical parameter settings.

_V_a_l_u_e:

     An object of class '"gpar"'.

_A_u_t_h_o_r(_s):

     Paul Murrell

_S_e_e _A_l_s_o:

     'Hershey'.

_E_x_a_m_p_l_e_s:

     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()