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