Cairo.Path
Creates a copy of the current path. See cairo_path_data_t for hints on how to iterate over the returned data structure.
Gets a flattened copy of the current path.
This function is like Cairo.Path.copy
except that any curves in the path will be approximated with piecewise-linear approximations (accurate to within the current tolerance value). That is, the result is guaranteed to not have any elements of type CURVE_TO
which will instead be replaced by a series of LINE_TO
elements.
Append the path onto the current path. The path may be either the return value from one of Cairo.Path.copy
or Cairo.Path.copy_flat
or it may be constructed manually.
val get_current_point : context -> float * float
get_current_point cr
gets the (x,y) coordinates of the current point of the current path, which is conceptually the final point reached by the path so far. The current point is returned in the user-space coordinate system.
Raise Error NO_CURRENT_POINT
if there is no defined current point.
Most path construction functions alter the current point. See the following for details on how they affect the current point: Cairo.Path.clear
, Cairo.Path.sub
, Cairo.Path.append
, Cairo.Path.close
, Cairo.move_to
, Cairo.line_to
, Cairo.curve_to
, Cairo.rel_move_to
, Cairo.rel_line_to
, Cairo.rel_curve_to
, Cairo.arc
, Cairo.arc_negative
, Cairo.rectangle
, Cairo.Path.text
, Cairo.Path.glyph
.
Some functions use and alter the current point but do not otherwise change current path: Cairo.show_text
.
Some functions unset the current path and as a result, current point: Cairo.fill
, Cairo.stroke
.
val clear : context -> unit
Clears the current path. After this call there will be no path and no current point.
val sub : context -> unit
Begin a new sub-path. Note that the existing path is not affected. After this call there will be no current point.
In many cases, this call is not needed since new sub-paths are frequently started with Cairo.move_to
.
A call to Cairo.Path.sub
is particularly useful when beginning a new sub-path with one of the Cairo.arc
calls. This makes things easier as it is no longer necessary to manually compute the arc's initial coordinates for a call to Cairo.move_to
.
val close : context -> unit
Adds a line segment to the path from the current point to the beginning of the current sub-path (the most recent point passed to Cairo.move_to
) and closes this sub-path. After this call the current point will be at the joined endpoint of the sub-path.
The behavior of Cairo.Path.close
is distinct from simply calling Cairo.line_to
with the equivalent coordinate in the case of stroking. When a closed sub-path is stroked, there are no caps on the ends of the sub-path. Instead, there is a line join connecting the final and initial segments of the sub-path.
If there is no current point before the call to close
, this function will have no effect.
Note: As of cairo version 1.2.4 any call to close
will place an explicit MOVE_TO
element into the path immediately after the CLOSE_PATH
element (which can be seen in Cairo.Path.copy
for example). This can simplify path processing in some cases as it may not be necessary to save the "last move_to point" during processing as the MOVE_TO
immediately after the CLOSE_PATH
will provide that point.
Adds closed paths for the glyphs to the current path. The generated path if filled, achieves an effect similar to that of Cairo.Glyph.show
.
val text : context -> string -> unit
text cr utf8
adds closed paths for text to the current path. The generated path if filled, achieves an effect similar to that of Cairo.show_text
. utf8
should be a valid UTF8 string containing no '\000'
characters.
Text conversion and positioning is done similar to Cairo.show_text
.
Like Cairo.show_text
, after this call the current point is moved to the origin of where the next glyph would be placed in this same progression. That is, the current point will be at the origin of the final glyph offset by its advance values. This allows for chaining multiple calls to to text
without having to set current point in between.
Note: The text
function call is part of what the cairo designers call the "toy" text API. It is convenient for short demos and simple programs, but it is not expected to be adequate for serious text-using applications. See Cairo.Path.glyph
for the "real" text path API in cairo.
Computes a bounding box in user-space coordinates covering the points on the current path. If the current path is empty, returns an empty rectangle { x=0.; y=0.; w=0.; h=0. }
. Stroke parameters, fill rule, surface dimensions and clipping are not taken into account.
Contrast with Cairo.fill_extents
and Cairo.stroke_extents
which return the extents of only the area that would be "inked" by the corresponding drawing operations.
The result of Cairo.Path.extents
is defined as equivalent to the limit of Cairo.stroke_extents
with ROUND
as the line width approaches 0.0 (but never reaching the empty-rectangle returned by Cairo.stroke_extents
for a line width of 0.0).
Specifically, this means that zero-area sub-paths such as Cairo.move_to
and Cairo.line_to
segments (even degenerate cases where the coordinates to both calls are identical) will be considered as contributing to the extents. However, a lone Cairo.move_to
will not contribute to the results of Cairo.Path.extents
.