org.freedesktop.cairo

Class Context

public class Context extends CairoObject

Constructor Summary
Context(Surface target)
Creates a new Context with all graphics state parameters set to default values and with target as a target surface.
protected Context(Handle hndl)
Method Summary
voidarc(Point point, double radius, double angle1, double angle2)
Adds an arc from angle1 to angle2 to the current path.
voidarc(double x, double y, double radius, double angle1, double angle2)
voidarcNegative(Point point, double radius, double angle1, double angle2)
Adds an arc from angle1 to angle2 to the current path.
voidarcNegative(double x, double y, double radius, double angle1, double angle2)
voidclip()
Establishes a new clip region by intersecting the current clip region with the current path as it would be filled by fill() and according to the current fill rule (see setFillRule()).
voidclipPreserve()
Establishes a new clip region by intersecting the current clip region with the current path as it would be filled by fill() and according to the current fill rule (see setFillRule()).
voidclosePath()
Closes the current path by connecting current point to the starting point with a line segment.
voidcopyPage()
voidcurveTo(Point p1, Point p2, Point p3)
Draws a cubic bezier curve from the current point to (x3, y3) using 2 control points (x1, y1) and (x2, y2).
voidcurveTo(double x1, double y1, double x2, double y2, double x3, double y3)
PointdeviceToUser(Point point)
Transform a coordinate from device space to user space by multiplying the given point by the inverse of the current transformation matrix (CTM).
PointdeviceToUserDistance(Point distance)
Transform a distance vector from device space to user space.
voidellipse(double cx, double cy, double rx, double ry)
Creates an ellipse path.
voidfill()
A drawing operator that fills the current path according to the current fill rule.
RectanglefillExtents()
voidfillPreserve()
A drawing operator that fills the current path according to the current fill rule.
protected voidfinalize()
Disposes all the native resources used by the object.
FontExtentsfontExtents()
Gets the font extents for the currently selected font.
AntialiasgetAntialias()
PointgetCurrentPoint()
Returns the current point of the surface.
FillRulegetFillRule()
Gets the current fill rule, as set by setFillRule().
FontFacegetFontFace()
Gets the current font face.
MatrixgetFontMatrix()
Gets the current font matrix.
FontOptionsgetFontOptions()
LineCapgetLineCap()
Returns current linecap style.
LineJoingetLineJoin()
Return current line join style.
doublegetLineWidth()
Returns the stroke line width.
MatrixgetMatrix()
Returns the current transformation matrix
doublegetMiterLimit()
Returns the miter limit for miter style line joins
OperatorgetOperator()
Returns the current surface operator
PatterngetSource()
Gets the current source pattern for this object.
SurfacegetTarget()
Gets the target surface for the cairo context as passed to the constructor.
doublegetTolerance()
Returns the tesselation tolerance of the current state.
TextExtentsglyphExtents(Glyph[] glyphs)
Gets the extents for an array of glyphs.
voidglyphPath(Glyph[] glyphs)
voididentityMatrix()
Resets the current transformation matrix (CTM) by setting it equal to the identity matrix.
booleaninFill(double x, double y)
Determines whether the point specified by (x, y) lies inside the area bounded by the current path, excluding the path's stroke area.
booleaninFill(Point p)
booleaninStroke(double x, double y)
Determines whether the point specified by (x, y) lies inside the area bounded by the current path, including the path's stroke area.
booleaninStroke(Point p)
voidlineTo(Point p)
Draws a line segment as part of the current path.
voidlineTo(double x, double y)
voidmask(Pattern pattern)
A drawing operator that paints the current source using the alpha channel of pattern as a mask.
voidmask(Surface surface, double sx, double sy)
A drawing operator that paints the current source using the alpha channel of surface as a mask.
voidmoveTo(Point p)
Moves the current point in the path to the given co-ordinates.
voidmoveTo(double x, double y)
voidnewPath()
Starts a new path.
voidpaint()
A drawing operator that paints the current source everywhere within the current clip region.
voidpaintWithAlpha(double alpha)
A drawing operator that paints the current source everywhere within the current clip region using a mask of constant alpha value alpha.
voidrectangle(Point upperLeft, Point lowerRight)
Draws a rectangle defined by the upper-left point p1 and the lower-right point p2.
voidrectangle(Rectangle rect)
Draws a rectangle defined by the Rectangle object rect.
voidrelCurveTo(Point p1, Point p2, Point p3)
Draws a cubic bezier curve from the current point to p3 using 2 control points p1 and p2.
voidrelCurveTo(double x1, double y1, double x2, double y2, double x3, double y3)
voidrelLineTo(Point p)
Draws a line segment as part of the current path.
voidrelLineTo(double x, double y)
voidrelMoveTo(Point p)
Moves to the current path to a new point.
voidrelMoveTo(double x, double y)
voidresetClip()
Reset the current clip region to its original, unrestricted state.
voidrestore()
Restores the state saved by a preceding call to {@link #save()} and removes that state from the stack of saved states.
voidrotate(double angle)
Modifies the current transformation matrix (CTM) by rotating the user-space axes by angle radians.
voidsave()
Makes a copy of the current state and saves it on an internal stack of saved states.
voidscale(double sx, double sy)
Modifies the current transformation matrix (CTM) by scaling the X and Y user-space axes by sx and sy respectively.
voidselectFontFace(String family, FontSlant slant, FontWeight weight)
Selects a family and style of font from a simplified description as a family name, slant and weight.
voidsetAntialias(Antialias antialias)
voidsetDash(double[] dashes, double offset)
Sets the line dash.
voidsetFillRule(FillRule fillrule)
Set the current fill rule within the Context.
voidsetFontFace(FontFace fontFace)
Replaces the current FontFace object in the context with fontFace.
voidsetFontMatrix(Matrix matrix)
Sets the current font matrix to matrix.
voidsetFontOptions(FontOptions fontOptions)
voidsetFontSize(double scale)
Sets the current font matrix to a scale by a factor of size, replacing any font matrix previously set with cairo_setFontSize() or setFontMatrix().
voidsetLineCap(LineCap linecap)
Sets the current line cap style within the cairo context.
voidsetLineJoin(LineJoin linejoin)
Sets the current line join style within the cairo context.
voidsetLineWidth(double width)
Sets the current line width within the cairo context.
voidsetMatrix(Matrix matrix)
Modifies the current transformation matrix (CTM) by setting it equal to matrix.
voidsetMiterLimit(double limit)
Sets the miter limit.
voidsetOperator(Operator op)
Sets the compositing operator to be used for all drawing operations.
voidsetSource(Pattern pattern)
Sets the source pattern within the Cairo object.
voidsetSource(Surface surface, double x, double y)
voidsetSourceRGB(double red, double green, double blue)
Sets a constant color for filling and stroking.
voidsetSourceRGBA(double red, double green, double blue, double alpha)
Sets the source pattern within this Cairo object to a translucent color.
voidsetTolerance(double tolerance)
Sets the tolerance used when converting paths into trapezoids.
voidshowGlyphs(Glyph[] glyphs)
voidshowPage()
voidshowText(String text)
Draws the given text on the screen.
Statusstatus()
voidstroke()
A drawing operator that strokes the current path according to the current line width, line join, line cap, and dash settings.
RectanglestrokeExtents()
voidstrokePreserve()
A drawing operator that strokes the current path according to the current line width, line join, line cap, and dash settings.
TextExtentstextExtents(String text)
Gets the extents for a string of text.
voidtextPath(String text)
voidtransform(Matrix matrix)
Modifies the current transformation matrix (CTM) by applying matrix as an additional transformation.
voidtranslate(double tx, double ty)
Modifies the current transformation matrix (CTM) by tanslating the user-space origin by (tx, ty).
PointuserToDevice(Point point)
Transform a coordinate from user space to device space by multiplying the given point by the current transformation matrix (CTM).
PointuserToDeviceDistance(Point distance)
Transform a distance vector from user space to device space.

Constructor Detail

Context

public Context(Surface target)
Creates a new Context with all graphics state parameters set to default values and with target as a target surface. The target surface should be constructed with a backend-specific function such as ImageSurface.create.

Parameters: target target surface for the context.

Context

protected Context(Handle hndl)

Method Detail

arc

public void arc(Point point, double radius, double angle1, double angle2)
Adds an arc from angle1 to angle2 to the current path. If there is a current point, that point is connected to the start of the arc by a straight line segment. Angles are measured in radians with an angle of 0 along the X axis and an angle of %M_PI radians (90 degrees) along the Y axis, so with the default transformation matrix, positive angles are clockwise. (To convert from degrees to radians, use degrees * (M_PI / 180.).) This function gives the arc in the direction of increasing angle; see arcNegative() to get the arc in the direction of decreasing angle. A full arc is drawn as a circle. To make an oval arc, you can scale the current transformation matrix by different amounts in the X and Y directions.

Parameters: point radius angle1 angle2

arc

public void arc(double x, double y, double radius, double angle1, double angle2)

arcNegative

public void arcNegative(Point point, double radius, double angle1, double angle2)
Adds an arc from angle1 to angle2 to the current path. The function behaves identically to arc() except that instead of giving the arc in the direction of increasing angle, it gives the arc in the direction of decreasing angle.

Parameters: point radius angle1 angle2

arcNegative

public void arcNegative(double x, double y, double radius, double angle1, double angle2)

clip

public void clip()
Establishes a new clip region by intersecting the current clip region with the current path as it would be filled by fill() and according to the current fill rule (see setFillRule()). After 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 clip() can only make the clip region smaller, never larger. But the current clip is part of the graphics state, so a tempoarary restriction of the clip region can be achieved by calling clip() within a save()/restore() pair. The only other means of increasing the size of the clip region is resetClip().

clipPreserve

public void clipPreserve()
Establishes a new clip region by intersecting the current clip region with the current path as it would be filled by fill() and according to the current fill rule (see setFillRule()). Unlike clip(), 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 clip() can only make the clip region smaller, never larger. But the current clip is part of the graphics state, so a tempoarary restriction of the clip region can be achieved by calling clip() within a save()/restore() pair. The only other means of increasing the size of the clip region is resetClip().

closePath

public void closePath()
Closes the current path by connecting current point to the starting point with a line segment.

copyPage

public void copyPage()

curveTo

public void curveTo(Point p1, Point p2, Point p3)
Draws a cubic bezier curve from the current point to (x3, y3) using 2 control points (x1, y1) and (x2, y2).

Parameters: p1 x co-ordinate of the first control point p2 x co-ordinate of the second control point p3 x co-ordinate of the end point

curveTo

public void curveTo(double x1, double y1, double x2, double y2, double x3, double y3)

deviceToUser

public Point deviceToUser(Point point)
Transform a coordinate from device space to user space by multiplying the given point by the inverse of the current transformation matrix (CTM).

deviceToUserDistance

public Point deviceToUserDistance(Point distance)
Transform a distance vector from device space to user space. This function is similar to deviceToUser() except that the translation components of the inverse CTM will be ignored when transforming the Point.

ellipse

public void ellipse(double cx, double cy, double rx, double ry)
Creates an ellipse path.

Parameters: cx X co-ordinate of the center of ellipse cy Y co-ordinate of the center of ellipse rx X radius of the ellipse ry Y radius of the ellipse

fill

public void fill()
A drawing operator that fills the current path according to the current fill rule. After fill, the current path will be cleared from the cairo context.

fillExtents

public Rectangle fillExtents()

fillPreserve

public void fillPreserve()
A drawing operator that fills the current path according to the current fill rule. Unlike fill(), fillPreserve preserves the path within the cairo context.

finalize

protected void finalize()
Disposes all the native resources used by the object.

fontExtents

public FontExtents fontExtents()
Gets the font extents for the currently selected font.

getAntialias

public Antialias getAntialias()

getCurrentPoint

public Point getCurrentPoint()
Returns the current point of the surface. The current point is returned in the user-space coordinate system. If there is no defined current point then Point will be set to (0,0)

Returns: Current point for drawing

getFillRule

public FillRule getFillRule()
Gets the current fill rule, as set by setFillRule().

getFontFace

public FontFace getFontFace()
Gets the current font face.

getFontMatrix

public Matrix getFontMatrix()
Gets the current font matrix. See setFontMatrix()

Returns: the current font matrix

getFontOptions

public FontOptions getFontOptions()

getLineCap

public LineCap getLineCap()
Returns current linecap style.

Returns: The line cap style

getLineJoin

public LineJoin getLineJoin()
Return current line join style.

Returns: Line join style

getLineWidth

public double getLineWidth()
Returns the stroke line width.

Returns: The stroke line width

getMatrix

public Matrix getMatrix()
Returns the current transformation matrix

Returns: the current transformation matrix

getMiterLimit

public double getMiterLimit()
Returns the miter limit for miter style line joins

Returns: The miter limit

getOperator

public Operator getOperator()
Returns the current surface operator

Returns: The surface operator.

getSource

public Pattern getSource()
Gets the current source pattern for this object.

getTarget

public Surface getTarget()
Gets the target surface for the cairo context as passed to the constructor.

Returns: the target surface

getTolerance

public double getTolerance()
Returns the tesselation tolerance of the current state.

Returns: tesselation tolerance

glyphExtents

public TextExtents glyphExtents(Glyph[] glyphs)
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 showGlyphs). Additionally, the xAdvance and yAdvance values indicate the amount by which the current point would be advanced by cairo_show_glyphs. Note that whitespace glyphs do not contribute to the size of the rectangle (extents.width and extents.height).

glyphPath

public void glyphPath(Glyph[] glyphs)

identityMatrix

public void identityMatrix()
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.

inFill

public boolean inFill(double x, double y)
Determines whether the point specified by (x, y) lies inside the area bounded by the current path, excluding the path's stroke area.

Parameters: x x coordinate of the point to test y y coordinate of the point to test

inFill

public boolean inFill(Point p)

inStroke

public boolean inStroke(double x, double y)
Determines whether the point specified by (x, y) lies inside the area bounded by the current path, including the path's stroke area.

Parameters: x x coordinate of the point to test y y coordinate of the point to test

inStroke

public boolean inStroke(Point p)

lineTo

public void lineTo(Point p)
Draws a line segment as part of the current path. The line is drawn from the current point of the path to the new co-ordinates.

Parameters: p the point coordinate for the end point for the line segment

lineTo

public void lineTo(double x, double y)

mask

public void mask(Pattern pattern)
A drawing operator that paints the current source using the alpha channel of pattern as a mask. (Opaque areas of mask are painted with the source, transparent areas are not painted.)

Parameters: pattern

mask

public void mask(Surface surface, double sx, double sy)
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.)

Parameters: surface sx sy

moveTo

public void moveTo(Point p)
Moves the current point in the path to the given co-ordinates.

Parameters: p the point co-ordinate of the point to move to

moveTo

public void moveTo(double x, double y)

newPath

public void newPath()
Starts a new path. You can add path segments to this path using the path extension methods (xxxxTo()).

paint

public void paint()
A drawing operator that paints the current source everywhere within the current clip region.

paintWithAlpha

public void paintWithAlpha(double alpha)
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 paint(), but the drawing is faded out using the alpha value.

Parameters: alpha

rectangle

public void rectangle(Point upperLeft, Point lowerRight)
Draws a rectangle defined by the upper-left point p1 and the lower-right point p2.

Parameters: upperLeft x and y coordinates of the upper-left point lowerRight x and y coordinates of the lower-right point

rectangle

public void rectangle(Rectangle rect)
Draws a rectangle defined by the Rectangle object rect.

Parameters: rect Rectangle defining the coordinate of the shape to draw

relCurveTo

public void relCurveTo(Point p1, Point p2, Point p3)
Draws a cubic bezier curve from the current point to p3 using 2 control points p1 and p2. The co-ordinates are specified relative to current point in the path.

Parameters: p1 relative co-ordinate of the first control point p2 relative co-ordinate of the second control point p3 relative co-ordinate of the end point

relCurveTo

public void relCurveTo(double x1, double y1, double x2, double y2, double x3, double y3)

relLineTo

public void relLineTo(Point p)
Draws a line segment as part of the current path. The line is drawn from the current point of the path to the new co-ordinates. The new co-ordinates are given relative to the current point.

Parameters: p The relative coordinate for the end point for the line segment

relLineTo

public void relLineTo(double x, double y)

relMoveTo

public void relMoveTo(Point p)
Moves to the current path to a new point. The co-ordinates of the new point are given in relation to the current point of the state.

Parameters: p relative distance between current point and the new point

relMoveTo

public void relMoveTo(double x, double y)

resetClip

public void 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 resetClip() as it will cause results unexpected by higher-level code which calls clip(). Consider using save() and restore() around clip() as a more robust means of temporarily restricting the clip region.

restore

public void restore()
Restores the state saved by a preceding call to {@link #save()} and removes that state from the stack of saved states.

rotate

public void rotate(double angle)
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.

Parameters: angle

save

public void save()
Makes a copy of the current state and saves it on an internal stack of saved states. When {@link #restore()} is called, the saved state will be restored. Multiple calls save() and restore() can be nested; each call to restore() restores the state from the matching paired save().

scale

public void scale(double sx, double sy)
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.

Parameters: sx sy

selectFontFace

public void selectFontFace(String family, FontSlant slant, FontWeight weight)
Selects a family and style of font from a simplified description as a family name, slant and weight. This method is meant to be used only for applications with simple font needs: Cairo doesn't provide for operations such as listing all available fonts on the system, and it is expected that most applications will need to use a more comprehensive font handling and text layout library in addition to Cairo.

Parameters: family font family name slant font slant weight font weight

setAntialias

public void setAntialias(Antialias antialias)

setDash

public void setDash(double[] dashes, double offset)
Sets the line dash.

Parameters: dashes offset

setFillRule

public void setFillRule(FillRule fillrule)
Set the current fill rule within the 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 fill and clip.

Parameters: fillrule

setFontFace

public void setFontFace(FontFace fontFace)
Replaces the current FontFace object in the context with fontFace. The replaced font face in the context will be destroyed if there are no other references to it.

Parameters: fontFace

setFontMatrix

public void setFontMatrix(Matrix matrix)
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 setFontSize()), but a more complex font matrix can be used to shear the font or stretch it unequally along the two axes

Parameters: matrix transformation matrix.

setFontOptions

public void setFontOptions(FontOptions fontOptions)

setFontSize

public void setFontSize(double scale)
Sets the current font matrix to a scale by a factor of size, replacing any font matrix previously set with cairo_setFontSize() or 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.)

Parameters: scale the scaling factor.

setLineCap

public void setLineCap(LineCap linecap)
Sets the current line cap style within the cairo context. See LineCap for details about how the available line cap styles are drawn.

Parameters: linecap

setLineJoin

public void setLineJoin(LineJoin linejoin)
Sets the current line join style within the cairo context. See LineJoin for details about how the available line join styles are drawn.

Parameters: linejoin

setLineWidth

public void setLineWidth(double width)
Sets the current line width within the cairo context. The line width specifies the diameter of a pen that is circular in user-space. As with the other stroke parameters, the current line cap style is examined by stroke(), strokeExtents(), and strokeToPath(), but does not have any effect during path construction.

Parameters: width

setMatrix

public void setMatrix(Matrix matrix)
Modifies the current transformation matrix (CTM) by setting it equal to matrix.

Parameters: matrix the transformation matrix

setMiterLimit

public void setMiterLimit(double limit)
Sets the miter limit.

Parameters: limit

setOperator

public void setOperator(Operator op)
Sets the compositing operator to be used for all drawing operations.

Parameters: op

setSource

public void setSource(Pattern pattern)
Sets the source pattern within the Cairo object. This pattern will then be used for any subsequent drawing operation until a new source pattern is set.

Parameters: pattern

setSource

public void setSource(Surface surface, double x, double y)

Parameters: surface x y

setSourceRGB

public void setSourceRGB(double red, double green, double blue)
Sets a constant color for filling and stroking. The color components are floating point numbers in the range 0 to 1. If the values passed in are outside that range, they will be clamped.

Parameters: red green blue

setSourceRGBA

public void setSourceRGBA(double red, double green, double blue, double alpha)
Sets the source pattern within this Cairo object to a translucent color. This color will then be used for any subsequent drawing operation until a new source pattern is set. The color and alpha components are floating point numbers in the range 0 to 1. If the values passed in are outside that range, they will be clamped.

Parameters: red green blue alpha

setTolerance

public void setTolerance(double tolerance)
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).

Parameters: tolerance

showGlyphs

public void showGlyphs(Glyph[] glyphs)

showPage

public void showPage()

showText

public void showText(String text)
Draws the given text on the screen.

Parameters: text String to draw on the screen.

status

public Status status()

stroke

public void stroke()
A drawing operator that strokes the current path according to the current line width, line join, line cap, and dash settings. After stroke, the current path will be cleared from the cairo context.

strokeExtents

public Rectangle strokeExtents()

strokePreserve

public void strokePreserve()
A drawing operator that strokes the current path according to the current line width, line join, line cap, and dash settings. Unlike stroke(), strokePreserve preserves the path within the cairo context.

textExtents

public TextExtents textExtents(String text)
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 showText). Additionally, the xAdvance and yAdvance values indicate the amount by which the current point would be advanced by 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 xAdvance and yAdvance values.

textPath

public void textPath(String text)

transform

public void transform(Matrix matrix)
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.

Parameters: matrix the transformation matrix to append

translate

public void translate(double tx, double ty)
Modifies the current transformation matrix (CTM) by tanslating 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 translate. In other words, the translation of the user-space origin takes place after any existing transformation.

Parameters: tx ty

userToDevice

public Point userToDevice(Point point)
Transform a coordinate from user space to device space by multiplying the given point by the current transformation matrix (CTM).

userToDeviceDistance

public Point userToDeviceDistance(Point distance)
Transform a distance vector from user space to device space. This function is similar to userToDevice() except that the translation components of the CTM will be ignored when transforming the Point.