Module 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.

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.

Clears the current path. After this call there will be no path and no current point.

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.

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.

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.

fold cr f folds f over all elements of the path.