The R Project SVN R

% File src/library/grid/man/grid.path.Rd
% Part of the R package, http://www.R-project.org
% Copyright 1995-2007 R Core Development Team
% Distributed under GPL 2 or later

\name{grid.path}
\alias{grid.path}
\alias{pathGrob}
\title{ Draw a Path }
\description{
  These functions create and draw a path.
  The final point will automatically
  be connected to the initial point.
}
\usage{
pathGrob(x, y,
         id=NULL, id.lengths=NULL,
         rule="winding",
         default.units="npc",
         name=NULL, gp=gpar(), vp=NULL)
grid.path(\dots)
}
\arguments{
  \item{x}{A numeric vector or unit object specifying x-locations.}
  \item{y}{A numeric vector or unit object specifying y-locations.}
  \item{id}{A numeric vector used to separate locations in \code{x} and
    \code{y} into sub-paths.  All locations with the same
    \code{id} belong to the same sub-path.}
  \item{id.lengths}{A numeric vector used to separate locations in \code{x} and
    \code{y} into sub-paths.  Specifies consecutive blocks of
    locations which make up separate sub-paths.}
  \item{rule}{A character value specifying the fill rule: either
    \code{"winding"} or \code{"evenodd"}.}
  \item{default.units}{A string indicating the default units to use
    if \code{x} or \code{y}
    are only given as numeric vectors.}  
  \item{name}{ A character identifier. }
  \item{gp}{An object of class \code{gpar}, typically the output
    from a call to the function \code{gpar}.  This is basically
    a list of graphical parameter settings.}
  \item{vp}{A Grid viewport object (or NULL).}
  \item{\dots}{Arguments passed to \code{pathGrob()}.}
}
\value{
  A grob object.
}
\details{
  Both functions create a path grob (a graphical object describing a
  path), but only \code{grid.path}
  draws the path (and then only if \code{draw} is \code{TRUE}).

  A path is like a polygon except that the former
  can contain holes, as interpreted by the fill rule; these fill a region if
  the path border encircles it an odd or non-zero number of times,
  respectively.

}
\author{Paul Murrell}
\seealso{
  \link{Grid},
  \code{\link{viewport}}
}
\examples{
pathSample <- function(x, y, rule, gp=gpar()) {
    if (is.na(rule))
        grid.path(x, y, id=rep(1:2, each=4), gp=gp)
    else 
        grid.path(x, y, id=rep(1:2, each=4), rule=rule, gp=gp)
    if (!is.na(rule))
        grid.text(paste("Rule:", rule), y=0, just="bottom")
}

pathTriplet <- function(x, y, title) {
    pushViewport(viewport(height=0.9, layout=grid.layout(1, 3),
                          gp=gpar(cex=.7)))
    grid.rect(y=1, height=unit(1, "char"), just="top",
              gp=gpar(col=NA, fill="grey"))
    grid.text(title, y=1, just="top")
    pushViewport(viewport(layout.pos.col=1))
    pathSample(x, y, rule="winding",
               gp=gpar(fill="grey"))
    popViewport()
    pushViewport(viewport(layout.pos.col=2))
    pathSample(x, y, rule="evenodd",
               gp=gpar(fill="grey"))
    popViewport()
    pushViewport(viewport(layout.pos.col=3))
    pathSample(x, y, rule=NA)
    popViewport()
    popViewport()
}

pathTest <- function() {
    grid.newpage()
    pushViewport(viewport(layout=grid.layout(5, 1)))
    pushViewport(viewport(layout.pos.row=1))
    pathTriplet(x=c(.1, .1, .9, .9, .2, .2, .8, .8),
                y=c(.1, .9, .9, .1, .2, .8, .8, .2),
                title="Nested rectangles, both clockwise")
    popViewport()
    pushViewport(viewport(layout.pos.row=2))
    pathTriplet(x=c(.1, .1, .9, .9, .2, .8, .8, .2),
                y=c(.1, .9, .9, .1, .2, .2, .8, .8),
                title="Nested rectangles, outer clockwise, inner anti-clockwise")
    popViewport()
    pushViewport(viewport(layout.pos.row=3))
    pathTriplet(x=c(.1, .1, .4, .4, .6, .9, .9, .6),
                y=c(.1, .4, .4, .1, .6, .6, .9, .9),
                title="Disjoint rectangles")
    popViewport()
    pushViewport(viewport(layout.pos.row=4))
    pathTriplet(x=c(.1, .1, .6, .6, .4, .4, .9, .9),
                y=c(.1, .6, .6, .1, .4, .9, .9, .4),
                title="Overlapping rectangles, both clockwise")
    popViewport()
    pushViewport(viewport(layout.pos.row=5))
    pathTriplet(x=c(.1, .1, .6, .6, .4, .9, .9, .4),
                y=c(.1, .6, .6, .1, .4, .4, .9, .9),
                title="Overlapping rectangles, one clockwise, other anti-clockwise")
    popViewport()
    popViewport()
}

pathTest()
}
\keyword{dplot}