%{
//
dynload "libatsdoc/dynloadall.dats"
#include "utils/atsdoc/DOCUMENT/TUTORIALATS/tutorialatxt.dats"
//
#include "./ATEXT/ats2cairo.dats"
//
%}\
#comment("\n\
The file is automatically generated by [atsdoc] from chap_drawline.atxt.\n\
")
#comment("\n\
Time of Generation: #timestamp()\
")
<chapter id="drawline">
#title("Drawing Lines")

#para('\

In cairo, drawing often starts with the construction of a path consisting
of a sequence of points. For example, the function
#dyncode("draw_triangle") for drawing a path connecting three points is
given as follows:

')

#atscode("\
fun
draw_triangle{l:agz}
(
  cr: !cairo_ref l
, x0: double, y0: double
, x1: double, y1: double
, x2: double, y2: double
) : void = () where {
  val () = cairo_move_to (cr, x0, y0)
  val () = cairo_line_to (cr, x1, y1)
  val () = cairo_line_to (cr, x2, y2)
  val () = cairo_close_path (cr)
} (* end of [draw_triangle] *)
")

#para('\

The functions involved in the body of #dyncode("draw_triangle") are
assigned the following types in ATS:

')

#atscode('\
fun cairo_move_to {l:agz} (cr: !cairo_ref l, x: double, y: double): void

fun cairo_line_to {l:agz} (cr: !cairo_ref l, x: double, y: double): void

fun cairo_close_path {l:agz} (cr: !cairo_ref l): void
')

#para('\

When called, #dyncode("cairo_move_to") starts a new (sub)path whose initial
point is (x, y) and #dyncode("cairo_line_to") connects the current point on
the current path to (x, y) and then set (x, y) to be the current point. The
function #dyncode("cairo_close_path") simply adds a segment connecting the
current point to the initial point of the current (sub)path.

')

#para('\

There is also a function #dyncode("cairo_rel_line_to") of the following type:

')

#atscode('\
fun cairo_rel_line_to {l:agz} (cr: !cairo_ref l, x: double, y: double): void
')

#para('\

This function is similar to #dyncode("cairo_line_to") except for (x, y) being
relative to the current point on the current (sub)path.\

')

#para('\

Once a path is constructed, #dyncode("cairo_stroke") can be called to draw
line segments along the path:

#atscode('\
fun cairo_stroke {l:agz} (cr: !cairo_ref l) : void
')

There are a few line attributes that can be
set in cairo. For instance, the styles of line cap and line join as well as
the width of line can be set by the following functions:\

')

#atscode('\
fun cairo_set_line_cap {l:agz} (cr: !cairo_ref l, line_cap: cairo_line_cap_t): void

fun cairo_set_line_join {l:agz} (cr: !cairo_ref l, line_join: cairo_line_join_t): void

fun cairo_set_line_width {l:agz} (cr: !cairo_ref l, width: double): void
')

#para("\

The following styles of line cap are supported:\

")

#atscode('\
CAIRO_LINE_CAP_BUTT
CAIRO_LINE_CAP_ROUND
CAIRO_LINE_CAP_SQUARE
')

#para('\
and the following lines, from left to right, are drawn according to these
styles, respectively:
')

#para('\
<inlinemediaobject>
<imageobject>
<imagedata fileref="#MYIMAGEROOTget()/tutprog_linecap.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
')

#para('\
The following styles of line join are supported:
')

#atscode('\
CAIRO_LINE_JOIN_MITER
CAIRO_LINE_JOIN_ROUND
CAIRO_LINE_JOIN_BEVEL
')

#para('\
and the following triangles, from left to right, are drawn according to these
styles, respectively:
')

#para('\
<inlinemediaobject>
<imageobject>
<imagedata fileref="#MYIMAGEROOTget()/tutprog_linejoin.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
')

#para('\
There is also a function #dyncode("cairo_set_dash") for setting up
line dash pattern.
')

#comment("
#para('\

Please find in #mycodelink("tutprog_triangle.dats",
"tutprog_triangle.dats") a program with a GUI interface that employes the
function #dyncode("draw_triangle") to draw randomly generated triangles.\

')
")

<!-- ****** ****** -->

</chapter>#comment("chapter/drawline")

#comment(" ****** ****** ")

#comment(" end of [chap_drawline.atxt] ")

%{
implement main () = fprint_filsub (stdout_ref, "chap_drawline_atxt.txt")
%}
