org.freedesktop.cairo
Class Context

java.lang.Object
  org.freedesktop.bindings.Proxy
      org.freedesktop.cairo.Context

public class Context
extends 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

Graphics will be rendered to the Surface specified when you construct the Context:

• 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 using the underlying GDK Window in your Widget's EXPOSE_EVENT, and do your drawing there.

See the links above for examples of each use case.

Drawing Operations

Context has numerous methods allowing you to draw shapes, patterns, and images to the Surface you are drawing on. These operations are all quite low level, but give you very fine grained control over what is drawn and where.

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.setSourceRGB(1.0, 0.0, 0.0);
 

for solid red. In the case of co-ordinates, you can simply specify the pixel address you wish to move to or draw to:

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

where stroke draws the current path with the current line thickness.

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

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

and so on.

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

Since:

4.0.7

Author:

Andrew Cowie, Carl Worth, Behdad Esfahbod, Vreixo Formoso

See Also:

Cairo Graphics documentation

Constructor Summary

Context(Drawable drawable)
Construct a new "Cairo Context" related to a Drawable.

Context(Surface target)
Construct a new "Cairo Context".

Method Summary

void	arc(double xc, double yc, double radius, double angle1, double angle2) Adds a circular arc of the given radius to the current path.
void	arcNegative(double xc, double yc, double radius, double angle1, double angle2) Adds a circular arc of the given radius to the current path.
void	fill() Fill the current path, implicitly closing sub-paths first.
void	fillPreserve()
Pattern	getSource() Get the current source Pattern for this Context.
Surface	getTarget() Get the Surface that this Context is drawing on.
void	lineTo(double x, double y) Add a line from the current location to x,y.
void	mask(Pattern pattern) Paint the current source using the alpha channel of pattern as a mask.
void	moveTo(double x, double y) Move to a new location without drawing, beginning a new sub-path.
void	paint() Paint the current source everywhere within the current clip region.
void	rectangle(double x, double y, double width, double height) Draw a (closed) rectangular sub-path.
void	setAntialias(Antialias antialias) Set the antialiasing mode of the rasterizer used for drawing shapes.
void	setLineWidth(double width) Set the line width for this Context.
void	setOperator(Operator op) Set the operation that will govern forthcoming compositing actions.
void	setSource(Pattern pattern) Set a Pattern to be the source of this Context.
void	setSourceRGB(double red, double green, double blue) Set the source pattern within this Context to an opaque colour.
void	setSourceRGBA(double red, double green, double blue, double alpha) Set the source pattern within this Context to a translucent colour.
void	setSourceSurface(Surface surface, double x, double y) Create a Pattern from a Surface, and then use it in this Context.
void	stroke() Draw the current path as a line.

Methods inherited from class org.freedesktop.bindings.Proxy

toString

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

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

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(Surface target)

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

Since:

4.0.7

Method Detail

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 axis, increasing in a clockwise direction.

This function gives the arc in the direction of increasing angles; see arcNegative() to go 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, 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π until it is less than angle1.

See arc() for drawing in the positive direction.

Since:

4.0.7

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

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

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

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

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

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

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(Pattern pattern)

Set a Pattern to be the source of this Context.

Since:

4.0.7

setSourceRGB

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

setSourceRGBA

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

setSourceSurface

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

stroke

public void stroke()

Draw the current path as a line.

Since:

4.0.7