org.freedesktop.cairo
Class Context

Object
  org.freedesktop.bindings.Pointer
      org.freedesktop.bindings.Proxy
          org.freedesktop.cairo.Context

public class Context
extends org.freedesktop.bindings.Proxy

Carry out drawing operations with the Cairo Graphics library. The current Context contains the state of the rendering engine, including the co-ordinates of as yet undrawn elements.

Constructing

• If creating an image to be written to a file, start with an ImageSurface, do your drawing, and then use Surface's writeToPNG() to output your image.
• If drawing to the screen in a user interface application, construct a Context in your Widget's Widget.ExposeEvent, and do your drawing there.

Drawing Operations

It is somewhat traditional to call your Context cr.

All of the methods on Context take arguments of type double to represent co-ordinates, angles, colours, transparency levels, etc. Colours are represented as values between 0.0 and 0.1, for example:

 cr.setSource(1.0, 0.0, 0.0);
 

 cr.moveTo(10, 10);
 cr.lineTo(90, 50);
 cr.stroke();
 

Various other drawing operations are done by creating a shape and then filling it in:

 cr.rectangle(30, 20, 60, 60);
 cr.fill();
 

Obviously this is only the beginning of our documentation for Cairo.

Since:

4.0.7

Author:

Andrew Cowie, Carl Worth, Behdad Esfahbod, Vreixo Formoso, Zak Fenton

See Also:

Cairo Graphics documentation

Context

public Context(Drawable drawable)

Construct a new "Cairo Context" related to a Drawable. This is the magic glue which allows you to link between GTK's Widgets and Cairo's drawing operations.

You may find yourself needing to get at the Surface that is being drawn on. Use getTarget().

If you're drawing in an Widget.ExposeEvent then you're better off using the Context(EventExpose) constructor.

Strictly speaking, this method is a part of GDK. We expose it here as we are, from the Java bindings' perspective, constructing a Cairo Context. So a constructor it is.

Since:

4.0.7

Context

public Context(EventExpose event)

Construct a new "Cairo Context" during an ExposeEvent. This is the magic glue which allows you to link between GTK's Widgets and Cairo's drawing operations.

This constructor takes the [org.gnome.gdk] EventExpose structure and passes is directly to some native code which constructs the Context, then clip()s it to the Region contained in the ExposeEvent. This isn't enough to save you running your drawing code, but it is enough to tell Cairo very early on to only actually render the part that has been damaged or exposed. This can save a lot of cycles deep down.

Since:

4.0.17

Context

public Context(Surface target)

Construct a new "Cairo Context". You supply the Surface that you are drawing to.

Since:

4.0.7

arc

public void arc(double xc,
                double yc,
                double radius,
                double angle1,
                double angle2)

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

Angles are measured in radians. An angle of 0.0 is in the direction of the positive x axis. An angle of π/2 radians (90°) is in the direction of the positive y axis. Angles increase in the direction from the positive x axis toward the positive y axis, increasing in a clockwise direction.

The 60° arc shown is from angle 0 through +π/3 radians, and was achieved with the following call:

 cr.arc(50.0, 50.0, 30.0, 0.0, Math.PI / 3.0);
 

The illustration has its axis centred at position 50, 50. The key point to note is that positive y is towards the bottom, and that increasing angles as drawn by this function go clockwise which is backwards from the Cartesian or Polar co-ordinates you're probably used to using in mathematics.

See arcNegative() to draw arcs that go in the other direction.

Since:

4.0.7

arcNegative

public void arcNegative(double xc,
                        double yc,
                        double radius,
                        double angle1,
                        double angle2)

Adds a circular arc of the given radius to the current path. The arc is centered at xc,yc, will begin 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π until it is less than angle1.

This 135° arc shown in the illustration goes from 0 to -3/4&pi radians:

 cr.arcNegative(50.0, 50.0, 30.0, 0.0, -Math.PI * 3.0 / 4.0);
 

note that in this example the second angle is negative; if 3/4&pi had been specified the arc would have continued to a point 45° below the -x axis.

See arc() for drawing arcs in the positive, clockwise direction.

Since:

4.0.7

clip

public void clip()

Confines subsequent drawing operations to the inside area of the current path.

Since:

4.0.10

clipPreserve

public void clipPreserve()

Confines subsequent drawing operations to the inside area of the current path, leaving the path intact for subsequent reuse.

Since:

4.0.10

closePath

public void closePath()

Close the current path.

This makes the path a closed loop, rather than it being a line with caps at each end. Call this when you're trying to close a shape.

The current path begins at the point given to the last moveTo() call. If there's no current point, then this has no effect.

Since:

4.0.17

fill

public void fill()

Fill the current path, implicitly closing sub-paths first. The drawing will be done according to the current FillRule. The path will be cleared after calling fill(); if you want to keep it use fillPreserve() instead.

Since:

4.0.7

fillPreserve

public void fillPreserve()

Fill the current path, preserving the path such that it can be used used again. This is useful if you have drawn a shape and want to stroke() it with a different colour as an outline.

Since:

4.0.7

getCurrentPointX

public double getCurrentPointX()

Get the x co-ordinate of the current point.

You'll need to call this if you want to resume drawing at that point after calling stroke() or fill(), as after doing their work they clear the current path; the current point goes along with it.

 // do some drawing
 
 x = cr.getCurrentPointX();
 y = cr.getCurrentPointY();
 
 cr.stroke();
 
 cr.moveTo(x, y);
 
 // carry on drawing
 

Since:

4.0.10

getCurrentPointY

public double getCurrentPointY()

Get the y co-ordinate of the current point. See getCurrentPointX() for discussion of when you'd need this.

Since:

4.0.10

getLineWidth

public double getLineWidth()

Get the line width for this Context.

Since:

4.0.12

getSource

public Pattern getSource()

Get the current source Pattern for this Context.

Since:

4.0.7

getTarget

public Surface getTarget()

Get the Surface that this Context is drawing on.

Yes, this method has a stupid name. It really should be getSurface(). So many people have a hard time finding the generic method that allows you to get to the Surface that they're considering renaming this to cairo_get_surface in Cairo itself, but until they do, we'll stick with the algorithmic mapping of cairo_get_target.

Since:

4.0.7

inFill

public boolean inFill(double x,
                      double y)

Is the supplied point in the area that would be filled if fill() was called with the current path?

Since:

4.0.17

inStroke

public boolean inStroke(double x,
                        double y)

Is the supplied point in the thickness that would be drawn if stroke() was called with the current path?

Since:

4.0.17

lineRelative

public void lineRelative(double dx,
                         double dy)

Move to a location relative to the current point.

If the point is at x,y then this will draw a line from x,y to x+dx, y+dy, leaving the point at the latter location.

In the underlying native library this is cairo_rel_line_to(). We have adjusted the name slightly to provide for better discoverability in the completion space.

Since:

4.0.10

lineTo

public void lineTo(double x,
                   double y)

Add a line from the current location to x,y. After the call the current point will be x,y.

Since:

4.0.7

mask

public void mask(Pattern pattern)

Paint the current source using the alpha channel of pattern as a mask. This means "opaque areas of the mask will be painted with the source, whereas transparent areas will not be painted"

Since:

4.0.7

mask

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

Paint the current source using the alpha channel of the given surface as its mask. The Surface will be offset by x and y before drawing.

Since:

4.0.10

moveRelative

public void moveRelative(double dx,
                         double dy)

Move to a location relative to the current point.

If the point is at x,y then this will move the point to x+dx,y+dy.

In the underlying native library this is cairo_rel_move_to(). We have adjusted the name slightly to provide for better discoverability in the completion space.

Since:

4.0.10

moveTo

public void moveTo(double x,
                   double y)

Move to a new location without drawing, beginning a new sub-path. After the call the current point will be x,y.

Since:

4.0.7

newSubPath

public void newSubPath()

Create a new path within the current one. Although moveTo() also creates a new sub-path, this allows you to do so without needing destination co-ordinates.

Since:

4.0.17

paint

public void paint()

Paint the current source everywhere within the current clip region.

Since:

4.0.7

rectangle

public void rectangle(double x,
                      double y,
                      double width,
                      double height)

Draw a (closed) rectangular sub-path. The rectangle will be at x,y in user-space coordinates of the given width and height.

Since:

4.0.7

restore

public void restore()

Restores the Context to the last (nested) saved state.

Throws:

IllegalStateException - If there is no matching previous call to save().

Since:

4.0.10

rotate

public void rotate(double r)

Applies a rotate transformation. This rotates the co-ordinates of subsequent drawing operations through a given angle (in radians). The rotation happens around the origin (0, 0). To rotate around a different point, try the following:

 cr.translate(x, y);
 cr.rotate(r);
 cr.translate(-x, -y);
 

See Matrix for the full suite of affine transformations available.

Since:

4.0.10

save

public void save()

Makes a copy of the current state of the Context and saves it on an internal stack. The saved state is recovered using restore().

The utility of this function is to preserve a configuration that will be temporary modified. For example, if you are drawing something with a given color, line width, etc. and you need to change some of those properties, draw something else, and then go back to the original state. Instead of changing back all properties again, you can just invoke save() before modifying them, and then restore() later, once you want to use the original configuration again.

Multiple calls to save() and restore() can be nested. Each call to restore() restores the state from the matching paired save().

Since:

4.0.10

scale

public void scale(double sx,
                  double sy)

Applies a scale transformation. It scales X and Y axis by sx and sy, respectively.

The effect of this is that the points you submit are scaled by sx, sy. For example, the following sequence:

 Context cr;
 
 cr.scale(2.0, 3.0);
 cr.moveTo(1.0, 1.0);
 cr.lineTo(2.0, 2.0);
 cr.stroke();
 

Will actually draw a line from (2.0, 3.0) to (4.0, 6.0) in the target Surface.

Note that you can also use negative numbers. Do not scale by 0.

See Matrix for the full suite of affine transformations available.

Since:

4.0.12

setAntialias

public void setAntialias(Antialias antialias)

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.

Since:

4.0.7

setDash

public void setDash(double[] dashes)

Sets the dash pattern used in lines drawn with stroke().

The pattern is specified by an array of double values. Each value provides the length of alternate "on" and "off" portions of the stroke.

Since:

4.0.12

setFillRule

public void setFillRule(FillRule setting)

Change the fill algorithm. The default is WINDING.

Since:

4.0.17

setLineWidth

public void setLineWidth(double width)

Set the line width for this Context. This will have effect in next call to stroke(). Default value is 2.0.

Since:

4.0.7

setOperator

public void setOperator(Operator op)

Set the operation that will govern forthcoming compositing actions.

One particularly useful sequence is clearing the Surface to all transparent pixels:

 cr.setOperator(Operator.CLEAR);
 cr.paint();
 

Since:

4.0.7

setSource

public void setSource(Color color)

Set the source pattern within this Context to an opaque color.

Since:

4.0.12

setSource

public void setSource(double red,
                      double green,
                      double blue)

Set the source pattern within this Context to an opaque colour. The parameters each take the range 0.0 to 1.0.

Since:

4.0.10

setSource

public void setSource(double red,
                      double green,
                      double blue,
                      double alpha)

Set the source pattern within this Context to a translucent colour. The parameters each take the range 0.0 to 1.0. For the alpha parameter, a value of 0.0 indicates full transparency, and 1.0 is full opacity (ie, normal).

Since:

4.0.10

setSource

public void setSource(Pattern pattern)

Set a Pattern to be the source of this Context.

Since:

4.0.7

setSource

public void setSource(Pixbuf pixbuf,
                      double x,
                      double y)

Given an image already loaded in a Pixbuf, set the current Source to be that image. For example, to put the image at the bottom right of your drawing area, you might do something like:

 pixbuf = new Pixbuf(filename);
 cr.setSource(pixbuf, pageWidth - pixbuf.getWidth(), pageHeight - pixbuf.getHeight());
 cr.paint();
 

as paint() paints the current source "everywhere", and so down goes your image. If you are drawing the same image data to screen frequently, consider caching the image in video memory. See XlibSurface.

Since:

4.0.10

setSource

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

Create a Pattern from a Surface, and then use it in this Context. This is a convenience method.

x,y define where, in user-space coordinates, that the Pattern should appear.

You can get the Pattern that was created internally by calling this with getSource() and manipulate it further if you need to change the defaults.

Since:

4.0.10

showHandle

public void showHandle(Handle graphic)

Render an SVG image to this Cairo surface.

In the underlying native library this is rsvg_handle_render_cairo(). We have placed the call here to align with other Cairo baesd image and text rendering methods.

Since:

4.0.18

showLayout

public void showLayout(Layout layout)

Draw a paragraph of text. The top-left corner of the Layout's rendered extents will be drawn at the current Context point.

The text to draw and its format is specified in a Pango Layout, previously constructed with this Context.

Since:

4.0.10

showLayout

public void showLayout(LayoutLine line)

Draw a single line of text as extracted from a Layout.

Unlike the showLayout() taking a full Layout, this method draws the base line of the extent (its Rectangle's x, y origin) at the current Context point. See LayoutLine's getExtentsLogical() method for details.

Since:

4.0.10

stroke

public void stroke()

Draw the current path as a line.

Since:

4.0.7

strokePreserve

public void strokePreserve()

Draw the current path as a line, preserving the path such that it can be used used again. If you have drawn a shape and want to fill() it, you are better off calling fillPreserve() and, changing source and then calling stroke(); otherwise your fill will blot out the inside of your stroke.

Since:

4.0.10

transform

public void transform(Matrix matrix)

Apply the given Matrix to affine transform this Context. See Matrix for examples.

Beware that if there is a scaling component, line widths resulting from stroke() calls will scale too!

Since:

4.0.10

translate

public void translate(double tx,
                      double ty)

Applies a translation transformation. What this does is move the point of origin so that (0, 0) is now at a new position.

 cr.translate(20,50);
 cr.moveTo(20,20);    // This is now 40,70
  ...
 

See Matrix for the full suite of affine transformations available.

Since:

4.0.10

updateLayout

public void updateLayout(Layout layout)

Overview  Package   Class		java-gnome
PREV CLASS   NEXT CLASS	FRAMES    NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD	DETAIL: FIELD | CONSTR | METHOD