Class Path

java.lang.Object
org.javagi.base.ProxyInstance
org.gnome.gsk.Path
All Implemented Interfaces:
Proxy
@Generated("org.javagi.JavaGI") public class Path extends ProxyInstance

Describes lines and curves that are more complex than simple rectangles.

Paths can used for rendering (filling or stroking) and for animations (e.g. as trajectories).

GskPath is an immutable, opaque, reference-counted struct. After creation, you cannot change the types it represents. Instead, new GskPath objects have to be created. The Gsk.PathBuilder structure is meant to help in this endeavor.

Conceptually, a path consists of zero or more contours (continuous, connected curves), each of which may or may not be closed. Contours are typically constructed from Bézier segments.

A Path
Since:
4.14

  • Constructor Details

    • Path

      public Path(MemorySegment address)
      Create a Path proxy instance for the provided memory address.
      Parameters:
      address - the memory address of the native object

  • Method Details

    • getType

      public static @Nullable Type getType()
      Get the GType of the Path class.
      Returns:
      the GType

    • getMemoryLayout

      public static MemoryLayout getMemoryLayout()
      The memory layout of the native struct.
      Returns:
      the memory layout

    • parse

      public static @Nullable Path parse(String string)

      Constructs a path from a serialized form.

      The string is expected to be in (a superset of) SVG path syntax, as e.g. produced by toString().

      A high-level summary of the syntax:

      • M x y Move to (x, y)
      • L x y Add a line from the current point to (x, y)
      • Q x1 y1 x2 y2 Add a quadratic Bézier from the current point to (x2, y2), with control point (x1, y1)
      • C x1 y1 x2 y2 x3 y3 Add a cubic Bézier from the current point to (x3, y3), with control points (x1, y1) and (x2, y2)
      • Z Close the contour by drawing a line back to the start point
      • H x Add a horizontal line from the current point to the given x value
      • V y Add a vertical line from the current point to the given y value
      • T x2 y2 Add a quadratic Bézier, using the reflection of the previous segments' control point as control point
      • S x2 y2 x3 y3 Add a cubic Bézier, using the reflection of the previous segments' second control point as first control point
      • A rx ry r l s x y Add an elliptical arc from the current point to (x, y) with radii rx and ry. See the SVG documentation for how the other parameters influence the arc.
      • O x1 y1 x2 y2 w Add a rational quadratic Bézier from the current point to (x2, y2) with control point (x1, y1) and weight w.

      All the commands have lowercase variants that interpret coordinates relative to the current point.

      The O command is an extension that is not supported in SVG.

      Parameters:
      string - a string
      Returns:
      a new GskPath, or NULL if string could not be parsed
      Since:
      4.14

    • equal

      public boolean equal(Path path2)

      Returns whether two paths have identical structure.

      Note that it is possible to construct paths that render identical even though they don't have the same structure.

      Parameters:
      path2 - another path
      Returns:
      true if this Path and path2 have identical structure
      Since:
      4.22

    • foreach

      public boolean foreach(Set<PathForeachFlags> flags, @Nullable PathForeachFunc func)

      Calls func for every operation of the path.

      Note that this may only approximate self, because paths can contain optimizations for various specialized contours, and depending on the flags, the path may be decomposed into simpler curves than the ones that it contained originally.

      This function serves two purposes:

      • When the flags allow everything, it provides access to the raw, unmodified data of the path.
      • When the flags disallow certain operations, it provides an approximation of the path using just the allowed operations.
      Parameters:
      flags - flags to pass to the foreach function
      func - the function to call for operations
      Returns:
      false if func returned false, true otherwise.
      Since:
      4.14

    • foreach

      public boolean foreach(PathForeachFlags flags, @Nullable PathForeachFunc func)

      Calls func for every operation of the path.

      Note that this may only approximate self, because paths can contain optimizations for various specialized contours, and depending on the flags, the path may be decomposed into simpler curves than the ones that it contained originally.

      This function serves two purposes:

      • When the flags allow everything, it provides access to the raw, unmodified data of the path.
      • When the flags disallow certain operations, it provides an approximation of the path using just the allowed operations.
      Parameters:
      flags - flags to pass to the foreach function
      func - the function to call for operations
      Returns:
      false if func returned false, true otherwise.
      Since:
      4.14

    • foreachIntersection

      public boolean foreachIntersection(@Nullable Path path2, @Nullable PathIntersectionFunc func)

      Finds intersections between two paths.

      This function finds intersections between this Path and path2, and calls func for each of them, in increasing order for path1.

      If path2 is not provided or equal to path1, the function finds non-trivial self-intersections of path1.

      When segments of the paths coincide, the callback is called once for the start of the segment, with GSKPATHINTERSECTIONSTART, and once for the end of the segment, with GSKPATHINTERSECTIONEND. Note that other intersections may occur between the start and end of such a segment.

      If func returns FALSE, the iteration is stopped.

      Parameters:
      path2 - the second path
      func - the function to call for intersections
      Returns:
      FALSE if func returned FALSE, TRUE` otherwise.
      Since:
      4.20

    • getBounds

      public boolean getBounds(Rect bounds)

      Computes the bounds of the given path.

      The returned bounds may be larger than necessary, because this function aims to be fast, not accurate. The bounds are guaranteed to contain the path. For accurate bounds, use getTightBounds(Rect).

      It is possible that the returned rectangle has 0 width and/or height. This can happen when the path only describes a point or an axis-aligned line.

      If the path is empty, false is returned and bounds are set to graphene_rect_zero(). This is different from the case where the path is a single point at the origin, where the bounds will also be set to the zero rectangle but true will be returned.

      Parameters:
      bounds - return location for the bounds
      Returns:
      true if the path has bounds, false if the path is known to be empty and have no bounds
      Since:
      4.14

    • getClosestPoint

      public boolean getClosestPoint(Point point, float threshold, PathPoint result, @Nullable Out<Float> distance)

      Computes the closest point on the path to the given point.

      If there is no point closer than the given threshold, false is returned.

      Parameters:
      point - the point
      threshold - maximum allowed distance
      result - return location for the closest point
      distance - return location for the distance
      Returns:
      true if point was set to the closest point on self, false if no point is closer than threshold
      Since:
      4.14

    • getEndPoint

      public boolean getEndPoint(PathPoint result)

      Gets the end point of the path.

      An empty path has no points, so false is returned in this case.

      Parameters:
      result - return location for point
      Returns:
      true if result was filled
      Since:
      4.14

    • getNext

      public boolean getNext(PathPoint point)

      Moves point to the next vertex.

      An empty path has no points, so false is returned in this case.

      Parameters:
      point - the current point
      Returns:
      true if point was set
      Since:
      4.22

    • getPrevious

      public boolean getPrevious(PathPoint point)

      Moves point to the previous vertex.

      An empty path has no points, so false is returned in this case.

      Parameters:
      point - the current point
      Returns:
      true if point was set
      Since:
      4.22

    • getStartPoint

      public boolean getStartPoint(PathPoint result)

      Gets the start point of the path.

      An empty path has no points, so false is returned in this case.

      Parameters:
      result - return location for point
      Returns:
      true if result was filled
      Since:
      4.14

    • getStrokeBounds

      public boolean getStrokeBounds(Stroke stroke, Rect bounds)

      Computes the bounds for stroking the given path with the given parameters.

      The returned bounds may be larger than necessary, because this function aims to be fast, not accurate. The bounds are guaranteed to contain the area affected by the stroke, including protrusions like miters.

      Parameters:
      stroke - stroke parameters
      bounds - the bounds to fill in
      Returns:
      true if the path has bounds, false if the path is known to be empty and have no bounds.
      Since:
      4.14

    • getTightBounds

      public boolean getTightBounds(Rect bounds)

      Computes the tight bounds of the given path.

      This function works harder than getBounds(Rect) to produce the smallest possible bounds.

      Parameters:
      bounds - return location for the bounds
      Returns:
      true if the path has bounds, false if the path is known to be empty and have no bounds
      Since:
      4.22

    • inFill

      public boolean inFill(Point point, FillRule fillRule)

      Returns whether a point is inside the fill area of a path.

      Note that this function assumes that filling a contour implicitly closes it.

      Parameters:
      point - the point to test
      fillRule - the fill rule to follow
      Returns:
      true if point is inside
      Since:
      4.14

    • isClosed

      public boolean isClosed()
      Returns if the path represents a single closed contour.
      Returns:
      true if the path is closed
      Since:
      4.14

    • isEmpty

      public boolean isEmpty()
      Checks if the path is empty, i.e. contains no lines or curves.
      Returns:
      true if the path is empty
      Since:
      4.14

    • print

      public void print(String string)

      Converts the path into a human-readable representation.

      The string is compatible with (a superset of) SVG path syntax, see parse(String) for a summary of the syntax.

      Parameters:
      string - the string to print into
      Since:
      4.14

    • ref

      public Path ref()
      Increases the reference count of a path by one.
      Returns:
      the passed in GskPath
      Since:
      4.14

    • toCairo

      public void toCairo(org.freedesktop.cairo.Context cr)

      Appends the path to a cairo context for drawing with Cairo.

      This may cause some suboptimal conversions to be performed as Cairo does not support all features of GskPath.

      This function does not clear the existing Cairo path. Call cairo_new_path() if you want this.

      Parameters:
      cr - a cairo context
      Since:
      4.14

    • toString

      public String toString()

      Converts the path into a human-readable string.

      You can use this function in a debugger to get a quick overview of the path.

      This is a wrapper around print(String), see that function for details.

      Overrides:
      toString in class Object
      Returns:
      a new string for this Path
      Since:
      4.14

    • unref

      public void unref()

      Decreases the reference count of a path by one.

      If the resulting reference count is zero, frees the path.

      Since:
      4.14