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

  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, you get a Context in your Widget's `Widget.Draw` signal, 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.setSource(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, Zak Fenton
  See Also:
    Cairo Graphics documentation

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `Context(Surface target)` Construct a new "Cairo Context".
    `Context(Window window)` Construct a new "Cairo Context" related to a Window.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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` | `clip()` Confines subsequent drawing operations to the inside area of the current path.
    `void` | `clipPreserve()` Confines subsequent drawing operations to the inside area of the current path, leaving the path intact for subsequent reuse.
    `void` | `closePath()` Close the current path.
    `void` | `fill()` Fill the current path, implicitly closing sub-paths first.
    `void` | `fillPreserve()` Fill the current path, preserving the path such that it can be used used again.
    `double` | `getCurrentPointX()` Get the x co-ordinate of the current point.
    `double` | `getCurrentPointY()` Get the y co-ordinate of the current point.
    `double` | `getLineWidth()` Get the line width for this Context.
    `Pattern` | `getSource()` Get the current source Pattern for this Context.
    `Surface` | `getTarget()` Get the Surface that this Context is drawing on.
    `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?
    `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?
    `void` | `lineRelative(double dx, double dy)` Move to a location relative to the current point.
    `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` | `mask(Surface surface, double x, double y)` Paint the current source using the alpha channel of the given `surface` as its mask.
    `void` | `moveRelative(double dx, double dy)` Move to a location relative to the current point.
    `void` | `moveTo(double x, double y)` Move to a new location without drawing, beginning a new sub-path.
    `void` | `newSubPath()` Create a new path within the current one.
    `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` | `restore()` Restores the Context to the last (nested) saved state.
    `void` | `rotate(double r)` Applies a rotate transformation.
    `void` | `save()` Makes a copy of the current state of the Context and saves it on an internal stack.
    `void` | `scale(double sx, double sy)` Applies a scale transformation.
    `void` | `setAntialias(Antialias antialias)` Set the antialiasing mode of the rasterizer used for drawing shapes.
    `void` | `setDash(double[] dashes)` Sets the dash pattern used in lines drawn with `stroke()`.
    `void` | `setFillRule(FillRule setting)` Change the fill algorithm.
    `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(double red, double green, double blue)` Set the source pattern within this Context to an opaque colour.
    `void` | `setSource(double red, double green, double blue, double alpha)` Set the source pattern within this Context to a translucent colour.
    `void` | `setSource(Pattern pattern)` Set a Pattern to be the source of this Context.
    `void` | `setSource(Pixbuf pixbuf, double x, double y)` Given an image already loaded in a Pixbuf, set the current Source to be that image.
    `void` | `setSource(RGBA color)` Set the source pattern within this Context to the given RGBA colour.
    `void` | `setSource(Surface surface, double x, double y)` Create a Pattern from a Surface, and then use it in this Context.
    `void` | `showHandle(Handle graphic)` Render an SVG image to this Cairo surface.
    `void` | `showLayout(Layout layout)` Draw a paragraph of text.
    `void` | `showLayout(LayoutLine line)` Draw a single line of text as extracted from a Layout.
    `void` | `stroke()` Draw the current path as a line.
    `void` | `strokePreserve()` Draw the current path as a line, preserving the path such that it can be used used again.
    `void` | `transform(Matrix matrix)` Apply the given Matrix to affine transform this Context.
    `void` | `translate(double tx, double ty)` Applies a translation transformation.
    `void` | `updateLayout(Layout layout)`

    - ### Methods inherited from class org.freedesktop.bindings.Pointer

      `toString`

    - ### Methods inherited from class Object

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

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