:right-sidebar: True Path =================================================================== .. currentmodule:: gi.repository.Gsk .. versionadded:: 4.14 .. class:: Path(*args, **kwargs) :no-contents-entry: A ``GskPath`` 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 :obj:`~gi.repository.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. .. image:: https://docs.gtk.org/gsk4/path-light.png Methods ------- .. rst-class:: interim-class .. class:: Path :no-index: .. method:: foreach(flags: ~gi.repository.Gsk.PathForeachFlags, func: ~typing.Callable[[~gi.repository.Gsk.PathOperation, ~gi.repository.Graphene.Point, int, float, ~typing.Any], bool], user_data: ~typing.Any = None) -> bool 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. .. versionadded:: 4.14 :param flags: flags to pass to the foreach function. See :obj:`~gi.repository.Gsk.PathForeachFlags` for details about flags :param func: the function to call for operations :param user_data: user data passed to ``func`` .. method:: get_bounds() -> ~typing.Tuple[bool, ~gi.repository.Graphene.Rect] 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. 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 :func:`~gi.repository.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. .. versionadded:: 4.14 .. method:: get_closest_point(point: ~gi.repository.Graphene.Point, threshold: float) -> ~typing.Tuple[bool, ~gi.repository.Gsk.PathPoint, float] Computes the closest point on the path to the given point and sets the ``result`` to it. If there is no point closer than the given threshold, ``FALSE`` is returned. .. versionadded:: 4.14 :param point: the point :param threshold: maximum allowed distance .. method:: get_end_point() -> ~typing.Tuple[bool, ~gi.repository.Gsk.PathPoint] Gets the end point of the path. An empty path has no points, so ``FALSE`` is returned in this case. .. versionadded:: 4.14 .. method:: get_start_point() -> ~typing.Tuple[bool, ~gi.repository.Gsk.PathPoint] Gets the start point of the path. An empty path has no points, so ``FALSE`` is returned in this case. .. versionadded:: 4.14 .. method:: get_stroke_bounds(stroke: ~gi.repository.Gsk.Stroke) -> ~typing.Tuple[bool, ~gi.repository.Graphene.Rect] Computes the bounds for stroking the given path with the parameters in ``stroke``\. 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. .. versionadded:: 4.14 :param stroke: stroke parameters .. method:: in_fill(point: ~gi.repository.Graphene.Point, fill_rule: ~gi.repository.Gsk.FillRule) -> bool Returns whether the given point is inside the area that would be affected if the path was filled according to ``fill_rule``\. Note that this function assumes that filling a contour implicitly closes it. .. versionadded:: 4.14 :param point: the point to test :param fill_rule: the fill rule to follow .. method:: is_closed() -> bool Returns if the path represents a single closed contour. .. versionadded:: 4.14 .. method:: is_empty() -> bool Checks if the path is empty, i.e. contains no lines or curves. .. versionadded:: 4.14 .. classmethod:: parse() -> ~gi.repository.Gsk.Path | None This is a convenience function that constructs a ``GskPath`` from a serialized form. The string is expected to be in (a superset of) `SVG path syntax `__\, as e.g. produced by :obj:`~gi.repository.Gsk.Path.to_string`\. 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. .. versionadded:: 4.14 .. method:: print_(string: ~gi.repository.GLib.String) -> None :param string: .. method:: to_cairo(cr: ~gi.repository.cairo.Context) -> None Appends the given ``path`` to the given 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. .. versionadded:: 4.14 :param cr: a cairo context .. method:: to_string() -> str Converts the path into a string that is suitable for printing. You can use this function in a debugger to get a quick overview of the path. This is a wrapper around :obj:`~gi.repository.Gsk.Path.print`\, see that function for details. .. versionadded:: 4.14