asymptote: draw
4.1 draw
========
void draw(picture pic=currentpicture, Label L="", path g,
align align=NoAlign, pen p=currentpen,
arrowbar arrow=None, arrowbar bar=None, margin margin=NoMargin,
Label legend="", marker marker=nomarker);
Draw the path 'g' on the picture 'pic' using pen 'p' for drawing,
with optional drawing attributes (Label 'L', explicit label alignment
'align', arrows and bars 'arrow' and 'bar', margins 'margin', legend,
and markers 'marker'). Only one parameter, the path, is required. For
convenience, the arguments 'arrow' and 'bar' may be specified in either
order. The argument 'legend' is a Label to use in constructing an
optional legend entry.
Bars are useful for indicating dimensions. The possible values of
'bar' are 'None', 'BeginBar', 'EndBar' (or equivalently 'Bar'), and
'Bars' (which draws a bar at both ends of the path). Each of these bar
specifiers (except for 'None') will accept an optional real argument
that denotes the length of the bar in 'PostScript' coordinates. The
default bar length is 'barsize(pen)'.
The possible values of 'arrow' are 'None', 'Blank' (which draws no
arrows or path), 'BeginArrow', 'MidArrow', 'EndArrow' (or equivalently
'Arrow'), and 'Arrows' (which draws an arrow at both ends of the path).
All of the arrow specifiers except for 'None' and 'Blank' may be given
the optional arguments arrowhead 'arrowhead' (one of the predefined
arrowhead styles 'DefaultHead', 'SimpleHead', 'HookHead', 'TeXHead'),
real 'size' (arrowhead size in 'PostScript' coordinates), real 'angle'
(arrowhead angle in degrees), filltype 'filltype' (one of 'FillDraw',
'Fill', 'NoFill', 'UnFill', 'Draw') and (except for 'MidArrow' and
'Arrows') a real 'position' (in the sense of 'point(path p, real t)')
along the path where the tip of the arrow should be placed. The default
arrowhead size when drawn with a pen 'p' is 'arrowsize(p)'. There are
also arrow versions with slightly modified default values of 'size' and
'angle' suitable for curved arrows: 'BeginArcArrow', 'EndArcArrow' (or
equivalently 'ArcArrow'), 'MidArcArrow', and 'ArcArrows'.
Margins can be used to shrink the visible portion of a path by
'labelmargin(p)' to avoid overlap with other drawn objects. Typical
values of 'margin' are 'NoMargin', 'BeginMargin', 'EndMargin' (or
equivalently 'Margin'), and 'Margins' (which leaves a margin at both
ends of the path). One may use 'Margin(real begin, real end)' to
specify the size of the beginning and ending margin, respectively, in
multiples of the units 'labelmargin(p)' used for aligning labels.
Alternatively, 'BeginPenMargin', 'EndPenMargin' (or equivalently
'PenMargin'), 'PenMargins', 'PenMargin(real begin, real end)' specify a
margin in units of the pen line width, taking account of the pen line
width when drawing the path or arrow. For example, use 'DotMargin', an
abbreviation for 'PenMargin(-0.5*dotfactor,0.5*dotfactor)', to draw from
the usual beginning point just up to the boundary of an end dot of width
'dotfactor*linewidth(p)'. The qualifiers 'BeginDotMargin',
'EndDotMargin', and 'DotMargins' work similarly. The qualifier
'TrueMargin(real begin, real end)' allows one to specify a margin
directly in 'PostScript' units, independent of the pen line width.
The use of arrows, bars, and margins is illustrated by the examples
'Pythagoras.asy', 'sqrtx01.asy', and 'triads.asy'.
The legend for a picture 'pic' can be fit and aligned to a frame with
the routine:
frame legend(picture pic=currentpicture, int perline=1,
real xmargin=legendmargin, real ymargin=xmargin,
real linelength=legendlinelength,
real hskip=legendhskip, real vskip=legendvskip,
real maxwidth=0, real maxheight=0,
bool hstretch=false, bool vstretch=false, pen p=currentpen);
Here 'xmargin' and 'ymargin' specify the surrounding x and y margins,
'perline' specifies the number of entries per line (default 1; 0 means
choose this number automatically), 'linelength' specifies the length of
the path lines, 'hskip' and 'vskip' specify the line skip (as a multiple
of the legend entry size), 'maxwidth' and 'maxheight' specify optional
upper limits on the width and height of the resulting legend (0 means
unlimited), 'hstretch' and 'vstretch' allow the legend to stretch
horizontally or vertically, and 'p' specifies the pen used to draw the
bounding box. The legend frame can then be added and aligned about a
point on a picture 'dest' using 'add' or 'attach' (add about).
To draw a dot, simply draw a path containing a single point. The
'dot' command defined in the module 'plain' draws a dot having a
diameter equal to an explicit pen line width or the default line width
magnified by 'dotfactor' (6 by default), using the specified filltype
(filltype):
void dot(picture pic=currentpicture, pair z, pen p=currentpen,
filltype filltype=Fill);
void dot(picture pic=currentpicture, Label L, pair z, align align=NoAlign,
string format=defaultformat, pen p=currentpen, filltype filltype=Fill);
void dot(picture pic=currentpicture, Label[] L=new Label[], pair[] z,
align align=NoAlign, string format=defaultformat, pen p=currentpen,
filltype filltype=Fill)
void dot(picture pic=currentpicture, Label L, pen p=currentpen,
filltype filltype=Fill);
If the variable 'Label' is given as the 'Label' argument to the
second routine, the 'format' argument will be used to format a string
based on the dot location (here 'defaultformat' is '"$%.4g$"'). The
third routine draws a dot at every point of a pair array 'z'. One can
also draw a dot at every node of a path:
void dot(picture pic=currentpicture, Label[] L=new Label[],
path g, align align=RightSide, string format=defaultformat,
pen p=currentpen, filltype filltype=Fill);
See pathmarkers and markers for more general methods
for marking path nodes.
To draw a fixed-sized object (in 'PostScript' coordinates) about the
user coordinate 'origin', use the routine
void draw(pair origin, picture pic=currentpicture, Label L="", path g,
align align=NoAlign, pen p=currentpen, arrowbar arrow=None,
arrowbar bar=None, margin margin=NoMargin, Label legend="",
marker marker=nomarker);