Constructor Detail

• Context

  public Context(Surface target)

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

  Since:

  4.0.7

• Context

  public Context(Window window)

  Construct a new "Cairo Context" related to a Window. 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.1.1

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

  Set the source pattern within this Context to the given RGBA colour.

  Since:

  4.1.1

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