:right-sidebar: True PathBuilder =================================================================== .. currentmodule:: gi.repository.Gsk .. versionadded:: 4.14 .. class:: PathBuilder(**kwargs) :no-contents-entry: ``GskPathBuilder`` is an auxiliary object for constructing ``GskPath`` objects. A path is constructed like this: .. code-block:: C :dedent: GskPath * construct_path (void) { GskPathBuilder *builder; builder = gsk_path_builder_new (); // add contours to the path here return gsk_path_builder_free_to_path (builder); Adding contours to the path can be done in two ways. The easiest option is to use the ``gsk_path_builder_add_*`` group of functions that add predefined contours to the current path, either common shapes like :obj:`~gi.repository.Gsk.PathBuilder.add_circle` or by adding from other paths like :obj:`~gi.repository.Gsk.PathBuilder.add_path`\. The ``gsk_path_builder_add_*`` methods always add complete contours, and do not use or modify the current point. The other option is to define each line and curve manually with the ``gsk_path_builder_*_to`` group of functions. You start with a call to :obj:`~gi.repository.Gsk.PathBuilder.move_to` to set the starting point and then use multiple calls to any of the drawing functions to move the pen along the plane. Once you are done, you can call :obj:`~gi.repository.Gsk.PathBuilder.close` to close the path by connecting it back with a line to the starting point. This is similar to how paths are drawn in Cairo. Note that ``GskPathBuilder`` will reduce the degree of added Bézier curves as much as possible, to simplify rendering. Constructors ------------ .. rst-class:: interim-class .. class:: PathBuilder :no-index: .. classmethod:: new() -> ~gi.repository.Gsk.PathBuilder Create a new ``GskPathBuilder`` object. The resulting builder would create an empty ``GskPath``\. Use addition functions to add types to it. .. versionadded:: 4.14 Methods ------- .. rst-class:: interim-class .. class:: PathBuilder :no-index: .. method:: add_cairo_path(path: ~gi.repository.cairo.Path) -> None Adds a Cairo path to the builder. You can use cairo_copy_path() to access the path from a Cairo context. .. versionadded:: 4.14 :param path: a path .. method:: add_circle(center: ~gi.repository.Graphene.Point, radius: float) -> None Adds a circle with the ``center`` and ``radius``\. The path is going around the circle in clockwise direction. If ``radius`` is zero, the contour will be a closed point. .. versionadded:: 4.14 :param center: the center of the circle :param radius: the radius of the circle .. method:: add_layout(layout: ~gi.repository.Pango.Layout) -> None Adds the outlines for the glyphs in ``layout`` to the builder. .. versionadded:: 4.14 :param layout: the pango layout to add .. method:: add_path(path: ~gi.repository.Gsk.Path) -> None Appends all of ``path`` to the builder. .. versionadded:: 4.14 :param path: the path to append .. method:: add_rect(rect: ~gi.repository.Graphene.Rect) -> None Adds ``rect`` as a new contour to the path built by the builder. The path is going around the rectangle in clockwise direction. If the the width or height are 0, the path will be a closed horizontal or vertical line. If both are 0, it'll be a closed dot. .. versionadded:: 4.14 :param rect: The rectangle to create a path for .. method:: add_reverse_path(path: ~gi.repository.Gsk.Path) -> None Appends all of ``path`` to the builder, in reverse order. .. versionadded:: 4.14 :param path: the path to append .. method:: add_rounded_rect(rect: ~gi.repository.Gsk.RoundedRect) -> None Adds ``rect`` as a new contour to the path built in ``self``\. The path is going around the rectangle in clockwise direction. .. versionadded:: 4.14 :param rect: the rounded rect .. method:: add_segment(path: ~gi.repository.Gsk.Path, start: ~gi.repository.Gsk.PathPoint, end: ~gi.repository.Gsk.PathPoint) -> None Adds to ``self`` the segment of ``path`` from ``start`` to ``end``\. If ``start`` is equal to or after ``end``\, the path will first add the segment from ``start`` to the end of the path, and then add the segment from the beginning to ``end``\. If the path is closed, these segments will be connected. Note that this method always adds a path with the given start point and end point. To add a closed path, use :obj:`~gi.repository.Gsk.PathBuilder.add_path`\. .. versionadded:: 4.14 :param path: the ``GskPath`` to take the segment to :param start: the point on ``path`` to start at :param end: the point on ``path`` to end at .. method:: arc_to(x1: float, y1: float, x2: float, y2: float) -> None Adds an elliptical arc from the current point to ``x2``\, ``y2`` with ``x1``\, ``y1`` determining the tangent directions. After this, ``x2``\, ``y2`` will be the new current point. Note: Two points and their tangents do not determine a unique ellipse, so GSK just picks one. If you need more precise control, use :obj:`~gi.repository.Gsk.PathBuilder.conic_to` or :obj:`~gi.repository.Gsk.PathBuilder.svg_arc_to`\. .. image:: https://docs.gtk.org/gsk4/arc-light.png .. versionadded:: 4.14 :param x1: x coordinate of first control point :param y1: y coordinate of first control point :param x2: x coordinate of second control point :param y2: y coordinate of second control point .. method:: close() -> None Ends the current contour with a line back to the start point. Note that this is different from calling :obj:`~gi.repository.Gsk.PathBuilder.line_to` with the start point in that the contour will be closed. A closed contour behaves differently from an open one. When stroking, its start and end point are considered connected, so they will be joined via the line join, and not ended with line caps. .. versionadded:: 4.14 .. method:: conic_to(x1: float, y1: float, x2: float, y2: float, weight: float) -> None Adds a `conic curve `__ from the current point to ``x2``\, ``y2`` with the given ``weight`` and ``x1``\, ``y1`` as the control point. The weight determines how strongly the curve is pulled towards the control point. A conic with weight 1 is identical to a quadratic Bézier curve with the same points. Conic curves can be used to draw ellipses and circles. They are also known as rational quadratic Bézier curves. After this, ``x2``\, ``y2`` will be the new current point. .. image:: https://docs.gtk.org/gsk4/conic-light.png .. versionadded:: 4.14 :param x1: x coordinate of control point :param y1: y coordinate of control point :param x2: x coordinate of the end of the curve :param y2: y coordinate of the end of the curve :param weight: weight of the control point, must be greater than zero .. method:: cubic_to(x1: float, y1: float, x2: float, y2: float, x3: float, y3: float) -> None Adds a `cubic Bézier curve `__ from the current point to ``x3``\, ``y3`` with ``x1``\, ``y1`` and ``x2``\, ``y2`` as the control points. After this, ``x3``\, ``y3`` will be the new current point. .. image:: https://docs.gtk.org/gsk4/cubic-light.png .. versionadded:: 4.14 :param x1: x coordinate of first control point :param y1: y coordinate of first control point :param x2: x coordinate of second control point :param y2: y coordinate of second control point :param x3: x coordinate of the end of the curve :param y3: y coordinate of the end of the curve .. method:: get_current_point() -> ~gi.repository.Graphene.Point Gets the current point. The current point is used for relative drawing commands and updated after every operation. When the builder is created, the default current point is set to ``0, 0``\. Note that this is different from cairo, which starts out without a current point. .. versionadded:: 4.14 .. method:: html_arc_to(x1: float, y1: float, x2: float, y2: float, radius: float) -> None Implements arc-to according to the HTML Canvas spec. A convenience function that implements the `HTML arc_to `__ functionality. After this, the current point will be the point where the circle with the given radius touches the line from ``x1``\, ``y1`` to ``x2``\, ``y2``\. .. versionadded:: 4.14 :param x1: X coordinate of first control point :param y1: Y coordinate of first control point :param x2: X coordinate of second control point :param y2: Y coordinate of second control point :param radius: Radius of the circle .. method:: line_to(x: float, y: float) -> None Draws a line from the current point to ``x``\, ``y`` and makes it the new current point. .. image:: https://docs.gtk.org/gsk4/line-light.png .. versionadded:: 4.14 :param x: x coordinate :param y: y coordinate .. method:: move_to(x: float, y: float) -> None Starts a new contour by placing the pen at ``x``\, ``y``\. If this function is called twice in succession, the first call will result in a contour made up of a single point. The second call will start a new contour. .. versionadded:: 4.14 :param x: x coordinate :param y: y coordinate .. method:: quad_to(x1: float, y1: float, x2: float, y2: float) -> None Adds a `quadratic Bézier curve `__ from the current point to ``x2``\, ``y2`` with ``x1``\, ``y1`` as the control point. After this, ``x2``\, ``y2`` will be the new current point. .. image:: https://docs.gtk.org/gsk4/quad-light.png .. versionadded:: 4.14 :param x1: x coordinate of control point :param y1: y coordinate of control point :param x2: x coordinate of the end of the curve :param y2: y coordinate of the end of the curve .. method:: rel_arc_to(x1: float, y1: float, x2: float, y2: float) -> None Adds an elliptical arc from the current point to ``x2``\, ``y2`` with ``x1``\, ``y1`` determining the tangent directions. All coordinates are given relative to the current point. This is the relative version of :obj:`~gi.repository.Gsk.PathBuilder.arc_to`\. .. versionadded:: 4.14 :param x1: x coordinate of first control point :param y1: y coordinate of first control point :param x2: x coordinate of second control point :param y2: y coordinate of second control point .. method:: rel_conic_to(x1: float, y1: float, x2: float, y2: float, weight: float) -> None Adds a `conic curve `__ from the current point to ``x2``\, ``y2`` with the given ``weight`` and ``x1``\, ``y1`` as the control point. All coordinates are given relative to the current point. This is the relative version of :obj:`~gi.repository.Gsk.PathBuilder.conic_to`\. .. versionadded:: 4.14 :param x1: x offset of control point :param y1: y offset of control point :param x2: x offset of the end of the curve :param y2: y offset of the end of the curve :param weight: weight of the curve, must be greater than zero .. method:: rel_cubic_to(x1: float, y1: float, x2: float, y2: float, x3: float, y3: float) -> None Adds a `cubic Bézier curve `__ from the current point to ``x3``\, ``y3`` with ``x1``\, ``y1`` and ``x2``\, ``y2`` as the control points. All coordinates are given relative to the current point. This is the relative version of :obj:`~gi.repository.Gsk.PathBuilder.cubic_to`\. .. versionadded:: 4.14 :param x1: x offset of first control point :param y1: y offset of first control point :param x2: x offset of second control point :param y2: y offset of second control point :param x3: x offset of the end of the curve :param y3: y offset of the end of the curve .. method:: rel_html_arc_to(x1: float, y1: float, x2: float, y2: float, radius: float) -> None Implements arc-to according to the HTML Canvas spec. All coordinates are given relative to the current point. This is the relative version of :obj:`~gi.repository.Gsk.PathBuilder.html_arc_to`\. .. versionadded:: 4.14 :param x1: X coordinate of first control point :param y1: Y coordinate of first control point :param x2: X coordinate of second control point :param y2: Y coordinate of second control point :param radius: Radius of the circle .. method:: rel_line_to(x: float, y: float) -> None Draws a line from the current point to a point offset from it by ``x``\, ``y`` and makes it the new current point. This is the relative version of :obj:`~gi.repository.Gsk.PathBuilder.line_to`\. .. versionadded:: 4.14 :param x: x offset :param y: y offset .. method:: rel_move_to(x: float, y: float) -> None Starts a new contour by placing the pen at ``x``\, ``y`` relative to the current point. This is the relative version of :obj:`~gi.repository.Gsk.PathBuilder.move_to`\. .. versionadded:: 4.14 :param x: x offset :param y: y offset .. method:: rel_quad_to(x1: float, y1: float, x2: float, y2: float) -> None Adds a `quadratic Bézier curve `__ from the current point to ``x2``\, ``y2`` with ``x1``\, ``y1`` the control point. All coordinates are given relative to the current point. This is the relative version of :obj:`~gi.repository.Gsk.PathBuilder.quad_to`\. .. versionadded:: 4.14 :param x1: x offset of control point :param y1: y offset of control point :param x2: x offset of the end of the curve :param y2: y offset of the end of the curve .. method:: rel_svg_arc_to(rx: float, ry: float, x_axis_rotation: float, large_arc: bool, positive_sweep: bool, x: float, y: float) -> None Implements arc-to according to the SVG spec. All coordinates are given relative to the current point. This is the relative version of :obj:`~gi.repository.Gsk.PathBuilder.svg_arc_to`\. .. versionadded:: 4.14 :param rx: X radius :param ry: Y radius :param x_axis_rotation: the rotation of the ellipsis :param large_arc: whether to add the large arc :param positive_sweep: whether to sweep in the positive direction :param x: the X coordinate of the endpoint :param y: the Y coordinate of the endpoint .. method:: svg_arc_to(rx: float, ry: float, x_axis_rotation: float, large_arc: bool, positive_sweep: bool, x: float, y: float) -> None Implements arc-to according to the SVG spec. A convenience function that implements the `SVG arc_to `__ functionality. After this, ``x``\, ``y`` will be the new current point. .. versionadded:: 4.14 :param rx: X radius :param ry: Y radius :param x_axis_rotation: the rotation of the ellipsis :param large_arc: whether to add the large arc :param positive_sweep: whether to sweep in the positive direction :param x: the X coordinate of the endpoint :param y: the Y coordinate of the endpoint .. method:: to_path() -> ~gi.repository.Gsk.Path Creates a new ``GskPath`` from the given builder. The given ``GskPathBuilder`` is reset once this function returns; you cannot call this function multiple times on the same builder instance. This function is intended primarily for language bindings. C code should use :obj:`~gi.repository.Gsk.PathBuilder.free_to_path`\. .. versionadded:: 4.14