\HeaderA{grid.lines}{Draw Lines in a Grid Viewport}{grid.lines}
\aliasA{grid.polyline}{grid.lines}{grid.polyline}
\aliasA{linesGrob}{grid.lines}{linesGrob}
\aliasA{polylineGrob}{grid.lines}{polylineGrob}
\keyword{dplot}{grid.lines}
\begin{Description}\relax
These functions create and draw a series of lines.
\end{Description}
\begin{Usage}
\begin{verbatim}
grid.lines(x = unit(c(0, 1), "npc", units.per.obs),
          y = unit(c(0, 1), "npc", units.per.obs), 
          default.units = "npc", units.per.obs = FALSE,
          arrow = NULL, name = NULL,
          gp=gpar(), draw = TRUE, vp = NULL)
linesGrob(x = unit(c(0, 1), "npc", units.per.obs),
          y = unit(c(0, 1), "npc", units.per.obs), 
          default.units = "npc", units.per.obs = FALSE,
          arrow = NULL, name = NULL,
          gp=gpar(), vp = NULL)
grid.polyline(...)
polylineGrob(x = unit(c(0, 1), "npc"),
             y = unit(c(0, 1), "npc"), 
             id=NULL, id.lengths=NULL,
             default.units = "npc", 
             arrow = NULL, name = NULL,
             gp=gpar(), vp = NULL)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] A numeric vector or unit object specifying x-values.
\item[\code{y}] A numeric vector or unit object specifying y-values.
\item[\code{default.units}] A string indicating the default units to use
if \code{x} or \code{y} are only given as numeric vectors.
\item[\code{units.per.obs}] A logical value to indicate whether each
individual (x, y) location has its own unit(s) specified.
\item[\code{arrow}] A list describing arrow heads to place at either end
of the line, as produced by the \code{arrow} function.
\item[\code{name}] A character identifier. 
\item[\code{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[\code{draw}] A logical value indicating whether graphics output
should be produced.
\item[\code{vp}] A Grid viewport object (or NULL).
\item[\code{id}] A numeric vector used to separate locations in \code{x} and
\code{y} into multiple lines.  All locations with the same
\code{id} belong to the same line.
\item[\code{id.lengths}] A numeric vector used to separate locations in \code{x} and
\code{y} into multiple lines.  Specifies consecutive blocks of
locations which make up separate lines.
\item[\code{...}] Arguments passed to \code{polylineGrob}.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The first two functions create a lines grob (a graphical object describing
lines), and \code{grid.lines}
draws the lines (if \code{draw} is \code{TRUE}).

The second two functions create or draw a polyline grob,
which is just like a lines grob, except that there can be
multiple distinct lines drawn.
\end{Details}
\begin{Value}
A lines grob or a polyline grob.
\code{grid.lines} returns a lines grob invisibly.
\end{Value}
\begin{Author}\relax
Paul Murrell
\end{Author}
\begin{SeeAlso}\relax
\LinkA{Grid}{Grid},
\code{\LinkA{viewport}{viewport}},
\code{\LinkA{arrow}{arrow}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
grid.lines()
# Using id (NOTE: locations are not in consecutive blocks)
grid.newpage()
grid.polyline(x=c((0:4)/10, rep(.5, 5), (10:6)/10, rep(.5, 5)),
             y=c(rep(.5, 5), (10:6/10), rep(.5, 5), (0:4)/10),
             id=rep(1:5, 4),
             gp=gpar(col=1:5, lwd=3))
# Using id.lengths
grid.newpage()
grid.polyline(x=outer(c(0, .5, 1, .5), 5:1/5),
             y=outer(c(.5, 1, .5, 0), 5:1/5),
             id.lengths=rep(4, 5),
             gp=gpar(col=1:5, lwd=3))
\end{ExampleCode}
\end{Examples}

