org.freedesktop.cairo
Class Context

java.lang.Object
  extended byorg.gnu.glib.Struct
      extended byorg.freedesktop.cairo.CairoObject
          extended byorg.freedesktop.cairo.Context

public class Context
extends org.freedesktop.cairo.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.
 
Method Summary
 void arc(double x, double y, double radius, double angle1, double angle2)
           
 void arc(Point point, double radius, double angle1, double angle2)
          Adds an arc from angle1 to angle2 to the current path.
 void arcNegative(double x, double y, double radius, double angle1, double angle2)
           
 void arcNegative(Point point, double radius, double angle1, double angle2)
          Adds an arc from angle1 to angle2 to the current path.
 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()).
 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()).
 void closePath()
          Closes the current path by connecting current point to the starting point with a line segment.
 void copyPage()
           
 void curveTo(double x1, double y1, double x2, double y2, double x3, double y3)
           
 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).
 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).
 Point deviceToUserDistance(Point distance)
          Transform a distance vector from device space to user space.
 void ellipse(double cx, double cy, double rx, double ry)
          Creates an ellipse path.
 void fill()
          A drawing operator that fills the current path according to the current fill rule.
 Rectangle fillExtents()
           
 void fillPreserve()
          A drawing operator that fills the current path according to the current fill rule.
 FontExtents fontExtents()
          Gets the font extents for the currently selected font.
 Antialias getAntialias()
           
 Point getCurrentPoint()
          Returns the current point of the surface.
 FillRule getFillRule()
          Gets the current fill rule, as set by setFillRule().
 FontFace getFontFace()
          Gets the current font face.
 Matrix getFontMatrix()
          Gets the current font matrix.
 FontOptions getFontOptions()
           
 LineCap getLineCap()
          Returns current linecap style.
 LineJoin getLineJoin()
          Return current line join style.
 double getLineWidth()
          Returns the stroke line width.
 Matrix getMatrix()
          Returns the current transformation matrix
 double getMiterLimit()
          Returns the miter limit for miter style line joins
 Operator getOperator()
          Returns the current surface operator
 Pattern getSource()
          Gets the current source pattern for this object.
 Surface getTarget()
          Gets the target surface for the cairo context as passed to the constructor.
 double getTolerance()
          Returns the tesselation tolerance of the current state.
 TextExtents glyphExtents(Glyph[] glyphs)
          Gets the extents for an array of glyphs.
 void glyphPath(Glyph[] glyphs)
           
 void identityMatrix()
          Resets the current transformation matrix (CTM) by setting it equal to the identity matrix.
 void lineTo(double x, double y)
           
 void lineTo(Point p)
          Draws a line segment as part of the current path.
 void mask(Pattern pattern)
          A drawing operator that paints the current source using the alpha channel of pattern as a mask.
 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.
 void moveTo(double x, double y)
           
 void moveTo(Point p)
          Moves the current point in the path to the given co-ordinates.
 void newPath()
          Starts a new path.
 void paint()
          A drawing operator that paints the current source everywhere within the current clip region.
 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.
 void rectangle(Point p1, Point p2)
           
 void rectangle(Rectangle rect)
           
 void relCurveTo(double x1, double y1, double x2, double y2, double x3, double y3)
           
 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.
 void relLineTo(double x, double y)
           
 void relLineTo(Point p)
          Draws a line segment as part of the current path.
 void relMoveTo(double x, double y)
           
 void relMoveTo(Point p)
          Moves to the current path to a new point.
 void resetClip()
          Reset the current clip region to its original, unrestricted state.
 void restore()
          Restores the state saved by a preceding call to save() and removes that state from the stack of saved states.
 void rotate(double angle)
          Modifies the current transformation matrix (CTM) by rotating the user-space axes by angle radians.
 void save()
          Makes a copy of the current state and saves it on an internal stack of saved states.
 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.
 void selectFontFace(java.lang.String family, FontSlant slant, FontWeight weight)
          Selects a family and style of font from a simplified description as a family name, slant and weight.
 void setAntialias(Antialias antialias)
           
 void setDash(double[] dashes, double offset)
          Sets the line dash.
 void setFillRule(FillRule fillrule)
          Set the current fill rule within the Context.
 void setFontFace(FontFace fontFace)
          Replaces the current FontFace object in the context with fontFace.
 void setFontMatrix(Matrix matrix)
          Sets the current font matrix to matrix.
 void setFontOptions(FontOptions fontOptions)
           
 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().
 void setLineCap(LineCap linecap)
          Sets the current line cap style within the cairo context.
 void setLineJoin(LineJoin linejoin)
          Sets the current line join style within the cairo context.
 void setLineWidth(double width)
          Sets the current line width within the cairo context.
 void setMatrix(Matrix matrix)
          Modifies the current transformation matrix (CTM) by setting it equal to matrix.
 void setMiterLimit(double limit)
          Sets the miter limit.
 void setOperator(Operator op)
          Sets the compositing operator to be used for all drawing operations.
 void setSource(Pattern pattern)
          Sets the source pattern within the Cairo object.
 void setSource(Surface surface, double x, double y)
           
 void setSourceRGB(double red, double green, double blue)
          Sets a constant color for filling and stroking.
 void setSourceRGBA(double red, double green, double blue, double alpha)
          Sets the source pattern within this Cairo object to a translucent color.
 void setTolerance(double tolerance)
          Sets the tolerance used when converting paths into trapezoids.
 void showGlyphs(Glyph[] glyphs)
           
 void showPage()
           
 void showText(java.lang.String text)
          Draws the given text on the screen.
 Status status()
           
 void stroke()
          A drawing operator that strokes the current path according to the current line width, line join, line cap, and dash settings.
 Rectangle strokeExtents()
           
 void strokePreserve()
          A drawing operator that strokes the current path according to the current line width, line join, line cap, and dash settings.
 TextExtents textExtents(java.lang.String text)
          Gets the extents for a string of text.
 void textPath(java.lang.String text)
           
 void transform(Matrix matrix)
          Modifies the current transformation matrix (CTM) by applying matrix as an additional transformation.
 void translate(double tx, double ty)
          Modifies the current transformation matrix (CTM) by tanslating the user-space origin by (tx, ty).
 Point userToDevice(Point point)
          Transform a coordinate from user space to device space by multiplying the given point by the current transformation matrix (CTM).
 Point userToDeviceDistance(Point distance)
          Transform a distance vector from user space to device space.
 
Methods inherited from class org.gnu.glib.Struct
equals, getHandle, getNullHandle, hashCode
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, toString, wait, wait, wait
 

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.
Method Detail

save

public void save()
Makes a copy of the current state and saves it on an internal stack of saved states. When 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().


restore

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


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 -

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 -

setSource

public void setSource(Surface surface,
                      double x,
                      double y)
Parameters:
surface -
x -
y -

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 -

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 -

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 -

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 -

setDash

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

Parameters:
dashes -
offset -

setMiterLimit

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

Parameters:
limit -

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 -

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 -

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 -

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

setMatrix

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

Parameters:
matrix - the transformation matrix

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.


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.


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.


newPath

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


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)

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)

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)

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)

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)

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)

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)

rectangle

public void rectangle(Point p1,
                      Point p2)

rectangle

public void rectangle(Rectangle rect)

closePath

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


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 -

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 -

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.


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.


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.


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.


copyPage

public void copyPage()

showPage

public void showPage()

strokeExtents

public Rectangle strokeExtents()

fillExtents

public Rectangle fillExtents()

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.


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().


selectFontFace

public void selectFontFace(java.lang.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

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.

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.

getFontMatrix

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

Returns:
the current font matrix

showText

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

Parameters:
text - String to draw on the screen.

showGlyphs

public void showGlyphs(Glyph[] glyphs)

getFontFace

public FontFace getFontFace()
Gets the current font face.


fontExtents

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


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 -

textExtents

public TextExtents textExtents(java.lang.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.


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


textPath

public void textPath(java.lang.String text)

glyphPath

public void glyphPath(Glyph[] glyphs)

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.


getTolerance

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

Returns:
tesselation tolerance

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().


getLineWidth

public double getLineWidth()
Returns the stroke line width.

Returns:
The stroke line width

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

getMiterLimit

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

Returns:
The miter limit

getMatrix

public Matrix getMatrix()
Returns the current transformation matrix

Returns:
the current transformation matrix

getTarget

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

Returns:
the target surface

status

public Status status()

setAntialias

public void setAntialias(Antialias antialias)

getAntialias

public Antialias getAntialias()

setFontOptions

public void setFontOptions(FontOptions fontOptions)

getFontOptions

public FontOptions getFontOptions()

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