gtkmm: Gsk::PathBuilder Class Reference

gtkmm 4.23.2

Public Member Functions | Static Public Member Functions | Protected Member Functions | Related Symbols | List of all members
Gsk::PathBuilder Class Referencefinal

Constructs Gsk::Path objects. More...

`#include <gskmm/pathbuilder.h>`

## Public Member Functions
void | reference () const
| Increment the reference count for this object.
void | unreference () const
| Decrement the reference count for this object.
GskPathBuilder * | gobj ()
| Provides access to the underlying C instance.
const GskPathBuilder * | gobj () const
| Provides access to the underlying C instance.
GskPathBuilder * | gobj_copy () const
| Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.
| PathBuilder ()=delete
| PathBuilder (const PathBuilder &)=delete
PathBuilder & | operator= (const PathBuilder &)=delete
Glib::RefPtr< Path > | to_path ()
| Creates a new path from the given builder.
Gdk::Graphene::Point | get_current_point () const
| Gets the current point.
void | add_path (const Glib::RefPtr< const Path > & path)
| Appends all of path to the builder.
void | add_reverse_path (const Glib::RefPtr< const Path > & path)
| Appends all of path to the builder, in reverse order.
void | add_cairo_path (const Cairo::RefPtr< const Cairo::Path > & path)
| Adds a Cairo path to the builder.
void | add_layout (const Glib::RefPtr< const Pango::Layout > & layout)
| Adds the outlines for the glyphs in layout to the builder.
void | add_rect (const Gdk::Graphene::Rect & rect)
| Adds a rectangle as a new contour.
void | add_rounded_rect (const Gsk::RoundedRect & rect)
| Adds a rounded rectangle as a new contour.
void | add_circle (const Gdk::Graphene::Point & center, float radius)
| Adds a circle as a new contour.
void | add_segment (const Glib::RefPtr< const Path > & path, const PathPoint &start, const PathPoint &end)
| Adds a segment of a path to the builder.
void | move_to (float x, float y)
| Starts a new contour by placing the pen at x, y.
void | rel_move_to (float x, float y)
| Starts a new contour by placing the pen at x, y relative to the current point.
void | line_to (float x, float y)
| Draws a line from the current point to x, y and makes it the new current point.
void | rel_line_to (float x, float y)
| Draws a line from the current point to a point offset from it by x, y and makes it the new current point.
void | quad_to (float x1, float y1, float x2, float y2)
| Adds a quadratic Bézier curve from the current point to x2, y2 with x1, y1 as the control point.
void | rel_quad_to (float x1, float y1, float x2, float y2)
| Adds a quadratic Bézier curve from the current point to x2, y2 with x1, y1 the control point.
void | cubic_to (float x1, float y1, float x2, float y2, float x3, float y3)
| Adds a cubic Bézier curve from the current point to x3, y3 with x1, y1 and x2, y2 as the control points.
void | rel_cubic_to (float x1, float y1, float x2, float y2, float x3, float y3)
| Adds a cubic Bézier curve from the current point to x3, y3 with x1, y1 and x2, y2 as the control points.
void | conic_to (float x1, float y1, float x2, float y2, float weight)
| Adds a conic curve from the current point to x2, y2 with the given weight and x1, y1 as the control point.
void | rel_conic_to (float x1, float y1, float x2, float y2, float weight)
| Adds a conic curve from the current point to x2, y2 with the given weight and x1, y1 as the control point.
void | arc_to (float x1, float y1, float x2, float y2)
| Adds an elliptical arc from the current point to x2, y2 with x1, y1 determining the tangent directions.
void | rel_arc_to (float x1, float y1, float x2, float y2)
| Adds an elliptical arc from the current point to x2, y2 with x1, y1 determining the tangent directions.
void | svg_arc_to (float rx, float ry, float x_axis_rotation, bool large_arc, bool positive_sweep, float x, float y)
| Implements arc-to according to the SVG spec.
void | rel_svg_arc_to (float rx, float ry, float x_axis_rotation, bool large_arc, bool positive_sweep, float x, float y)
| Implements arc-to according to the SVG spec.
void | html_arc_to (float x1, float y1, float x2, float y2, float radius)
| Implements arc-to according to the HTML Canvas spec.
void | rel_html_arc_to (float x1, float y1, float x2, float y2, float radius)
| Implements arc-to according to the HTML Canvas spec.
void | close ()
| Ends the current contour with a line back to the start point.

## Static Public Member Functions
static Glib::RefPtr< PathBuilder > | create ()

## Protected Member Functions
void | operator delete (void *, std::size_t)

## Related Symbols
(Note that these are not member symbols.)
Glib::RefPtr< Gsk::PathBuilder > | wrap (GskPathBuilder * object, bool take_copy=false)
| A Glib::wrap() method for this object.

## Detailed Description

Constructs Gsk::Path objects.

Adding contours to the path can be done in two ways. The easiest option is to use the add_* group of functions that add predefined contours to the current path, either common shapes like add_circle() or by adding from other paths like add_path().

The 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 * _to group of functions. You start with a call to 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 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 Gsk::PathBuilder will reduce the degree of added Bézier curves as much as possible, to simplify rendering.

Since gtkmm 4.24

## Constructor & Destructor Documentation

## ◆ PathBuilder() [1/2]

Gsk::PathBuilder::PathBuilder | ( |  | ) |
| delete

## ◆ PathBuilder() [2/2]

Gsk::PathBuilder::PathBuilder | ( | const PathBuilder & |  | ) |
| delete

## Member Function Documentation

## ◆ add_cairo_path()

void Gsk::PathBuilder::add_cairo_path | ( | const Cairo::RefPtr< const Cairo::Path > & | path | ) |

Adds a Cairo path to the builder.

You can use cairo_copy_path() to access the path from a Cairo context.

Since gtkmm 4.24

Parameters

  path | A path.

## ◆ add_circle()

void Gsk::PathBuilder::add_circle | ( | const Gdk::Graphene::Point & | center,
|  | float | radius )

Adds a circle as a new contour.

The path is going around the circle in clockwise direction.

If radius is zero, the contour will be a closed point.

Since gtkmm 4.24

Parameters

  center | The center of the circle.
  radius | The radius of the circle.

## ◆ add_layout()

void Gsk::PathBuilder::add_layout | ( | const Glib::RefPtr< const Pango::Layout > & | layout | ) |

Adds the outlines for the glyphs in layout to the builder.

Since gtkmm 4.24

Parameters

  layout | The pango layout to add.

## ◆ add_path()

void Gsk::PathBuilder::add_path | ( | const Glib::RefPtr< const Path > & | path | ) |

Appends all of path to the builder.

Since gtkmm 4.24

Parameters

  path | The path to append.

## ◆ add_rect()

void Gsk::PathBuilder::add_rect | ( | const Gdk::Graphene::Rect & | rect | ) |

Adds a rectangle as a new contour.

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.

Since gtkmm 4.24

Parameters

  rect | The rectangle to create a path for.

## ◆ add_reverse_path()

void Gsk::PathBuilder::add_reverse_path | ( | const Glib::RefPtr< const Path > & | path | ) |

Appends all of path to the builder, in reverse order.

Since gtkmm 4.24

Parameters

  path | The path to append.

## ◆ add_rounded_rect()

void Gsk::PathBuilder::add_rounded_rect | ( | const Gsk::RoundedRect & | rect | ) |

Adds a rounded rectangle as a new contour.

The path is going around the rectangle in clockwise direction.

Since gtkmm 4.24

Parameters

  rect | The rounded rect.

## ◆ add_segment()

void Gsk::PathBuilder::add_segment | ( | const Glib::RefPtr< const Path > & | path,
|  | const PathPoint & | start,
|  | const PathPoint & | end )

Adds a segment of a path to the builder.

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 add_path().

Since gtkmm 4.24

Parameters

  path | The path to take the segment to.
  start | The point on path to start at.
  end | The point on path to end at.

## ◆ arc_to()

void Gsk::PathBuilder::arc_to | ( | float | x1,
|  | float | y1,
|  | float | x2,
|  | float | y2 )

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 conic_to() or svg_arc_to().

<picture> <source srcset="arc-dark.png" media="(prefers-color-scheme: dark)"> </picture>

Since gtkmm 4.24

Parameters

  x1 | X coordinate of first control point.
  y1 | Y coordinate of first control point.
  x2 | X coordinate of second control point.
  y2 | Y coordinate of second control point.

## ◆ close()

void Gsk::PathBuilder::close | ( |  | ) |

Ends the current contour with a line back to the start point.

Note that this is different from calling 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.

Since gtkmm 4.24

## ◆ conic_to()

void Gsk::PathBuilder::conic_to | ( | float | x1,
|  | float | y1,
|  | float | x2,
|  | float | y2,
|  | float | weight )

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.

<picture> <source srcset="conic-dark.png" media="(prefers-color-scheme: dark)"> </picture>

Since gtkmm 4.24

Parameters

  x1 | X coordinate of control point.
  y1 | Y coordinate of control point.
  x2 | X coordinate of the end of the curve.
  y2 | Y coordinate of the end of the curve.
  weight | Weight of the control point, must be greater than zero.

## ◆ create()

Glib::RefPtr< PathBuilder > Gsk::PathBuilder::create | ( |  | ) |
| static

## ◆ cubic_to()

void Gsk::PathBuilder::cubic_to | ( | float | x1,
|  | float | y1,
|  | float | x2,
|  | float | y2,
|  | float | x3,
|  | float | y3 )

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.

<picture> <source srcset="cubic-dark.png" media="(prefers-color-scheme: dark)"> </picture>

Since gtkmm 4.24

Parameters

  x1 | X coordinate of first control point.
  y1 | Y coordinate of first control point.
  x2 | X coordinate of second control point.
  y2 | Y coordinate of second control point.
  x3 | X coordinate of the end of the curve.
  y3 | Y coordinate of the end of the curve.

## ◆ get_current_point()

Gdk::Graphene::Point Gsk::PathBuilder::get_current_point | ( |  | ) | const

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.

Since gtkmm 4.24

Returns
  The current point.

## ◆ gobj() [1/2]

GskPathBuilder * Gsk::PathBuilder::gobj | ( |  | ) |

Provides access to the underlying C instance.

## ◆ gobj() [2/2]

const GskPathBuilder * Gsk::PathBuilder::gobj | ( |  | ) | const

Provides access to the underlying C instance.

## ◆ gobj_copy()

GskPathBuilder * Gsk::PathBuilder::gobj_copy | ( |  | ) | const

Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.

## ◆ html_arc_to()

void Gsk::PathBuilder::html_arc_to | ( | float | x1,
|  | float | y1,
|  | float | x2,
|  | float | y2,
|  | float | radius )

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.

Since gtkmm 4.24

Parameters

  x1 | X coordinate of first control point.
  y1 | Y coordinate of first control point.
  x2 | X coordinate of second control point.
  y2 | Y coordinate of second control point.
  radius | Radius of the circle.

## ◆ line_to()

void Gsk::PathBuilder::line_to | ( | float | x,
|  | float | y )

Draws a line from the current point to x, y and makes it the new current point.

<picture> <source srcset="line-dark.png" media="(prefers-color-scheme: dark)"> </picture>

Since gtkmm 4.24

Parameters

  x | X coordinate.
  y | Y coordinate.

## ◆ move_to()

void Gsk::PathBuilder::move_to | ( | float | x,
|  | float | y )

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.

Since gtkmm 4.24

Parameters

  x | X coordinate.
  y | Y coordinate.

## ◆ operator delete()

void Gsk::PathBuilder::operator delete | ( | void * | ,
|  | std::size_t | )
| protected

## ◆ operator=()

PathBuilder & Gsk::PathBuilder::operator= | ( | const PathBuilder & |  | ) |
| delete

## ◆ quad_to()

void Gsk::PathBuilder::quad_to | ( | float | x1,
|  | float | y1,
|  | float | x2,
|  | float | y2 )

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.

<picture> <source srcset="quad-dark.png" media="(prefers-color-scheme: dark)"> </picture>

Since gtkmm 4.24

Parameters

  x1 | X coordinate of control point.
  y1 | Y coordinate of control point.
  x2 | X coordinate of the end of the curve.
  y2 | Y coordinate of the end of the curve.

## ◆ reference()

void Gsk::PathBuilder::reference | ( |  | ) | const

Increment the reference count for this object.

You should never need to do this manually - use the object via a RefPtr instead.

## ◆ rel_arc_to()

void Gsk::PathBuilder::rel_arc_to | ( | float | x1,
|  | float | y1,
|  | float | x2,
|  | float | y2 )

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 arc_to().

Since gtkmm 4.24

Parameters

  x1 | X coordinate of first control point.
  y1 | Y coordinate of first control point.
  x2 | X coordinate of second control point.
  y2 | Y coordinate of second control point.

## ◆ rel_conic_to()

void Gsk::PathBuilder::rel_conic_to | ( | float | x1,
|  | float | y1,
|  | float | x2,
|  | float | y2,
|  | float | weight )

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 conic_to().

Since gtkmm 4.24

Parameters

  x1 | X offset of control point.
  y1 | Y offset of control point.
  x2 | X offset of the end of the curve.
  y2 | Y offset of the end of the curve.
  weight | Weight of the curve, must be greater than zero.

## ◆ rel_cubic_to()

void Gsk::PathBuilder::rel_cubic_to | ( | float | x1,
|  | float | y1,
|  | float | x2,
|  | float | y2,
|  | float | x3,
|  | float | y3 )

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 cubic_to().

Since gtkmm 4.24

Parameters

  x1 | X offset of first control point.
  y1 | Y offset of first control point.
  x2 | X offset of second control point.
  y2 | Y offset of second control point.
  x3 | X offset of the end of the curve.
  y3 | Y offset of the end of the curve.

## ◆ rel_html_arc_to()

void Gsk::PathBuilder::rel_html_arc_to | ( | float | x1,
|  | float | y1,
|  | float | x2,
|  | float | y2,
|  | float | radius )

Implements arc-to according to the HTML Canvas spec.

All coordinates are given relative to the current point.

This is the relative version of html_arc_to().

Since gtkmm 4.24

Parameters

  x1 | X coordinate of first control point.
  y1 | Y coordinate of first control point.
  x2 | X coordinate of second control point.
  y2 | Y coordinate of second control point.
  radius | Radius of the circle.

## ◆ rel_line_to()

void Gsk::PathBuilder::rel_line_to | ( | float | x,
|  | float | y )

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 line_to().

Since gtkmm 4.24

Parameters

  x | X offset.
  y | Y offset.

## ◆ rel_move_to()

void Gsk::PathBuilder::rel_move_to | ( | float | x,
|  | float | y )

Starts a new contour by placing the pen at x, y relative to the current point.

This is the relative version of move_to().

Since gtkmm 4.24

Parameters

  x | X offset.
  y | Y offset.

## ◆ rel_quad_to()

void Gsk::PathBuilder::rel_quad_to | ( | float | x1,
|  | float | y1,
|  | float | x2,
|  | float | y2 )

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 quad_to().

Since gtkmm 4.24

Parameters

  x1 | X offset of control point.
  y1 | Y offset of control point.
  x2 | X offset of the end of the curve.
  y2 | Y offset of the end of the curve.

## ◆ rel_svg_arc_to()

void Gsk::PathBuilder::rel_svg_arc_to | ( | float | rx,
|  | float | ry,
|  | float | x_axis_rotation,
|  | bool | large_arc,
|  | bool | positive_sweep,
|  | float | x,
|  | float | y )

Implements arc-to according to the SVG spec.

All coordinates are given relative to the current point.

This is the relative version of svg_arc_to().

Since gtkmm 4.24

Parameters

  rx | X radius.
  ry | Y radius.
  x_axis_rotation | The rotation of the ellipsis.
  large_arc | Whether to add the large arc.
  positive_sweep | Whether to sweep in the positive direction.
  x | X coordinate of the endpoint.
  y | Y coordinate of the endpoint.

## ◆ svg_arc_to()

void Gsk::PathBuilder::svg_arc_to | ( | float | rx,
|  | float | ry,
|  | float | x_axis_rotation,
|  | bool | large_arc,
|  | bool | positive_sweep,
|  | float | x,
|  | float | y )

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.

Since gtkmm 4.24

Parameters

  rx | X radius.
  ry | Y radius.
  x_axis_rotation | The rotation of the ellipsis.
  large_arc | Whether to add the large arc.
  positive_sweep | Whether to sweep in the positive direction.
  x | X coordinate of the endpoint.
  y | Y coordinate of the endpoint.

## ◆ to_path()

Glib::RefPtr< Path > Gsk::PathBuilder::to_path | ( |  | ) |

Creates a new path from the given builder.

The given Gsk::PathBuilder is reset to the initial state once this function returns. Calling this function again on the same builder instance will therefore produce an empty path, not a copy of the same path.

This function is intended primarily for language bindings. C code should use free_to_path().

Since gtkmm 4.24

Returns
  The newly created path with all the contours added to the builder.

## ◆ unreference()

void Gsk::PathBuilder::unreference | ( |  | ) | const

Decrement the reference count for this object.

You should never need to do this manually - use the object via a RefPtr instead.

## Friends And Related Symbol Documentation

## ◆ wrap()

Glib::RefPtr< Gsk::PathBuilder > wrap | ( | GskPathBuilder * | object,
|  | bool | take_copy = false )
| related

A Glib::wrap() method for this object.

Parameters

  object | The C instance.
  take_copy | False if the result should take ownership of the C instance. True if it should take a new copy or ref.

Returns
  A C++ instance that wraps this C instance.