| % File src/library/grid/man/legendGrob.Rd |
| % Part of the R package, https://www.R-project.org |
| % Copyright 2013 R Core Team |
| % Distributed under GPL 2 or later |
| |
| \name{legendGrob} |
| \title{Constructing a Legend Grob} |
| \alias{legendGrob} |
| \alias{grid.legend} |
| \description{ |
| Constructing a legend grob (in progress) |
| } |
| \usage{ |
| legendGrob(labels, nrow, ncol, byrow = FALSE, |
| do.lines = has.lty || has.lwd, lines.first = TRUE, |
| hgap = unit(1, "lines"), vgap = unit(1, "lines"), |
| default.units = "lines", pch, gp = gpar(), vp = NULL) |
| |
| grid.legend(\dots, draw=TRUE) |
| } |
| \arguments{ |
| \item{labels}{legend labels (expressions)} |
| \item{nrow, ncol}{integer; the number of rows or columns, respectively |
| of the legend \dQuote{layout}. \code{nrow} is optional and |
| typically computed from the number of labels and \code{ncol}.} |
| \item{byrow}{logical indicating whether rows of the legend are filled first.} |
| \item{do.lines}{logical indicating whether legend lines are drawn.} |
| \item{lines.first}{logical indicating whether legend lines are drawn |
| first and hence in a plain \dQuote{below} legend symbols.} |
| \item{hgap}{horizontal space between the legend entries} |
| \item{vgap}{vertical space between the legend entries} |
| \item{default.units}{default units, see \code{\link{unit}}.} |
| \item{pch}{legend symbol, numeric or character, passed to |
| \code{\link{pointsGrob}()}; see also \code{\link[graphics]{points}} for |
| interpretation of the numeric codes.} |
| \item{gp}{an \R object of class \code{gpar}, typically the output |
| from a call to the function \code{gpar}, is basically a list of |
| graphical parameter settings.} |
| \item{vp}{a Grid \code{\link{viewport}} object (or \code{NULL}).} |
| \item{\dots}{for \code{grid.legend()}: all the arguments above are |
| passed to \code{legendGrob()}.} |
| \item{draw}{logical indicating whether graphics output should be produced.} |
| } |
| \value{ |
| Both functions create a legend \code{\link{grob}} (a graphical object |
| describing a plot legend), but only \code{grid.legend} draws it (only |
| if \code{draw} is \code{TRUE}). |
| } |
| %\author{Martin Maechler assisted by Marius Hofert, building on Paul Murrell's} |
| \seealso{ |
| \link{Grid}, \code{\link{viewport}}; |
| \code{\link{pointsGrob}}, \code{\link{linesGrob}}. |
| |
| \code{\link{grid.plot.and.legend}} contains a simple example. |
| } |
| \examples{ |
| ## Data: |
| n <- 10 |
| x <- stats::runif(n) ; y1 <- stats::runif(n) ; y2 <- stats::runif(n) |
| ## Construct the grobs : |
| plot <- gTree(children=gList(rectGrob(), |
| pointsGrob(x, y1, pch=21, gp=gpar(col=2, fill="gray")), |
| pointsGrob(x, y2, pch=22, gp=gpar(col=3, fill="gray")), |
| xaxisGrob(), |
| yaxisGrob())) |
| legd <- legendGrob(c("Girls", "Boys", "Other"), pch=21:23, |
| gp=gpar(col = 2:4, fill = "gray")) |
| gg <- packGrob(packGrob(frameGrob(), plot), |
| legd, height=unit(1,"null"), side="right") |
| |
| ## Now draw it on a new device page: |
| grid.newpage() |
| pushViewport(viewport(width=0.8, height=0.8)) |
| grid.draw(gg) |
| } |
| \keyword{aplot} |
| |