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

\name{polypath}
\alias{polypath}
\title{Path Drawing}
\description{
  \code{path} draws a path whose vertices are
  given in \code{x} and \code{y}.
}
\usage{
polypath(x, y = NULL,
         border = NULL, col = NA, lty = par("lty"),
         rule = "winding", \dots)
}
\arguments{
  \item{x, y}{vectors containing the coordinates of the vertices
    of the path.}
   \item{col}{the color for filling the path. The default,
     \code{NA}, is to leave paths unfilled, unless \code{density} is
     specified.  (For back-compatibility, \code{NULL} is equivalent to
     \code{NA}.)  If \code{density} is specified with a positive value
     this gives the color of the shading lines.}
  \item{border}{the color to draw the border.  The default, \code{NULL},
    means to use \code{\link{par}("fg")}.  Use \code{border = NA} to
    omit borders.

    For compatibility with S, \code{border} can also be logical, in
    which case \code{FALSE} is equivalent to \code{NA} (borders omitted)
    and \code{TRUE} is equivalent to \code{NULL} (use the foreground colour),
  }
  \item{lty}{the line type to be used, as in \code{\link{par}}.}
  \item{rule}{character value specifying the path fill mode: either
    \code{"winding"} or \code{"evenodd"}.}
  \item{\dots}{\link{graphical parameters} such as \code{xpd}, \code{lend},
    \code{ljoin} and \code{lmitre} can be given as arguments.}
}
\details{
  The coordinates can be passed in a plotting structure
  (a list with \code{x} and \code{y} components), a two-column matrix,
  \dots.  See \code{\link{xy.coords}}.

  It is assumed that the path is to be closed by joining the last point to
  the first point.

  The coordinates can contain missing values.  The behaviour is similar
  to that of \code{\link{polygon}}, except that instead of breaking a
  polygon into several polygons, \code{NA} values break the path into
  several sub-paths (including closing the last point to the first point
  in each sub-path).  See the examples below.

  The distinction between a path and a polygon is 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.

  Hatched shading (as implemented for \code{polygon()}) is not
  (currently) supported.

  Not all graphics devices support this function: for example
  \code{xfig} and \code{pictex} do not.
}
\references{
  Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)
  \emph{The New S Language}.
  Wadsworth & Brooks/Cole.

  Murrell, P. (2005) \emph{R Graphics}. Chapman & Hall/CRC Press.
}
\seealso{
  \code{\link{segments}} for even more flexibility, \code{\link{lines}},
  \code{\link{rect}}, \code{\link{box}}, \code{\link{polygon}}.

  \code{\link{par}} for how to specify colors.
}
\examples{
plotPath <- function(x, y, col = "grey", rule = "winding") {
    plot.new()
    plot.window(range(x, na.rm = TRUE), range(y, na.rm = TRUE))
    polypath(x, y, col = col, rule = rule)
    if (!is.na(col))
        mtext(paste("Rule:", rule), side = 1, line = 0)
}

plotRules <- function(x, y, title) {
    plotPath(x, y)
    plotPath(x, y, rule = "evenodd")
    mtext(title, side = 3, line = 0)
    plotPath(x, y, col = NA)
}

op <- par(mfrow = c(5, 3), mar = c(2, 1, 1, 1))

plotRules(c(.1, .1, .9, .9, NA, .2, .2, .8, .8),
          c(.1, .9, .9, .1, NA, .2, .8, .8, .2),
          "Nested rectangles, both clockwise")
plotRules(c(.1, .1, .9, .9, NA, .2, .8, .8, .2),
          c(.1, .9, .9, .1, NA, .2, .2, .8, .8),
          "Nested rectangles, outer clockwise, inner anti-clockwise")
plotRules(c(.1, .1, .4, .4, NA, .6, .9, .9, .6),
          c(.1, .4, .4, .1, NA, .6, .6, .9, .9),
          "Disjoint rectangles")
plotRules(c(.1, .1, .6, .6, NA, .4, .4, .9, .9),
          c(.1, .6, .6, .1, NA, .4, .9, .9, .4),
          "Overlapping rectangles, both clockwise")
plotRules(c(.1, .1, .6, .6, NA, .4, .9, .9, .4),
          c(.1, .6, .6, .1, NA, .4, .4, .9, .9),
          "Overlapping rectangles, one clockwise, other anti-clockwise")

par(op)
}
\keyword{aplot}