gsk4/auto/
path_builder.rs

Help
1// This file was generated by gir (https://github.com/gtk-rs/gir)
2// from gir-files (https://github.com/gtk-rs/gir-files)
3// DO NOT EDIT
4
5use crate::{ffi, Path, PathPoint, RoundedRect};
6use glib::translate::*;
7
8glib::wrapper! {
9    /// Constructs [`Path`][crate::Path] objects.
10    ///
11    /// A path is constructed like this:
12    ///
13    /// **⚠️ The following code is in c ⚠️**
14    ///
15    /// ```c
16    /// GskPath *
17    /// construct_path (void)
18    /// {
19    ///   GskPathBuilder *builder;
20    ///
21    ///   builder = gsk_path_builder_new ();
22    ///
23    ///   // add contours to the path here
24    ///
25    ///   return gsk_path_builder_free_to_path (builder);
26    /// ```
27    ///
28    /// Adding contours to the path can be done in two ways.
29    /// The easiest option is to use the `gsk_path_builder_add_*` group
30    /// of functions that add predefined contours to the current path,
31    /// either common shapes like [`add_circle()`][Self::add_circle()]
32    /// or by adding from other paths like [`add_path()`][Self::add_path()].
33    ///
34    /// The `gsk_path_builder_add_*` methods always add complete contours,
35    /// and do not use or modify the current point.
36    ///
37    /// The other option is to define each line and curve manually with
38    /// the `gsk_path_builder_*_to` group of functions. You start with
39    /// a call to [`move_to()`][Self::move_to()] to set the starting point
40    /// and then use multiple calls to any of the drawing functions to
41    /// move the pen along the plane. Once you are done, you can call
42    /// [`close()`][Self::close()] to close the path by connecting it
43    /// back with a line to the starting point.
44    ///
45    /// This is similar to how paths are drawn in Cairo.
46    ///
47    /// Note that [`PathBuilder`][crate::PathBuilder] will reduce the degree of added Bézier
48    /// curves as much as possible, to simplify rendering.
49    #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
50    pub struct PathBuilder(Shared<ffi::GskPathBuilder>);
51
52    match fn {
53        ref => |ptr| ffi::gsk_path_builder_ref(ptr),
54        unref => |ptr| ffi::gsk_path_builder_unref(ptr),
55        type_ => || ffi::gsk_path_builder_get_type(),
56    }
57}
58
59impl PathBuilder {
60    /// Create a new [`PathBuilder`][crate::PathBuilder] object.
61    ///
62    /// The resulting builder would create an empty [`Path`][crate::Path].
63    /// Use addition functions to add types to it.
64    ///
65    /// # Returns
66    ///
67    /// a new [`PathBuilder`][crate::PathBuilder]
68    #[doc(alias = "gsk_path_builder_new")]
69    pub fn new() -> PathBuilder {
70        assert_initialized_main_thread!();
71        unsafe { from_glib_full(ffi::gsk_path_builder_new()) }
72    }
73
74    /// Adds a circle as a new contour.
75    ///
76    /// The path is going around the circle in clockwise direction.
77    ///
78    /// If @radius is zero, the contour will be a closed point.
79    /// ## `center`
80    /// the center of the circle
81    /// ## `radius`
82    /// the radius of the circle
83    #[doc(alias = "gsk_path_builder_add_circle")]
84    pub fn add_circle(&self, center: &graphene::Point, radius: f32) {
85        unsafe {
86            ffi::gsk_path_builder_add_circle(
87                self.to_glib_none().0,
88                center.to_glib_none().0,
89                radius,
90            );
91        }
92    }
93
94    /// Adds the outlines for the glyphs in @layout to the builder.
95    /// ## `layout`
96    /// the pango layout to add
97    #[doc(alias = "gsk_path_builder_add_layout")]
98    pub fn add_layout(&self, layout: &pango::Layout) {
99        unsafe {
100            ffi::gsk_path_builder_add_layout(self.to_glib_none().0, layout.to_glib_none().0);
101        }
102    }
103
104    /// Appends all of @path to the builder.
105    /// ## `path`
106    /// the path to append
107    #[doc(alias = "gsk_path_builder_add_path")]
108    pub fn add_path(&self, path: &Path) {
109        unsafe {
110            ffi::gsk_path_builder_add_path(self.to_glib_none().0, path.to_glib_none().0);
111        }
112    }
113
114    /// Adds a rectangle as a new contour.
115    ///
116    /// The path is going around the rectangle in clockwise direction.
117    ///
118    /// If the the width or height are 0, the path will be a closed
119    /// horizontal or vertical line. If both are 0, it'll be a closed dot.
120    /// ## `rect`
121    /// the rectangle to create a path for
122    #[doc(alias = "gsk_path_builder_add_rect")]
123    pub fn add_rect(&self, rect: &graphene::Rect) {
124        unsafe {
125            ffi::gsk_path_builder_add_rect(self.to_glib_none().0, rect.to_glib_none().0);
126        }
127    }
128
129    /// Appends all of @path to the builder, in reverse order.
130    /// ## `path`
131    /// the path to append
132    #[doc(alias = "gsk_path_builder_add_reverse_path")]
133    pub fn add_reverse_path(&self, path: &Path) {
134        unsafe {
135            ffi::gsk_path_builder_add_reverse_path(self.to_glib_none().0, path.to_glib_none().0);
136        }
137    }
138
139    /// Adds a rounded rectangle as a new contour.
140    ///
141    /// The path is going around the rectangle in clockwise direction.
142    /// ## `rect`
143    /// the rounded rect
144    #[doc(alias = "gsk_path_builder_add_rounded_rect")]
145    pub fn add_rounded_rect(&self, rect: &RoundedRect) {
146        unsafe {
147            ffi::gsk_path_builder_add_rounded_rect(self.to_glib_none().0, rect.to_glib_none().0);
148        }
149    }
150
151    /// Adds a segment of a path to the builder.
152    ///
153    /// If @start is equal to or after @end, the path will first add the
154    /// segment from @start to the end of the path, and then add the segment
155    /// from the beginning to @end. If the path is closed, these segments
156    /// will be connected.
157    ///
158    /// Note that this method always adds a path with the given start point
159    /// and end point. To add a closed path, use [`add_path()`][Self::add_path()].
160    /// ## `path`
161    /// the path to take the segment to
162    /// ## `start`
163    /// the point on @path to start at
164    /// ## `end`
165    /// the point on @path to end at
166    #[doc(alias = "gsk_path_builder_add_segment")]
167    pub fn add_segment(&self, path: &Path, start: &PathPoint, end: &PathPoint) {
168        unsafe {
169            ffi::gsk_path_builder_add_segment(
170                self.to_glib_none().0,
171                path.to_glib_none().0,
172                start.to_glib_none().0,
173                end.to_glib_none().0,
174            );
175        }
176    }
177
178    /// Adds an elliptical arc from the current point to @x2, @y2
179    /// with @x1, @y1 determining the tangent directions.
180    ///
181    /// After this, @x2, @y2 will be the new current point.
182    ///
183    /// Note: Two points and their tangents do not determine
184    /// a unique ellipse, so GSK just picks one. If you need more
185    /// precise control, use [`conic_to()`][Self::conic_to()]
186    /// or [`svg_arc_to()`][Self::svg_arc_to()].
187    ///
188    /// <picture>
189    ///   <source srcset="arc-dark.png" media="(prefers-color-scheme: dark)">
190    ///   <img alt="Arc To" src="arc-light.png">
191    /// </picture>
192    /// ## `x1`
193    /// x coordinate of first control point
194    /// ## `y1`
195    /// y coordinate of first control point
196    /// ## `x2`
197    /// x coordinate of second control point
198    /// ## `y2`
199    /// y coordinate of second control point
200    #[doc(alias = "gsk_path_builder_arc_to")]
201    pub fn arc_to(&self, x1: f32, y1: f32, x2: f32, y2: f32) {
202        unsafe {
203            ffi::gsk_path_builder_arc_to(self.to_glib_none().0, x1, y1, x2, y2);
204        }
205    }
206
207    /// Ends the current contour with a line back to the start point.
208    ///
209    /// Note that this is different from calling [`line_to()`][Self::line_to()]
210    /// with the start point in that the contour will be closed. A closed
211    /// contour behaves differently from an open one. When stroking, its
212    /// start and end point are considered connected, so they will be
213    /// joined via the line join, and not ended with line caps.
214    #[doc(alias = "gsk_path_builder_close")]
215    pub fn close(&self) {
216        unsafe {
217            ffi::gsk_path_builder_close(self.to_glib_none().0);
218        }
219    }
220
221    /// Adds a [conic curve](https://en.wikipedia.org/wiki/Non-uniform_rational_B-spline)
222    /// from the current point to @x2, @y2 with the given @weight and @x1, @y1 as the
223    /// control point.
224    ///
225    /// The weight determines how strongly the curve is pulled towards the control point.
226    /// A conic with weight 1 is identical to a quadratic Bézier curve with the same points.
227    ///
228    /// Conic curves can be used to draw ellipses and circles. They are also known as
229    /// rational quadratic Bézier curves.
230    ///
231    /// After this, @x2, @y2 will be the new current point.
232    ///
233    /// <picture>
234    ///   <source srcset="conic-dark.png" media="(prefers-color-scheme: dark)">
235    ///   <img alt="Conic To" src="conic-light.png">
236    /// </picture>
237    /// ## `x1`
238    /// x coordinate of control point
239    /// ## `y1`
240    /// y coordinate of control point
241    /// ## `x2`
242    /// x coordinate of the end of the curve
243    /// ## `y2`
244    /// y coordinate of the end of the curve
245    /// ## `weight`
246    /// weight of the control point, must be greater than zero
247    #[doc(alias = "gsk_path_builder_conic_to")]
248    pub fn conic_to(&self, x1: f32, y1: f32, x2: f32, y2: f32, weight: f32) {
249        unsafe {
250            ffi::gsk_path_builder_conic_to(self.to_glib_none().0, x1, y1, x2, y2, weight);
251        }
252    }
253
254    /// Adds a [cubic Bézier curve](https://en.wikipedia.org/wiki/B`C3``A9zier_curve`)
255    /// from the current point to @x3, @y3 with @x1, @y1 and @x2, @y2 as the control
256    /// points.
257    ///
258    /// After this, @x3, @y3 will be the new current point.
259    ///
260    /// <picture>
261    ///   <source srcset="cubic-dark.png" media="(prefers-color-scheme: dark)">
262    ///   <img alt="Cubic To" src="cubic-light.png">
263    /// </picture>
264    /// ## `x1`
265    /// x coordinate of first control point
266    /// ## `y1`
267    /// y coordinate of first control point
268    /// ## `x2`
269    /// x coordinate of second control point
270    /// ## `y2`
271    /// y coordinate of second control point
272    /// ## `x3`
273    /// x coordinate of the end of the curve
274    /// ## `y3`
275    /// y coordinate of the end of the curve
276    #[doc(alias = "gsk_path_builder_cubic_to")]
277    pub fn cubic_to(&self, x1: f32, y1: f32, x2: f32, y2: f32, x3: f32, y3: f32) {
278        unsafe {
279            ffi::gsk_path_builder_cubic_to(self.to_glib_none().0, x1, y1, x2, y2, x3, y3);
280        }
281    }
282
283    /// Gets the current point.
284    ///
285    /// The current point is used for relative drawing commands and
286    /// updated after every operation.
287    ///
288    /// When the builder is created, the default current point is set
289    /// to `0, 0`. Note that this is different from cairo, which starts
290    /// out without a current point.
291    ///
292    /// # Returns
293    ///
294    /// the current point
295    #[doc(alias = "gsk_path_builder_get_current_point")]
296    #[doc(alias = "get_current_point")]
297    pub fn current_point(&self) -> graphene::Point {
298        unsafe {
299            from_glib_none(ffi::gsk_path_builder_get_current_point(
300                self.to_glib_none().0,
301            ))
302        }
303    }
304
305    /// Implements arc-to according to the HTML Canvas spec.
306    ///
307    /// A convenience function that implements the
308    /// [HTML arc_to](https://html.spec.whatwg.org/multipage/canvas.html#dom-context-2d-arcto-dev)
309    /// functionality.
310    ///
311    /// After this, the current point will be the point where
312    /// the circle with the given radius touches the line from
313    /// @x1, @y1 to @x2, @y2.
314    /// ## `x1`
315    /// x coordinate of first control point
316    /// ## `y1`
317    /// y coordinate of first control point
318    /// ## `x2`
319    /// x coordinate of second control point
320    /// ## `y2`
321    /// y coordinate of second control point
322    /// ## `radius`
323    /// radius of the circle
324    #[doc(alias = "gsk_path_builder_html_arc_to")]
325    pub fn html_arc_to(&self, x1: f32, y1: f32, x2: f32, y2: f32, radius: f32) {
326        unsafe {
327            ffi::gsk_path_builder_html_arc_to(self.to_glib_none().0, x1, y1, x2, y2, radius);
328        }
329    }
330
331    /// Draws a line from the current point to @x, @y and makes it
332    /// the new current point.
333    ///
334    /// <picture>
335    ///   <source srcset="line-dark.png" media="(prefers-color-scheme: dark)">
336    ///   <img alt="Line To" src="line-light.png">
337    /// </picture>
338    /// ## `x`
339    /// x coordinate
340    /// ## `y`
341    /// y coordinate
342    #[doc(alias = "gsk_path_builder_line_to")]
343    pub fn line_to(&self, x: f32, y: f32) {
344        unsafe {
345            ffi::gsk_path_builder_line_to(self.to_glib_none().0, x, y);
346        }
347    }
348
349    /// Starts a new contour by placing the pen at @x, @y.
350    ///
351    /// If this function is called twice in succession, the first
352    /// call will result in a contour made up of a single point.
353    /// The second call will start a new contour.
354    /// ## `x`
355    /// x coordinate
356    /// ## `y`
357    /// y coordinate
358    #[doc(alias = "gsk_path_builder_move_to")]
359    pub fn move_to(&self, x: f32, y: f32) {
360        unsafe {
361            ffi::gsk_path_builder_move_to(self.to_glib_none().0, x, y);
362        }
363    }
364
365    /// Adds a [quadratic Bézier curve](https://en.wikipedia.org/wiki/B`C3``A9zier_curve`)
366    /// from the current point to @x2, @y2 with @x1, @y1 as the control point.
367    ///
368    /// After this, @x2, @y2 will be the new current point.
369    ///
370    /// <picture>
371    ///   <source srcset="quad-dark.png" media="(prefers-color-scheme: dark)">
372    ///   <img alt="Quad To" src="quad-light.png">
373    /// </picture>
374    /// ## `x1`
375    /// x coordinate of control point
376    /// ## `y1`
377    /// y coordinate of control point
378    /// ## `x2`
379    /// x coordinate of the end of the curve
380    /// ## `y2`
381    /// y coordinate of the end of the curve
382    #[doc(alias = "gsk_path_builder_quad_to")]
383    pub fn quad_to(&self, x1: f32, y1: f32, x2: f32, y2: f32) {
384        unsafe {
385            ffi::gsk_path_builder_quad_to(self.to_glib_none().0, x1, y1, x2, y2);
386        }
387    }
388
389    /// Adds an elliptical arc from the current point to @x2, @y2
390    /// with @x1, @y1 determining the tangent directions.
391    ///
392    /// All coordinates are given relative to the current point.
393    ///
394    /// This is the relative version of [`arc_to()`][Self::arc_to()].
395    /// ## `x1`
396    /// x coordinate of first control point
397    /// ## `y1`
398    /// y coordinate of first control point
399    /// ## `x2`
400    /// x coordinate of second control point
401    /// ## `y2`
402    /// y coordinate of second control point
403    #[doc(alias = "gsk_path_builder_rel_arc_to")]
404    pub fn rel_arc_to(&self, x1: f32, y1: f32, x2: f32, y2: f32) {
405        unsafe {
406            ffi::gsk_path_builder_rel_arc_to(self.to_glib_none().0, x1, y1, x2, y2);
407        }
408    }
409
410    /// Adds a [conic curve](https://en.wikipedia.org/wiki/Non-uniform_rational_B-spline)
411    /// from the current point to @x2, @y2 with the given @weight and @x1, @y1 as the
412    /// control point.
413    ///
414    /// All coordinates are given relative to the current point.
415    ///
416    /// This is the relative version of [`conic_to()`][Self::conic_to()].
417    /// ## `x1`
418    /// x offset of control point
419    /// ## `y1`
420    /// y offset of control point
421    /// ## `x2`
422    /// x offset of the end of the curve
423    /// ## `y2`
424    /// y offset of the end of the curve
425    /// ## `weight`
426    /// weight of the curve, must be greater than zero
427    #[doc(alias = "gsk_path_builder_rel_conic_to")]
428    pub fn rel_conic_to(&self, x1: f32, y1: f32, x2: f32, y2: f32, weight: f32) {
429        unsafe {
430            ffi::gsk_path_builder_rel_conic_to(self.to_glib_none().0, x1, y1, x2, y2, weight);
431        }
432    }
433
434    /// Adds a [cubic Bézier curve](https://en.wikipedia.org/wiki/B`C3``A9zier_curve`)
435    /// from the current point to @x3, @y3 with @x1, @y1 and @x2, @y2 as the control
436    /// points.
437    ///
438    /// All coordinates are given relative to the current point.
439    ///
440    /// This is the relative version of [`cubic_to()`][Self::cubic_to()].
441    /// ## `x1`
442    /// x offset of first control point
443    /// ## `y1`
444    /// y offset of first control point
445    /// ## `x2`
446    /// x offset of second control point
447    /// ## `y2`
448    /// y offset of second control point
449    /// ## `x3`
450    /// x offset of the end of the curve
451    /// ## `y3`
452    /// y offset of the end of the curve
453    #[doc(alias = "gsk_path_builder_rel_cubic_to")]
454    pub fn rel_cubic_to(&self, x1: f32, y1: f32, x2: f32, y2: f32, x3: f32, y3: f32) {
455        unsafe {
456            ffi::gsk_path_builder_rel_cubic_to(self.to_glib_none().0, x1, y1, x2, y2, x3, y3);
457        }
458    }
459
460    /// Implements arc-to according to the HTML Canvas spec.
461    ///
462    /// All coordinates are given relative to the current point.
463    ///
464    /// This is the relative version of [`html_arc_to()`][Self::html_arc_to()].
465    /// ## `x1`
466    /// x coordinate of first control point
467    /// ## `y1`
468    /// y coordinate of first control point
469    /// ## `x2`
470    /// x coordinate of second control point
471    /// ## `y2`
472    /// y coordinate of second control point
473    /// ## `radius`
474    /// radius of the circle
475    #[doc(alias = "gsk_path_builder_rel_html_arc_to")]
476    pub fn rel_html_arc_to(&self, x1: f32, y1: f32, x2: f32, y2: f32, radius: f32) {
477        unsafe {
478            ffi::gsk_path_builder_rel_html_arc_to(self.to_glib_none().0, x1, y1, x2, y2, radius);
479        }
480    }
481
482    /// Draws a line from the current point to a point offset from it
483    /// by @x, @y and makes it the new current point.
484    ///
485    /// This is the relative version of [`line_to()`][Self::line_to()].
486    /// ## `x`
487    /// x offset
488    /// ## `y`
489    /// y offset
490    #[doc(alias = "gsk_path_builder_rel_line_to")]
491    pub fn rel_line_to(&self, x: f32, y: f32) {
492        unsafe {
493            ffi::gsk_path_builder_rel_line_to(self.to_glib_none().0, x, y);
494        }
495    }
496
497    /// Starts a new contour by placing the pen at @x, @y
498    /// relative to the current point.
499    ///
500    /// This is the relative version of [`move_to()`][Self::move_to()].
501    /// ## `x`
502    /// x offset
503    /// ## `y`
504    /// y offset
505    #[doc(alias = "gsk_path_builder_rel_move_to")]
506    pub fn rel_move_to(&self, x: f32, y: f32) {
507        unsafe {
508            ffi::gsk_path_builder_rel_move_to(self.to_glib_none().0, x, y);
509        }
510    }
511
512    /// Adds a [quadratic Bézier curve](https://en.wikipedia.org/wiki/B`C3``A9zier_curve`)
513    /// from the current point to @x2, @y2 with @x1, @y1 the control point.
514    ///
515    /// All coordinates are given relative to the current point.
516    ///
517    /// This is the relative version of [`quad_to()`][Self::quad_to()].
518    /// ## `x1`
519    /// x offset of control point
520    /// ## `y1`
521    /// y offset of control point
522    /// ## `x2`
523    /// x offset of the end of the curve
524    /// ## `y2`
525    /// y offset of the end of the curve
526    #[doc(alias = "gsk_path_builder_rel_quad_to")]
527    pub fn rel_quad_to(&self, x1: f32, y1: f32, x2: f32, y2: f32) {
528        unsafe {
529            ffi::gsk_path_builder_rel_quad_to(self.to_glib_none().0, x1, y1, x2, y2);
530        }
531    }
532
533    /// Implements arc-to according to the SVG spec.
534    ///
535    /// All coordinates are given relative to the current point.
536    ///
537    /// This is the relative version of [`svg_arc_to()`][Self::svg_arc_to()].
538    /// ## `rx`
539    /// x radius
540    /// ## `ry`
541    /// y radius
542    /// ## `x_axis_rotation`
543    /// the rotation of the ellipsis
544    /// ## `large_arc`
545    /// whether to add the large arc
546    /// ## `positive_sweep`
547    /// whether to sweep in the positive direction
548    /// ## `x`
549    /// x coordinate of the endpoint
550    /// ## `y`
551    /// y coordinate of the endpoint
552    #[doc(alias = "gsk_path_builder_rel_svg_arc_to")]
553    pub fn rel_svg_arc_to(
554        &self,
555        rx: f32,
556        ry: f32,
557        x_axis_rotation: f32,
558        large_arc: bool,
559        positive_sweep: bool,
560        x: f32,
561        y: f32,
562    ) {
563        unsafe {
564            ffi::gsk_path_builder_rel_svg_arc_to(
565                self.to_glib_none().0,
566                rx,
567                ry,
568                x_axis_rotation,
569                large_arc.into_glib(),
570                positive_sweep.into_glib(),
571                x,
572                y,
573            );
574        }
575    }
576
577    /// Implements arc-to according to the SVG spec.
578    ///
579    /// A convenience function that implements the
580    /// [SVG arc_to](https://www.w3.org/TR/SVG11/paths.html#PathDataEllipticalArcCommands)
581    /// functionality.
582    ///
583    /// After this, @x, @y will be the new current point.
584    /// ## `rx`
585    /// x radius
586    /// ## `ry`
587    /// y radius
588    /// ## `x_axis_rotation`
589    /// the rotation of the ellipsis
590    /// ## `large_arc`
591    /// whether to add the large arc
592    /// ## `positive_sweep`
593    /// whether to sweep in the positive direction
594    /// ## `x`
595    /// x coordinate of the endpoint
596    /// ## `y`
597    /// y coordinate of the endpoint
598    #[doc(alias = "gsk_path_builder_svg_arc_to")]
599    pub fn svg_arc_to(
600        &self,
601        rx: f32,
602        ry: f32,
603        x_axis_rotation: f32,
604        large_arc: bool,
605        positive_sweep: bool,
606        x: f32,
607        y: f32,
608    ) {
609        unsafe {
610            ffi::gsk_path_builder_svg_arc_to(
611                self.to_glib_none().0,
612                rx,
613                ry,
614                x_axis_rotation,
615                large_arc.into_glib(),
616                positive_sweep.into_glib(),
617                x,
618                y,
619            );
620        }
621    }
622
623    /// Creates a new path from the given builder.
624    ///
625    /// The given [`PathBuilder`][crate::PathBuilder] is reset once this function returns;
626    /// you cannot call this function multiple times on the same builder
627    /// instance.
628    ///
629    /// This function is intended primarily for language bindings.
630    /// C code should use `Gsk::PathBuilder::free_to_path()`.
631    ///
632    /// # Returns
633    ///
634    /// the newly created path
635    ///   with all the contours added to the builder
636    #[doc(alias = "gsk_path_builder_to_path")]
637    pub fn to_path(&self) -> Path {
638        unsafe { from_glib_full(ffi::gsk_path_builder_to_path(self.to_glib_none().0)) }
639    }
640}
641
642#[cfg(feature = "v4_14")]
643#[cfg_attr(docsrs, doc(cfg(feature = "v4_14")))]
644impl Default for PathBuilder {
645    fn default() -> Self {
646        Self::new()
647    }
648}
gsk4/auto/path_builder.rs

gsk4/auto/
path_builder.rs
