Drawing Context
#### Context.status()Checks whether an error has previously occurred for this context.
Returns: the current status of this context, see Status
Makes a copy of the current state of cr and saves it
on an internal stack of saved states for cr. When
Context.restore() is called, cr will be restored to
the saved state. Multiple calls to Context.save() and
Context.restore() can be nested; each call to Context.restore()
restores the state from the matching paired Context.save().
It isn't necessary to clear all saved states before
a Context is freed. If the reference count of a Context
drops to zero in response to a call to Context.destroy(),
any saved states will be freed along with the Context.
Restores cr to the state saved by a preceding call to
Context.save() and removes that state from the stack of
saved states.
Gets the target surface for the cairo context as passed to
Context.new().
This function will always return a valid pointer, but the result
can be a "nil" surface if cr is already in an error state,
(ie. Context.status() != "success").
A nil surface is indicated by Surface.status()
!= "success".
Return value: the target surface. This object is owned by cairo. To
keep a reference to it, you must call Surface.reference().
Temporarily redirects drawing to an intermediate surface known as a
group. The redirection lasts until the group is completed by a call
to Context.popGroup() or Context.popGroupToSource(). These calls
provide the result of any drawing to the group as a pattern,
(either as an explicit object, or set as the source pattern).
This group functionality can be convenient for performing intermediate compositing. One common use of a group is to render objects as opaque within the group, (so that they occlude each other), and then blend the result with translucence onto the destination.
Groups can be nested arbitrarily deep by making balanced calls to
Context.pushGroup()/cairoPopGroup(). Each call pushes/pops the new
target group onto/from a stack.
The Context.pushGroup() function calls Context.save() so that any
changes to the graphics state will not be visible outside the
group, (the pop_group functions call Context.restore()).
By default the intermediate group will have a content type of
"color-alpha". Other content types can be chosen for
the group by using Context.pushGroupWithContent() instead.
As an example, here is how one might fill and stroke a path with translucence, but without any portion of the fill being visible under the stroke:
cairo_push_group (cr);
cairo_set_source (cr, fill_pattern);
cairo_fill_preserve (cr);
cairo_set_source (cr, stroke_pattern);
cairo_stroke (cr);
cairo_pop_group_to_source (cr);
cairo_paint_with_alpha (cr, alpha);Temporarily redirects drawing to an intermediate surface known as a
group. The redirection lasts until the group is completed by a call
to Context.popGroup() or Context.popGroupToSource(). These calls
provide the result of any drawing to the group as a pattern,
(either as an explicit object, or set as the source pattern).
The group will have a content type of content. The ability to
control this content type is the only distinction between this
function and Context.pushGroup() which you should see for a more
detailed description of group rendering.
Terminates the redirection begun by a call to Context.pushGroup() or
Context.pushGroupWithContent() and returns a new pattern
containing the results of all drawing operations performed to the
group.
The Context.popGroup() function calls Context.restore(), (balancing a
call to Context.save() by the push_group function), so that any
changes to the graphics state will not be visible outside the
group.
Return value: a newly created (surface) pattern containing the
results of all drawing operations performed to the group. The
caller owns the returned object and should call
Pattern.destroy() when finished with it.
Terminates the redirection begun by a call to Context.pushGroup() or
Context.pushGroupWithContent() and installs the resulting pattern
as the source pattern in the given cairo context.
The behavior of this function is equivalent to the sequence of operations:
cairo_pattern_t *group = cairo_pop_group (cr);
cairo_set_source (cr, group);
cairo_pattern_destroy (group);but is more convenient as their is no need for a variable to store the short-lived pointer to the pattern.
The Context.popGroup() function calls Context.restore(), (balancing a
call to Context.save() by the push_group function), so that any
changes to the graphics state will not be visible outside the
group.
Gets the current destination surface for the context. This is either
the original target surface as passed to Context.new() or the target
surface for the current group as started by the most recent call to
Context.pushGroup() or Context.pushGroupWithContent().
This function will always return a valid pointer, but the result
can be a "nil" surface if cr is already in an error state,
(ie. Context.status() != "success").
A nil surface is indicated by Surface.status()
!= "success".
Return value: the target surface. This object is owned by cairo. To
keep a reference to it, you must call Surface.reference().
Sets the source pattern within cr to source. This pattern
will then be used for any subsequent drawing operation until a new
source pattern is set.
Note: The pattern's transformation matrix will be locked to the
user space in effect at the time of Context.setSource(). This means
that further modifications of the current transformation matrix
will not affect the source pattern. See Pattern.setMatrix().
The default source pattern is a solid pattern that is opaque black, (that is, it is equivalent to cairo_set_source_rgb(cr, 0.0, 0.0, 0.0)).
#### Context.setSourceSurface()This is a convenience function for creating a pattern from surface
and setting it as the source in cr with Context.setSource().
The x and y parameters give the user-space coordinate at which
the surface origin should appear. (The surface origin is its
upper-left corner before any transformation has been applied.) The
x and y parameters are negated and then set as translation values
in the pattern matrix.
Other than the initial translation pattern matrix, as described
above, all other pattern attributes, (such as its extend mode), are
set to the default values as in Pattern.createForSurface().
The resulting pattern can be queried with Context.getSource() so
that these attributes can be modified if desired, (eg. to create a
repeating pattern with Pattern.setExtend()).
Gets the current source pattern for cr.
Return value: the current source pattern. This object is owned by
cairo. To keep a reference to it, you must call
Pattern.reference().
Set the antialiasing mode of the rasterizer used for drawing shapes.
This value is a hint, and a particular backend may or may not support
a particular value. At the current time, no backend supports
"subpixel" when drawing shapes.
Note that this option does not affect text rendering, instead see
FontOptions.setAntialias().
Gets the current shape antialiasing mode, as set by
Context.setAntialias().
Return value: the current shape antialiasing mode.
#### Context.setDash()Sets the dash pattern to be used by Context.stroke(). A dash pattern
is specified by dashes, an array of positive values. Each value
provides the length of alternate "on" and "off" portions of the
stroke. The offset specifies an offset into the pattern at which
the stroke begins.
Each "on" segment will have caps applied as if the segment were a
separate sub-path. In particular, it is valid to use an "on" length
of 0.0 with "round" or "square" in order
to distributed dots or squares along a path.
Note: The length values are in user-space units as evaluated at the
time of stroking. This is not necessarily the same as the user
space at the time of Context.setDash().
If num_dashes is 0 dashing is disabled.
If num_dashes is 1 a symmetric pattern is assumed with alternating
on and off portions of the size specified by the single value in
dashes.
If any value in dashes is negative, or if all values are 0, then
cr will be put into an error state with a status of
"invalid-dash".
This function returns the length of the dash array in cr (0 if dashing
is not currently in effect).
See also Context.setDash() and Context.getDash().
Return value: the length of the dash array, or 0 if no dash array set.
#### Context.getDash()Gets the current dash array. If not nil, dashes should be big
enough to hold at least the number of values returned by
Context.getDashCount().
Set the current fill rule within the cairo context. The fill rule
is used to determine which regions are inside or outside a complex
(potentially self-intersecting) path. The current fill rule affects
both Context.fill() and Context.clip(). See FillRule for details
on the semantics of each available fill rule.
The default fill rule is "winding".
Gets the current fill rule, as set by Context.setFillRule().
Return value: the current fill rule.
#### Context.setLineCap()Sets the current line cap style within the cairo context. See
LineCap for details about how the available line cap
styles are drawn.
As with the other stroke parameters, the current line cap style is
examined by Context.stroke(), Context.strokeExtents(), and
Context.strokeToPath(), but does not have any effect during path
construction.
The default line cap style is "butt".
Gets the current line cap style, as set by Context.setLineCap().
Return value: the current line cap style.
#### Context.setLineJoin()Sets the current line join style within the cairo context. See
LineJoin for details about how the available line join
styles are drawn.
As with the other stroke parameters, the current line join style is
examined by Context.stroke(), Context.strokeExtents(), and
Context.strokeToPath(), but does not have any effect during path
construction.
The default line join style is "miter".
Gets the current line join style, as set by Context.setLineJoin().
Return value: the current line join style.
#### Context.setLineWidth()Sets the current line width within the cairo context. The line width value specifies the diameter of a pen that is circular in user space, (though device-space pen may be an ellipse in general due to scaling/shear/rotation of the CTM).
Note: When the description above refers to user space and CTM it
refers to the user space and CTM in effect at the time of the
stroking operation, not the user space and CTM in effect at the
time of the call to Context.setLineWidth(). The simplest usage
makes both of these spaces identical. That is, if there is no
change to the CTM between a call to Context.setLineWidth() and the
stroking operation, then one can just pass user-space values to
Context.setLineWidth() and ignore this note.
As with the other stroke parameters, the current line width is
examined by Context.stroke(), Context.strokeExtents(), and
Context.strokeToPath(), but does not have any effect during path
construction.
The default line width value is 2.0.
#### Context.getLineWidth()This function returns the current line width value exactly as set by
Context.setLineWidth(). Note that the value is unchanged even if
the CTM has changed between the calls to Context.setLineWidth() and
Context.getLineWidth().
Return value: the current line width.
#### Context.setMiterLimit()Sets the current miter limit within the cairo context.
If the current line join style is set to "miter"
(see Context.setLineJoin()), the miter limit is used to determine
whether the lines should be joined with a bevel instead of a miter.
Cairo divides the length of the miter by the line width.
If the result is greater than the miter limit, the style is
converted to a bevel.
As with the other stroke parameters, the current line miter limit is
examined by Context.stroke(), Context.strokeExtents(), and
Context.strokeToPath(), but does not have any effect during path
construction.
The default miter limit value is 10.0, which will convert joins with interior angles less than 11 degrees to bevels instead of miters. For reference, a miter limit of 2.0 makes the miter cutoff at 60 degrees, and a miter limit of 1.414 makes the cutoff at 90 degrees.
A miter limit for a desired angle can be computed as: miter limit = 1/sin(angle/2)
#### Context.getMiterLimit()Gets the current miter limit, as set by Context.setMiterLimit().
Return value: the current miter limit.
#### Context.setOperator()Sets the compositing operator to be used for all drawing
operations. See Operator for details on the semantics of
each available compositing operator.
The default operator is "over".
Gets the current compositing operator for a cairo context.
Return value: the current compositing operator.
#### Context.setTolerance()Sets the tolerance used when converting paths into trapezoids.
Curved segments of the path will be subdivided until the maximum
deviation between the original path and the polygonal approximation
is less than tolerance. The default value is 0.1. A larger
value will give better performance, a smaller value, better
appearance. (Reducing the value from the default value of 0.1
is unlikely to improve appearance significantly.) The accuracy of paths
within Cairo is limited by the precision of its internal arithmetic, and
the prescribed tolerance is restricted to the smallest
representable internal value.
Gets the current tolerance value, as set by Context.setTolerance().
Return value: the current tolerance value.
#### Context.clip()Establishes a new clip region by intersecting the current clip
region with the current path as it would be filled by Context.fill()
and according to the current fill rule (see Context.setFillRule()).
After Context.clip(), the current path will be cleared from the cairo
context.
The current clip region affects all drawing operations by effectively masking out any changes to the surface that are outside the current clip region.
Calling Context.clip() can only make the clip region smaller, never
larger. But the current clip is part of the graphics state, so a
temporary restriction of the clip region can be achieved by
calling Context.clip() within a Context.save()/cairoRestore()
pair. The only other means of increasing the size of the clip
region is Context.resetClip().
Establishes a new clip region by intersecting the current clip
region with the current path as it would be filled by Context.fill()
and according to the current fill rule (see Context.setFillRule()).
Unlike Context.clip(), Context.clipPreserve() preserves the path within
the cairo context.
The current clip region affects all drawing operations by effectively masking out any changes to the surface that are outside the current clip region.
Calling Context.clipPreserve() can only make the clip region smaller, never
larger. But the current clip is part of the graphics state, so a
temporary restriction of the clip region can be achieved by
calling Context.clipPreserve() within a Context.save()/cairoRestore()
pair. The only other means of increasing the size of the clip
region is Context.resetClip().
Computes a bounding box in user coordinates covering the area inside the current clip.
#### Context.inClip()Tests whether the given point is inside the area that would be
visible through the current clip, i.e. the area that would be filled by
a Context.paint() operation.
See Context.clip(), and Context.clipPreserve().
Return value: A non-zero value if the point is inside, or zero if outside.
#### Context.resetClip()Reset the current clip region to its original, unrestricted state. That is, set the clip region to an infinitely large shape containing the target surface. Equivalently, if infinity is too hard to grasp, one can imagine the clip region being reset to the exact bounds of the target surface.
Note that code meant to be reusable should not call
Context.resetClip() as it will cause results unexpected by
higher-level code which calls Context.clip(). Consider using
Context.save() and Context.restore() around Context.clip() as a more
robust means of temporarily restricting the clip region.
Gets the current clip region as a list of rectangles in user coordinates.
Never returns nil.
The status in the list may be "clip-not-representable" to
indicate that the clip region cannot be represented as a list of
user-space rectangles. The status may have other values to indicate
other errors.
Returns: the current clip region as a list of rectangles in user coordinates,
which should be destroyed using Context.rectangleListDestroy().
A drawing operator that fills the current path according to the
current fill rule, (each sub-path is implicitly closed before being
filled). After Context.fill(), the current path will be cleared from
the cairo context. See Context.setFillRule() and
Context.fillPreserve().
A drawing operator that fills the current path according to the
current fill rule, (each sub-path is implicitly closed before being
filled). Unlike Context.fill(), Context.fillPreserve() preserves the
path within the cairo context.
See Context.setFillRule() and Context.fill().
Computes a bounding box in user coordinates covering the area that
would be affected, (the "inked" area), by a Context.fill() operation
given the current path and fill parameters. If the current path is
empty, returns an empty rectangle ((0,0), (0,0)). Surface
dimensions and clipping are not taken into account.
Contrast with Path.extents(), which is similar, but returns
non-zero extents for some paths with no inked area, (such as a
simple line segment).
Note that Context.fillExtents() must necessarily do more work to
compute the precise inked areas in light of the fill rule, so
Path.extents() may be more desirable for sake of performance
if the non-inked path extents are desired.
See Context.fill(), Context.setFillRule() and Context.fillPreserve().
Tests whether the given point is inside the area that would be
affected by a Context.fill() operation given the current path and
filling parameters. Surface dimensions and clipping are not taken
into account.
See Context.fill(), Context.setFillRule() and Context.fillPreserve().
Return value: A non-zero value if the point is inside, or zero if outside.
#### Context.mask()A drawing operator that paints the current source
using the alpha channel of pattern as a mask. (Opaque
areas of pattern are painted with the source, transparent
areas are not painted.)
A drawing operator that paints the current source
using the alpha channel of surface as a mask. (Opaque
areas of surface are painted with the source, transparent
areas are not painted.)
A drawing operator that paints the current source everywhere within the current clip region.
#### Context.paintWithAlpha()A drawing operator that paints the current source everywhere within
the current clip region using a mask of constant alpha value
alpha. The effect is similar to Context.paint(), but the drawing
is faded out using the alpha value.
A drawing operator that strokes the current path according to the
current line width, line join, line cap, and dash settings. After
Context.stroke(), the current path will be cleared from the cairo
context. See Context.setLineWidth(), Context.setLineJoin(),
Context.setLineCap(), Context.setDash(), and
Context.strokePreserve().
Note: Degenerate segments and sub-paths are treated specially and provide a useful result. These can result in two different situations:
-
Zero-length "on" segments set in
Context.setDash(). If the cap style is"round"or"square"then these segments will be drawn as circular dots or squares respectively. In the case of"square", the orientation of the squares is determined by the direction of the underlying path. -
A sub-path created by
Context.moveTo()followed by either aContext.closePath()or one or more calls toContext.lineTo()to the same coordinate as theContext.moveTo(). If the cap style is"round"then these sub-paths will be drawn as circular dots. Note that in the case of"square"a degenerate sub-path will not be drawn at all, (since the correct orientation is indeterminate).
In no case will a cap style of "butt" cause anything
to be drawn in the case of either degenerate segments or sub-paths.
A drawing operator that strokes the current path according to the
current line width, line join, line cap, and dash settings. Unlike
Context.stroke(), Context.strokePreserve() preserves the path within the
cairo context.
See Context.setLineWidth(), Context.setLineJoin(),
Context.setLineCap(), Context.setDash(), and
Context.strokePreserve().
Computes a bounding box in user coordinates covering the area that
would be affected, (the "inked" area), by a Context.stroke()
operation given the current path and stroke parameters.
If the current path is empty, returns an empty rectangle ((0,0), (0,0)).
Surface dimensions and clipping are not taken into account.
Note that if the line width is set to exactly zero, then
Context.strokeExtents() will return an empty rectangle. Contrast with
Path.extents() which can be used to compute the non-empty
bounds as the line width approaches zero.
Note that Context.strokeExtents() must necessarily do more work to
compute the precise inked areas in light of the stroke parameters,
so Path.extents() may be more desirable for sake of
performance if non-inked path extents are desired.
See Context.stroke(), Context.setLineWidth(), Context.setLineJoin(),
Context.setLineCap(), Context.setDash(), and
Context.strokePreserve().
Tests whether the given point is inside the area that would be
affected by a Context.stroke() operation given the current path and
stroking parameters. Surface dimensions and clipping are not taken
into account.
See Context.stroke(), Context.setLineWidth(), Context.setLineJoin(),
Context.setLineCap(), Context.setDash(), and
Context.strokePreserve().
Return value: A non-zero value if the point is inside, or zero if outside.
#### Context.copyPage()Emits the current page for backends that support multiple pages, but
doesn't clear it, so, the contents of the current page will be retained
for the next page too. Use Context.showPage() if you want to get an
empty page after the emission.
This is a convenience function that simply calls
Surface.copyPage() on cr's target.
Emits and clears the current page for backends that support multiple
pages. Use Context.copyPage() if you don't want to clear the page.
This is a convenience function that simply calls
Surface.showPage() on cr's target.
Paths
#### Context.copyPath()Creates a copy of the current path and returns it to the user as a
Path. See cairo_path_data_t for hints on how to iterate
over the returned data structure.
This function will always return a valid pointer, but the result
will have no data (data==nil`` and
num_data==0), if either of the following
conditions hold:
Return value: the copy of the current path. The caller owns the
returned object and should call Path.destroy() when finished
with it.
Gets a flattened copy of the current path and returns it to the
user as a Path. See cairo_path_data_t for hints on
how to iterate over the returned data structure.
This function is like Context.copyPath() 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 "path-curve-to" which will instead be replaced by a
series of "path-line-to" elements.
This function will always return a valid pointer, but the result
will have no data (data==nil`` and
num_data==0), if either of the following
conditions hold:
Return value: the copy of the current path. The caller owns the
returned object and should call Path.destroy() when finished
with it.
Append the path onto the current path. The path may be either the
return value from one of Context.copyPath() or
Context.copyPathFlat() or it may be constructed manually. See
Path for details on how the path data structure should be
initialized, and note that path->status must be
initialized to "success".
Returns whether a current point is defined on the current path.
See Context.getCurrentPoint() for details on the current point.
Return value: whether a current point is defined.
#### Context.getCurrentPoint()Gets 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. If there is no defined current point or if cr is in an
error status, x and y will both be set to 0.0. It is possible to
check this in advance with Context.hasCurrentPoint().
Most path construction functions alter the current point. See the
following for details on how they affect the current point:
Context.newPath(), Context.newSubPath(),
Context.appendPath(), Context.closePath(),
Context.moveTo(), Context.lineTo(), Context.curveTo(),
Context.relMoveTo(), Context.relLineTo(), Context.relCurveTo(),
Context.arc(), Context.arcNegative(), Context.rectangle(),
Context.textPath(), Context.glyphPath(), Context.strokeToPath().
Some functions use and alter the current point but do not
otherwise change current path:
Context.showText().
Some functions unset the current path and as a result, current point:
Context.fill(), Context.stroke().
Clears the current path. After this call there will be no path and no current point.
#### Context.newSubPath()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 Context.moveTo().
A call to Context.newSubPath() is particularly useful when
beginning a new sub-path with one of the Context.arc() calls. This
makes things easier as it is no longer necessary to manually
compute the arc's initial coordinates for a call to
Context.moveTo().
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
Context.moveTo()), and closes this sub-path. After this call the
current point will be at the joined endpoint of the sub-path.
The behavior of Context.closePath() is distinct from simply calling
Context.lineTo() 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 Context.closePath(),
this function will have no effect.
Note: As of cairo version 1.2.4 any call to Context.closePath() will
place an explicit MOVE_TO element into the path immediately after
the CLOSE_PATH element, (which can be seen in Context.copyPath() 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 a circular arc of the given radius to the current path. The
arc is centered at (xc, yc), begins at angle1 and proceeds in
the direction of increasing angles to end at angle2. If angle2 is
less than angle1 it will be progressively increased by
2*M_PI until it is greater than angle1.
If there is a current point, an initial line segment will be added
to the path to connect the current point to the beginning of the
arc. If this initial line is undesired, it can be avoided by
calling Context.newSubPath() before calling Context.arc().
Angles are measured in radians. An angle of 0.0 is in the direction
of the positive X axis (in user space). An angle of
M_PI/2.0 radians (90 degrees) is in the
direction of the positive Y axis (in user space). Angles increase
in the direction from the positive X axis toward the positive Y
axis. So with the default transformation matrix, angles increase in
a clockwise direction.
(To convert from degrees to radians, use degrees * (M_PI / 180.).)
This function gives the arc in the direction of increasing angles;
see Context.arcNegative() to get the arc in the direction of
decreasing angles.
The arc is circular in user space. To achieve an elliptical arc,
you can scale the current transformation matrix by different
amounts in the X and Y directions. For example, to draw an ellipse
in the box given by x, y, width, height:
cairo_save (cr);
cairo_translate (cr, x + width / 2., y + height / 2.);
cairo_scale (cr, width / 2., height / 2.);
cairo_arc (cr, 0., 0., 1., 0., 2 * M_PI);
cairo_restore (cr);Adds a circular arc of the given radius to the current path. The
arc is centered at (xc, yc), begins at angle1 and proceeds in
the direction of decreasing angles to end at angle2. If angle2 is
greater than angle1 it will be progressively decreased by
2*M_PI until it is less than angle1.
See Context.arc() for more details. This function differs only in the
direction of the arc between the two angles.
Adds a cubic Bézier spline to the path from the current point to
position (x3, y3) in user-space coordinates, using (x1, y1) and
(x2, y2) as the control points. After this call the current point
will be (x3, y3).
If there is no current point before the call to Context.curveTo()
this function will behave as if preceded by a call to
cairo_move_to(cr, x1, y1).
Adds a line to the path from the current point to position (x, y)
in user-space coordinates. After this call the current point
will be (x, y).
If there is no current point before the call to Context.lineTo()
this function will behave as cairo_move_to(cr, x, y).
Begin a new sub-path. After this call the current point will be (x,
y).
Adds a closed sub-path rectangle of the given size to the current
path at position (x, y) in user-space coordinates.
This function is logically equivalent to:
cairo_move_to (cr, x, y);
cairo_rel_line_to (cr, width, 0);
cairo_rel_line_to (cr, 0, height);
cairo_rel_line_to (cr, -width, 0);
cairo_close_path (cr);Adds closed paths for the glyphs to the current path. The generated
path if filled, achieves an effect similar to that of
Context.showGlyphs().
Adds closed paths for text to the current path. The generated
path if filled, achieves an effect similar to that of
Context.showText().
Text conversion and positioning is done similar to Context.showText().
Like Context.showText(), 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 Context.textPath()
without having to set current point in between.
Note: The Context.textPath() 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 Context.glyphPath() for the
"real" text path API in cairo.
Relative-coordinate version of Context.curveTo(). All offsets are
relative to the current point. Adds a cubic Bézier spline to the
path from the current point to a point offset from the current
point by (dx3, dy3), using points offset by (dx1, dy1) and
(dx2, dy2) as the control points. After this call the current
point will be offset by (dx3, dy3).
Given a current point of (x, y), cairo_rel_curve_to(cr, dx1,
dy1, dx2, dy2, dx3, dy3) is logically equivalent to
cairo_curve_to(cr, x+dx1, y+dy1, x+dx2, y+dy2, x+dx3, y+dy3).
It is an error to call this function with no current point. Doing
so will cause cr to shutdown with a status of
"no-current-point".
Relative-coordinate version of Context.lineTo(). Adds a line to the
path from the current point to a point that is offset from the
current point by (dx, dy) in user space. After this call the
current point will be offset by (dx, dy).
Given a current point of (x, y), cairo_rel_line_to(cr, dx, dy)
is logically equivalent to cairo_line_to(cr, x + dx, y + dy).
It is an error to call this function with no current point. Doing
so will cause cr to shutdown with a status of
"no-current-point".
Begin a new sub-path. After this call the current point will offset
by (x, y).
Given a current point of (x, y), cairo_rel_move_to(cr, dx, dy)
is logically equivalent to cairo_move_to(cr, x + dx, y + dy).
It is an error to call this function with no current point. Doing
so will cause cr to shutdown with a status of
"no-current-point".
Transformations
#### Context.translate()Modifies the current transformation matrix (CTM) by translating the
user-space origin by (tx, ty). This offset is interpreted as a
user-space coordinate according to the CTM in place before the new
call to Context.translate(). In other words, the translation of the
user-space origin takes place after any existing transformation.
Modifies the current transformation matrix (CTM) by scaling the X
and Y user-space axes by sx and sy respectively. The scaling of
the axes takes place after any existing transformation of user
space.
Modifies the current transformation matrix (CTM) by rotating the
user-space axes by angle radians. The rotation of the axes takes
places after any existing transformation of user space. The
rotation direction for positive angles is from the positive X axis
toward the positive Y axis.
Modifies the current transformation matrix (CTM) by applying
matrix as an additional transformation. The new transformation of
user space takes place after any existing transformation.
Modifies the current transformation matrix (CTM) by setting it
equal to matrix.
Stores the current transformation matrix (CTM) into matrix.
Resets the current transformation matrix (CTM) by setting it equal to the identity matrix. That is, the user-space and device-space axes will be aligned and one user-space unit will transform to one device-space unit.
#### Context.userToDevice()Transform a coordinate from user space to device space by multiplying the given point by the current transformation matrix (CTM).
#### Context.userToDeviceDistance()Transform a distance vector from user space to device space. This
function is similar to Context.userToDevice() except that the
translation components of the CTM will be ignored when transforming
(dx,dy).
Transform a coordinate from device space to user space by multiplying the given point by the inverse of the current transformation matrix (CTM).
#### Context.deviceToUserDistance()Transform a distance vector from device space to user space. This
function is similar to Context.deviceToUser() except that the
translation components of the inverse CTM will be ignored when
transforming (dx,dy).
Rendering text and glyphs
#### Context.selectFontFace()Note: The Context.selectFontFace() 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.
Selects a family and style of font from a simplified description as a family name, slant and weight. Cairo provides no operation to list available family names on the system (this is a "toy", remember), but the standard CSS2 generic family names, ("serif", "sans-serif", "cursive", "fantasy", "monospace"), are likely to work as expected.
If family starts with the string "cairo:", or if no native font
backends are compiled in, cairo will use an internal font family.
The internal font family recognizes many modifiers in the family
string, most notably, it recognizes the string "monospace". That is,
the family name "cairo:monospace" will use the monospace version of
the internal font family.
For "real" font selection, see the font-backend-specific
font_face_create functions for the font backend you are using. (For
example, if you are using the freetype-based cairo-ft font backend,
see Context.ftFontFaceCreateForFtFace() or
Context.ftFontFaceCreateForPattern().) The resulting font face
could then be used with ScaledFontFace.new() and
Context.setScaledFont().
Similarly, when using the "real" font support, you can call directly into the underlying font system, (such as fontconfig or freetype), for operations such as listing available fonts, etc.
It is expected that most applications will need to use a more comprehensive font handling and text layout library, (for example, pango), in conjunction with cairo.
If text is drawn without a call to Context.selectFontFace(), (nor
Context.setFontFace() nor Context.setScaledFont()), the default
family is platform-specific, but is essentially "sans-serif".
Default slant is "normal", and default weight is
"normal".
This function is equivalent to a call to Context.toyFontFaceCreate()
followed by Context.setFontFace().
Sets the current font matrix to a scale by a factor of size, replacing
any font matrix previously set with Context.setFontSize() or
Context.setFontMatrix(). This results in a font size of size user space
units. (More precisely, this matrix will result in the font's
em-square being a size by size square in user space.)
If text is drawn without a call to Context.setFontSize(), (nor
Context.setFontMatrix() nor Context.setScaledFont()), the default
font size is 10.0.
Sets the current font matrix to matrix. The font matrix gives a
transformation from the design space of the font (in this space,
the em-square is 1 unit by 1 unit) to user space. Normally, a
simple scale is used (see Context.setFontSize()), but a more
complex font matrix can be used to shear the font
or stretch it unequally along the two axes
Stores the current font matrix into matrix. See
Context.setFontMatrix().
Sets a set of custom font rendering options for the Context.
Rendering options are derived by merging these options with the
options derived from underlying surface; if the value in options
has a default value (like "default"), then the value
from the surface is used.
Retrieves font rendering options set via cairo_set_font_options.
Note that the returned options do not include any options derived
from the underlying surface; they are literally the options
passed to Context.setFontOptions().
Replaces the current FontFace object in the Context with
font_face. The replaced font face in the Context will be
destroyed if there are no other references to it.
Gets the current font face for a Context.
Return value: the current font face. This object is owned by
cairo. To keep a reference to it, you must call
FontFace.reference().
This function never returns nil. If memory cannot be allocated, a
special "nil" FontFace object will be returned on which
FontFace.status() returns "no-memory". Using
this nil object will cause its error state to propagate to other
objects it is passed to, (for example, calling
Context.setFontFace() with a nil font will trigger an error that
will shutdown the Context object).
Replaces the current font face, font matrix, and font options in
the Context with those of the ScaledFontFace. Except for
some translation, the current CTM of the Context should be the
same as that of the ScaledFontFace, which can be accessed
using ScaledFontFace.getCtm().
Gets the current scaled font for a Context.
Return value: the current scaled font. This object is owned by
cairo. To keep a reference to it, you must call
ScaledFontFace.reference().
This function never returns nil. If memory cannot be allocated, a
special "nil" ScaledFontFace object will be returned on which
ScaledFontFace.status() returns "no-memory". Using
this nil object will cause its error state to propagate to other
objects it is passed to, (for example, calling
Context.setScaledFont() with a nil font will trigger an error that
will shutdown the Context object).
A drawing operator that generates the shape from a string of UTF-8 characters, rendered according to the current font_face, font_size (font_matrix), and font_options.
This function first computes a set of glyphs for the string of text. The first glyph is placed so that its origin is at the current point. The origin of each subsequent glyph is offset from that of the previous glyph by the advance values of the previous glyph.
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 easy display of a single
logical string with multiple calls to Context.showText().
Note: The Context.showText() 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 Context.showGlyphs() for the
"real" text display API in cairo.
A drawing operator that generates the shape from an array of glyphs, rendered according to the current font face, font size (font matrix), and font options.
#### Context.showTextGlyphs()This operation has rendering effects similar to Context.showGlyphs()
but, if the target surface supports it, uses the provided text and
cluster mapping to embed the text for the glyphs shown in the output.
If the target does not support the extended attributes, this function
acts like the basic Context.showGlyphs() as if it had been passed
glyphs and num_glyphs.
The mapping between utf8 and glyphs is provided by an array of
clusters. Each cluster covers a number of
text bytes and glyphs, and neighboring clusters cover neighboring
areas of utf8 and glyphs. The clusters should collectively cover utf8
and glyphs in entirety.
The first cluster always covers bytes from the beginning of utf8.
If cluster_flags do not have the "backward"
set, the first cluster also covers the beginning
of glyphs, otherwise it covers the end of the glyphs array and
following clusters move backward.
See cairo_text_cluster_t for constraints on valid clusters.
Gets the font extents for the currently selected font.
#### Context.textExtents()Gets the extents for a string of text. The extents describe a
user-space rectangle that encloses the "inked" portion of the text,
(as it would be drawn by Context.showText()). Additionally, the
x_advance and y_advance values indicate the amount by which the
current point would be advanced by Context.showText().
Note that whitespace characters do not directly contribute to the size of the rectangle (extents.width and extents.height). They do contribute indirectly by changing the position of non-whitespace characters. In particular, trailing whitespace characters are likely to not affect the size of the rectangle, though they will affect the x_advance and y_advance values.
#### Context.glyphExtents()Gets the extents for an array of glyphs. The extents describe a
user-space rectangle that encloses the "inked" portion of the
glyphs, (as they would be drawn by Context.showGlyphs()).
Additionally, the x_advance and y_advance values indicate the
amount by which the current point would be advanced by
Context.showGlyphs().
Note that whitespace glyphs do not contribute to the size of the rectangle (extents.width and extents.height).