gpar                  package:grid                  R Documentation

Handling Grid Graphical Parameters

Description:

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

Usage:

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

Arguments:

     ...: Any number of named arguments. 

   names: A character vector of valid graphical parameter names.

Details:

     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, ...
       lty         Line type
       lwd         Line width
       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)

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

     For most devices, the 'fontfamily' is specified when the device is
     first opened and may not be changed thereafter - i.e., specifying
     a different font family via 'fontfamily' will be ignored.  This
     will hopefully change in future versions of R.  Also, there is an
     important exception:  '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' follows the R base graphics
     standard:  1 = plain, 2 = bold, 3 = italic, 4 = bold italic.

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

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

Value:

     An object of class '"gpar"'.

Author(s):

     Paul Murrell

See Also:

     'Hershey'.

Examples:

     get.gpar()
     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()

