1% File src/library/grid/man/grid.curve.Rd
2% Part of the R package, https://www.R-project.org
3% Copyright 1995-2020 R Core Team
4% Distributed under GPL 2 or later
5
6\name{grid.curve}
7\alias{grid.curve}
8\alias{curveGrob}
9\alias{arcCurvature}
10\title{ Draw a Curve Between Locations }
11\concept{connector}
12\description{
13  These functions create and draw a curve from one location
14  to another.
15}
16\usage{
17grid.curve(...)
18curveGrob(x1, y1, x2, y2, default.units = "npc",
19          curvature = 1, angle = 90, ncp = 1, shape = 0.5,
20          square = TRUE, squareShape = 1,
21          inflect = FALSE, arrow = NULL, open = TRUE,
22          debug = FALSE,
23          name = NULL, gp = gpar(), vp = NULL)
24arcCurvature(theta)
25}
26\arguments{
27  \item{x1}{A numeric vector or unit object specifying the x-location of
28    the start point.}
29  \item{y1}{A numeric vector or unit object specifying the y-location of
30    the start point.}
31  \item{x2}{A numeric vector or unit object specifying the x-location of
32    the end point.}
33  \item{y2}{A numeric vector or unit object specifying the y-location of
34    the end point.}
35  \item{default.units}{A string indicating the default units to use
36    if \code{x1}, \code{y1}, \code{x2} or \code{y2}
37    are only given as numeric values.}
38  \item{curvature}{A numeric value giving the amount of curvature.
39    Negative values produce left-hand curves, positive values
40    produce right-hand curves, and zero produces a straight line.}
41  \item{angle}{A numeric value between 0 and 180,
42    giving an amount to skew the control
43    points of the curve.  Values less than 90 skew the curve towards
44    the start point and values greater than 90 skew the curve
45    towards the end point.}
46  \item{ncp}{The number of control points used to draw the curve.
47    More control points creates a smoother curve.}
48  \item{shape}{A numeric vector of values between -1 and 1, which
49    control the shape of the curve relative to its control points.
50    See \code{grid.xspline} for more details.}
51  \item{square}{A logical value that controls whether control
52    points for the curve are created city-block fashion or
53    obliquely.  When \code{ncp} is 1 and \code{angle} is 90,
54    this is typically \code{TRUE}, otherwise this should probably
55    be set to \code{FALSE} (see Examples below).}
56  \item{squareShape}{A \code{shape} value to control the behaviour
57    of the curve relative to any additional control point that
58    is inserted if \code{square} is \code{TRUE}.}
59  \item{inflect}{A logical value specifying whether the curve
60    should be cut in half and inverted (see Examples below).}
61  \item{arrow}{A list describing arrow heads to place at either end
62    of the curve, as produced by the \code{arrow} function.}
63  \item{open}{A logical value indicating whether to close the curve
64    (connect the start and end points).}
65  \item{debug}{A logical value indicating whether debugging
66    information should be drawn.}
67  \item{name}{ A character identifier. }
68  \item{gp}{An object of class \code{"gpar"}, typically the output
69    from a call to the function \code{\link{gpar}}.  This is basically
70    a list of graphical parameter settings.}
71  \item{vp}{A Grid viewport object (or NULL).}
72  \item{\dots}{Arguments to be passed to \code{curveGrob}.}
73  \item{theta}{An angle (in degrees).}
74}
75\value{
76  A grob object.
77}
78\details{
79  Both functions create a curve grob (a graphical object describing an
80  curve), but only \code{grid.curve}
81  draws the curve.
82
83  The \code{arcCurvature} function can be used to calculate a
84  \code{curvature} such that control points are generated on
85  an arc corresponding to angle \code{theta}.  This is typically
86  used in conjunction with a large \code{ncp} to produce a curve
87  corresponding to the desired arc.
88}
89\seealso{
90  \link{Grid},
91  \code{\link{viewport}},
92  \code{\link{grid.xspline}},
93  \code{\link{arrow}}
94}
95\examples{
96curveTest <- function(i, j, ...) {
97  pushViewport(viewport(layout.pos.col=j, layout.pos.row=i))
98  do.call("grid.curve", c(list(x1=.25, y1=.25, x2=.75, y2=.75), list(...)))
99  grid.text(sub("list\\\\((.*)\\\\)", "\\\\1",
100                deparse(substitute(list(...)))),
101            y=unit(1, "npc"))
102  popViewport()
103}
104# grid.newpage()
105pushViewport(plotViewport(c(0, 0, 1, 0),
106                          layout=grid.layout(2, 1, heights=c(2, 1))))
107pushViewport(viewport(layout.pos.row=1,
108                      layout=grid.layout(3, 3, respect=TRUE)))
109curveTest(1, 1)
110curveTest(1, 2, inflect=TRUE)
111curveTest(1, 3, angle=135)
112curveTest(2, 1, arrow=arrow())
113curveTest(2, 2, ncp=8)
114curveTest(2, 3, shape=0)
115curveTest(3, 1, curvature=-1)
116curveTest(3, 2, square=FALSE)
117curveTest(3, 3, debug=TRUE)
118popViewport()
119pushViewport(viewport(layout.pos.row=2,
120                      layout=grid.layout(3, 3)))
121curveTest(1, 1)
122curveTest(1, 2, inflect=TRUE)
123curveTest(1, 3, angle=135)
124curveTest(2, 1, arrow=arrow())
125curveTest(2, 2, ncp=8)
126curveTest(2, 3, shape=0)
127curveTest(3, 1, curvature=-1)
128curveTest(3, 2, square=FALSE)
129curveTest(3, 3, debug=TRUE)
130popViewport(2)
131}
132\keyword{dplot}
133