Lerking/gtk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Docs cleanup

Browse Source 
Rewrite the path docs for gi-docgen syntax.
This commit is contained in:
Matthias Clasen
2023-07-06 12:46:17 -04:00
parent 826efc4dff
commit bd9a93d549
6 changed files with 298 additions and 301 deletions
Download Patch File Download Diff File Expand all files Collapse all files

52
gsk/gskenums.h
View File

@@ -187,16 +187,19 @@ typedef enum {
* filled.
*
* #GskFillRule is used to select how paths are filled, for example in
* gsk_fill_node_new(). Whether or not a point is included in the fill is
* determined by taking a ray from that point to infinity and looking
* at intersections with the path. The ray can be in any direction,
* as long as it doesn't pass through the end point of a segment
* or have a tricky intersection such as intersecting tangent to the path.
* gsk_fill_node_new().
*
* Whether or not a point is included in the fill is determined by taking
* a ray from that point to infinity and looking at intersections with the
* path. The ray can be in any direction, as long as it doesn't pass through
* the end point of a segment or have a tricky intersection such as
* intersecting tangent to the path.
*
* (Note that filling is not actually implemented in this way. This
* is just a description of the rule that is applied.)
*
* New entries may be added in future versions.
**/
*/
typedef enum {
GSK_FILL_RULE_WINDING,
GSK_FILL_RULE_EVEN_ODD
@@ -205,11 +208,11 @@ typedef enum {
/**
* GskLineCap:
* @GSK_LINE_CAP_BUTT: Start and stop the line exactly at the start
* and end point
* and end point
* @GSK_LINE_CAP_ROUND: Use a round ending, the center of the circle
* is the start or end point.
* is the start or end point.
* @GSK_LINE_CAP_SQUARE: use squared ending, the center of the square
* is the start or end point.
* is the start or end point.
*
* Specifies how to render the start and end points of contours or
* dashes when stroking.
@@ -227,14 +230,14 @@ typedef enum {
* @GSK_LINE_JOIN_MITER: Use a sharp, angled corner
* @GSK_LINE_JOIN_MITER_CLIP: Use a sharp, angled corner, at a distance
* @GSK_LINE_JOIN_ROUND: Use a round join, the center of the circle is
* the joint point
* the joint point
* @GSK_LINE_JOIN_BEVEL: Use a cut-off join, the join is cut off at half
* the line width from the joint point
* the line width from the joint point
*
* Specifies how to render the junction of two lines when stroking.
*
* See gsk_stroke_set_miter_limit() for details on the difference between
* @GSK_LINE_JOIN_MITER and @GSK_LINE_JOIN_MITER_CLIP.
* See [method@Gsk.Stroke.set_miter_limit] for details on the difference
* between @GSK_LINE_JOIN_MITER and @GSK_LINE_JOIN_MITER_CLIP.
*
* The default line join style is %GSK_LINE_JOIN_MITER.
**/
@@ -248,18 +251,23 @@ typedef enum {
/**
* GskPathOperation:
* @GSK_PATH_MOVE: A move-to operation, with 1 point describing the
* target point.
* target point.
* @GSK_PATH_LINE: A line-to operation, with 2 points describing the
* start and end point of a straight line.
* start and end point of a straight line.
* @GSK_PATH_CLOSE: A close operation ending the current contour with
* a line back to the starting point. Two points describe the start
* and end of the line.
* a line back to the starting point. Two points describe the start
* and end of the line.
* @GSK_PATH_CUBIC: A curve-to operation describing a cubic Bézier curve
* with 4 points describing the start point, the two control points
* and the end point of the curve.
* a line back to the starting point. Two points describe the start
* and end of the line.
* @GSK_PATH_CURVE: A curve-to operation describing a cubic Bézier curve
* with 4 points describing the start point, the two control points
* and the end point of the curve.
* @GSK_PATH_CONIC: A weighted quadratic bezier curve with 3 points
* describing the start point, control point and end point of the
* curve. A weight for the curve will be passed, too.
* with 4 points describing the start point, the two control points
* and the end point of the curve.
* @GSK_PATH_CONIC: A weighted quadratic Bézier curve with 3 points
* describing the start point, control point and end point of the
* curve. A weight for the curve will be passed, too.
*
* Path operations can be used to approximate a #GskPath.
*

121
gsk/gskpath.c
View File

@@ -25,17 +25,16 @@
#include "gskpathbuilder.h"
/**
* SECTION:gskpath
* @Title: Path
* @Short_description: Lines and Curves
* @See_also: #GskRenderNode, #GskPathBuilder
* GskPath:
*
* This section describes the #GskPath structure that is used to
* describe lines and curves that are more complex than simple rectangles.
* A `GskPath` describes lines and curves that are more complex
* than simple rectangles.
*
* #GskPath is an immutable struct. After creation, you cannot change
* the types it represents. Instead, new #GskPath have to be created.
* The #GskPathBuilder structure is meant to help in this endeavor.
* `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 `GskPathBuilder` structure is meant to help in this endeavor.
*/
struct _GskPath
@@ -50,13 +49,6 @@ struct _GskPath
/* followed by the contours data */
};
/**
* GskPath:
*
* A #GskPath struct is a reference counted struct
* and should be treated as opaque.
*/
G_DEFINE_BOXED_TYPE (GskPath, gsk_path,
gsk_path_ref,
gsk_path_unref)
@@ -107,12 +99,12 @@ gsk_path_new_from_contours (const GSList *contours)
/**
* gsk_path_ref:
* @self: a #GskPath
* @self: a `GskPath`
*
* Increases the reference count of a #GskPath by one.
* Increases the reference count of a `GskPath` by one.
*
* Returns: the passed in #GskPath.
**/
* Returns: the passed in `GskPath`
*/
GskPath *
gsk_path_ref (GskPath *self)
{
@@ -125,11 +117,12 @@ gsk_path_ref (GskPath *self)
/**
* gsk_path_unref:
* @self: a #GskPath
* @self: a `GskPath`
*
* Decreases the reference count of a `GskPath` by one.
*
* Decreases the reference count of a #GskPath by one.
* If the resulting reference count is zero, frees the path.
**/
*/
void
gsk_path_unref (GskPath *self)
{
@@ -152,7 +145,7 @@ gsk_path_get_contour (GskPath *path,
/**
* gsk_path_print:
* @self: a #GskPath
* @self: a `GskPath`
* @string: The string to print into
*
* Converts @self into a human-readable string representation suitable
@@ -163,7 +156,7 @@ gsk_path_get_contour (GskPath *path,
* with the exception that conic curves will generate a string of the
* form "O x1 y1, x2 y2, w" where x1, y1 is the control point, x2, y2
* is the end point, and w is the weight.
**/
*/
void
gsk_path_print (GskPath *self,
GString *string)
@@ -183,17 +176,18 @@ gsk_path_print (GskPath *self,
/**
* gsk_path_to_string:
* @self: a #GskPath
* @self: a `GskPath`
*
* Converts the path into a string that is suitable for
* printing. You can use this function in a debugger to get a quick overview
* 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 gsk_path_print(), see that function
* for details.
* This is a wrapper around [method@Gsk.Path.print], see that
* function for details.
*
* Returns: A new string for @self
**/
*/
char *
gsk_path_to_string (GskPath *self)
{
@@ -244,18 +238,18 @@ gsk_path_to_cairo_add_op (GskPathOperation op,
/**
* gsk_path_to_cairo:
* @self: a #GskPath
* @self: a `GskPath`
* @cr: a cairo context
*
* Appends the given @path to the given cairo context for drawing
* with Cairo.
*
* This may cause some suboptimal conversions to be performed as Cairo
* may not support all features of #GskPath.
* 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.
**/
*/
void
gsk_path_to_cairo (GskPath *self,
cairo_t *cr)
@@ -270,14 +264,14 @@ gsk_path_to_cairo (GskPath *self,
cr);
}
/*
/*< private >*
* gsk_path_get_n_contours:
* @path: a #GskPath
* @path: a `GskPath`
*
* Gets the number of contours @path is composed out of.
*
* Returns: the number of contours in @path
**/
*/
gsize
gsk_path_get_n_contours (GskPath *path)
{
@@ -286,12 +280,12 @@ gsk_path_get_n_contours (GskPath *path)
/**
* gsk_path_is_empty:
* @self: a #GskPath
* @self: a `GskPath`
*
* Checks if the path is empty, i.e. contains no lines or curves.
*
* Returns: %TRUE if the path is empty
**/
* Returns: `TRUE` if the path is empty
*/
gboolean
gsk_path_is_empty (GskPath *self)
{
@@ -302,7 +296,7 @@ gsk_path_is_empty (GskPath *self)
/**
* gsk_path_get_bounds:
* @self: a #GskPath
* @self: a `GskPath`
* @bounds: (out caller-allocates): the bounds of the given path
*
* Computes the bounds of the given path.
@@ -320,9 +314,9 @@ gsk_path_is_empty (GskPath *self)
* is a single point at the origin, where the @bounds will also be set to
* the zero rectangle but 0 will be returned.
*
* Returns: %TRUE if the path has bounds, %FALSE if the path is known
* to be empty and have no bounds.
**/
* Returns: `TRUE` if the path has bounds, `FALSE` if the path is known
* to be empty and have no bounds.
*/
gboolean
gsk_path_get_bounds (GskPath *self,
graphene_rect_t *bounds)
@@ -357,17 +351,19 @@ gsk_path_get_bounds (GskPath *self,
/**
* gsk_path_foreach:
* @self: a #GskPath
* @flags: flags to pass to the foreach function. See #GskPathForeachFlags for
* details about flags.
* @self: a `GskPath`
* @flags: flags to pass to the foreach function. See `GskPathForeachFlags`
* for details about flags
* @func: (scope call) (closure user_data): the function to call for operations
* @user_data: (nullable): user data passed to @func
*
* Calls @func for every operation of the path. Note that this only approximates
* @self, because paths can contain optimizations for various specialized contours.
* Calls @func for every operation of the path.
*
* Returns: %FALSE if @func returned %FALSE, %TRUE otherwise.
**/
* Note that this only approximates @self, because paths can contain
* optimizations for various specialized contours.
*
* Returns: `FALSE` if @func returned FALSE`, `TRUE` otherwise.
*/
gboolean
gsk_path_foreach (GskPath *self,
GskPathForeachFlags flags,
@@ -690,13 +686,16 @@ parse_circle (const char **p,
* gsk_path_parse:
* @string: a string
*
* This is a convenience function that constructs a #GskPath
* from a serialized form. The string is expected to be in
* [SVG path syntax](https://www.w3.org/TR/SVG11/paths.html#PathData),
* as e.g. produced by gsk_path_to_string().
* This is a convenience function that constructs a `GskPath`
* from a serialized form.
*
* Returns: (nullable): a new #GskPath, or %NULL if @string could not be parsed
**/
* The string is expected to be in
* [SVG path syntax](https://www.w3.org/TR/SVG11/paths.html#PathData),
* as e.g. produced by [method@Gsk.Path.to_string].
*
* Returns: (nullable): a new `GskPath`, or `NULL`
* if @string could not be parsed
*/
GskPath *
gsk_path_parse (const char *string)
{
@@ -1118,7 +1117,7 @@ error:
/**
* gsk_path_get_stroke_bounds:
* @self: a #GtkPath
* @self: a `GtkPath`
* @stroke: stroke parameters
* @bounds: (out caller-allocates): the bounds to fill in
*
@@ -1130,8 +1129,8 @@ error:
* to contain the area affected by the stroke, including protrusions
* like miters.
*
* Returns: %TRUE if the path has bounds, %FALSE if the path is known
* to be empty and have no bounds.
* Returns: `TRUE` if the path has bounds, `FALSE`
* if the path is known to be empty and have no bounds.
*/
gboolean
gsk_path_get_stroke_bounds (GskPath *self,

148
gsk/gskpathbuilder.c
View File

@@ -24,10 +24,11 @@
#include "gskpathprivate.h"
/**
* SECTION:gskpathbuilder
* @Title: Building paths
* @Short_description: Building paths of lines and curves
* @See_also: #GskPath, #GskPathMeasure
* GskPathBuilder:
*
* A #GskPathBuilder struct is an opaque struct. It is meant to
* not be kept around and only be used to create new #GskPath
* objects.
*
* This section describes how to construct #GskPath structures.
*
@@ -46,30 +47,22 @@
* return gsk_path_builder_free_to_path (builder);
* ]|
*
* Adding contours to the path can be done in two ways.
* 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 gsk_path_builder_add_circle()
* or by adding from other paths like gsk_path_builder_add_path().
* either common shapes like [method@Gsk.PathBuilder.add_circle]
* or by adding from other paths like [method@Gsk.PathBuilder.add_path].
*
* 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 gsk_path_builder_move_to() to set the starting point
* a call to [method@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
* gsk_path_builder_close() to close the path by connecting it
* [method@Gsk.PathBuilder.close] to close the path by connecting it
* back with a line to the starting point.
* This is similar for how paths are drawn in Cairo.
*/
/**
* GskPathBuilder:
*
* A #GskPathBuilder struct is an opaque struct. It is meant to
* not be kept around and only be used to create new #GskPath
* objects.
*/
struct _GskPathBuilder
{
int ref_count;
@@ -91,11 +84,12 @@ G_DEFINE_BOXED_TYPE (GskPathBuilder,
/**
* gsk_path_builder_new:
*
* Create a new #GskPathBuilder object. The resulting builder
* would create an empty #GskPath. Use addition functions to add
* types to it.
* Create a new `GskPathBuilder` object.
*
* Returns: a new #GskPathBuilder
* The resulting builder would create an empty `GskPath`.
* Use addition functions to add types to it.
*
* Returns: a new `GskPathBuilder`
**/
GskPathBuilder *
gsk_path_builder_new (void)
@@ -116,15 +110,15 @@ gsk_path_builder_new (void)
/**
* gsk_path_builder_ref:
* @self: a #GskPathBuilder
* @self: a `GskPathBuilder`
*
* Acquires a reference on the given builder.
*
* This function is intended primarily for bindings. #GskPathBuilder objects
* should not be kept around.
* This function is intended primarily for bindings.
* `GskPathBuilder` objects should not be kept around.
*
* Returns: (transfer none): the given #GskPathBuilder with
* its reference count increased
* Returns: (transfer none): the given `GskPathBuilder`
* with its reference count increased
*/
GskPathBuilder *
gsk_path_builder_ref (GskPathBuilder *self)
@@ -208,7 +202,7 @@ gsk_path_builder_clear (GskPathBuilder *self)
/**
* gsk_path_builder_unref:
* @self: a #GskPathBuilder
* @self: a `GskPathBuilder`
*
* Releases a reference on the given builder.
*/
@@ -231,12 +225,12 @@ gsk_path_builder_unref (GskPathBuilder *self)
/**
* gsk_path_builder_free_to_path: (skip)
* @self: a #GskPathBuilder
* @self: a `GskPathBuilder`
*
* Creates a new #GskPath from the current state of the
* Creates a new `GskPath` from the current state of the
* given builder, and frees the @builder instance.
*
* Returns: (transfer full): the newly created #GskPath
* Returns: (transfer full): the newly created `GskPath`
* with all the contours added to the builder
*/
GskPath *
@@ -255,17 +249,18 @@ gsk_path_builder_free_to_path (GskPathBuilder *self)
/**
* gsk_path_builder_to_path:
* @self: a #GskPathBuilder
* @self: a `GskPathBuilder`
*
* 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.
* 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 bindings. C code should use
* gsk_path_builder_free_to_path().
* This function is intended primarily for bindings. C code should
* use [method@Gsk.PathBuilder.free_to_path].
*
* Returns: (transfer full): the newly created #GskPath
* Returns: (transfer full): the newly created `GskPath`
* with all the contours added to the builder
*/
GskPath *
@@ -297,7 +292,7 @@ gsk_path_builder_add_contour (GskPathBuilder *self,
/**
* gsk_path_builder_get_current_point:
* @self: a #GskPathBuilder
* @self: a `GskPathBuilder`
*
* Gets the current point. The current point is used for relative
* drawing commands and updated after every operation.
@@ -316,7 +311,7 @@ gsk_path_builder_get_current_point (GskPathBuilder *self)
/**
* gsk_path_builder_add_path:
* @self: a #GskPathBuilder
* @self: a `GskPathBuilder`
* @path: (transfer none): the path to append
*
* Appends all of @path to the builder.
@@ -340,11 +335,12 @@ gsk_path_builder_add_path (GskPathBuilder *self,
/**
* gsk_path_builder_add_cairo_path:
* @self: a #GskPathBuilder
* @self: a `GskPathBuilder`
*
* Adds a Cairo path to the builder.
*
* You can use cairo_copy_path() to access the path from a Cairo context.
* You can use cairo_copy_path() to access the path
* from a Cairo context.
**/
void
gsk_path_builder_add_cairo_path (GskPathBuilder *self,
@@ -389,7 +385,7 @@ gsk_path_builder_add_cairo_path (GskPathBuilder *self,
/**
* gsk_path_builder_add_rect:
* @self: A #GskPathBuilder
* @self: A `GskPathBuilder`
* @rect: The rectangle to create a path for
*
* Adds @rect as a new contour to the path built by the builder.
@@ -416,7 +412,7 @@ gsk_path_builder_add_rect (GskPathBuilder *self,
/**
* gsk_path_builder_add_rounded_rect:
* @self: a #GskPathBuilder
* @self: a `GskPathBuilder`
* @rect: the rounded rect
*
* Adds @rect as a new contour to the path built in @self.
@@ -483,7 +479,7 @@ gsk_path_builder_add_rounded_rect (GskPathBuilder *self,
/**
* gsk_path_builder_add_circle:
* @self: a #GskPathBuilder
* @self: a `GskPathBuilder`
* @center: the center of the circle
* @radius: the radius of the circle
*
@@ -506,7 +502,7 @@ gsk_path_builder_add_circle (GskPathBuilder *self,
/**
* gsk_path_builder_add_ellipse:
* @self: a #GskPathBuilder
* @self: a `GskPathBuilder`
* @center: the center point of the ellipse
* @radius: the radius of the ellipse in x/y direction
*
@@ -552,16 +548,16 @@ gsk_path_builder_add_ellipse (GskPathBuilder *self,
/**
* gsk_path_builder_move_to:
* @self: a #GskPathBuilder
* @self: a `GskPathBuilder`
* @x: x coordinate
* @y: y coordinate
*
* Starts a new contour by placing the pen at @x, @y.
*
* If gsk_path_builder_move_to() 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.
**/
* If gsk_path_builder_move_to() 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.
*/
void
gsk_path_builder_move_to (GskPathBuilder *self,
float x,
@@ -578,15 +574,15 @@ gsk_path_builder_move_to (GskPathBuilder *self,
/**
* gsk_path_builder_rel_move_to:
* @self: a #GskPathBuilder
* @self: a `GskPathBuilder`
* @x: x offset
* @y: y offset
*
* Starts a new contour by placing the pen at @x, @y relative to the current
* point.
* Starts a new contour by placing the pen at @x, @y relative
* to the current point.
*
* This is the relative version of gsk_path_builder_move_to().
**/
* This is the relative version of [method@Gsk.PathBuilder.move_to].
*/
void
gsk_path_builder_rel_move_to (GskPathBuilder *self,
float x,
@@ -601,13 +597,13 @@ gsk_path_builder_rel_move_to (GskPathBuilder *self,
/**
* gsk_path_builder_line_to:
* @self: a #GskPathBuilder
* @self: a `GskPathBuilder`
* @x: x coordinate
* @y: y coordinate
*
* Draws a line from the current point to @x, @y and makes it the new current
* point.
**/
* Draws a line from the current point to @x, @y and
* makes it the new current point.
*/
void
gsk_path_builder_line_to (GskPathBuilder *self,
float x,
@@ -629,15 +625,15 @@ gsk_path_builder_line_to (GskPathBuilder *self,
/**
* gsk_path_builder_rel_line_to:
* @self: a #GskPathBuilder
* @self: a `GskPathBuilder`
* @x: x offset
* @y: y offset
*
* Draws a line from the current point to a point offset to it by @x, @y
* and makes it the new current point.
* Draws a line from the current point to a point offset to
* it by @x, @y and makes it the new current point.
*
* This is the relative version of gsk_path_builder_line_to().
**/
* This is the relative version of [method@Gsk.PathBuilder.line_to].
*/
void
gsk_path_builder_rel_line_to (GskPathBuilder *self,
float x,
@@ -652,7 +648,7 @@ gsk_path_builder_rel_line_to (GskPathBuilder *self,
/**
* gsk_path_builder_curve_to:
* @self: a #GskPathBuilder
* @self: a `GskPathBuilder`
* @x1: x coordinate of first control point
* @y1: y coordinate of first control point
* @x2: x coordinate of second control point
@@ -689,7 +685,7 @@ gsk_path_builder_curve_to (GskPathBuilder *self,
/**
* gsk_path_builder_rel_curve_to:
* @self: a #GskPathBuilder
* @self: a `GskPathBuilder`
* @x1: x offset of first control point
* @y1: y offset of first control point
* @x2: x offset of second control point
@@ -701,8 +697,8 @@ gsk_path_builder_curve_to (GskPathBuilder *self,
* 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 gsk_path_builder_curve_to().
**/
* This is the relative version of [method@Gsk.PathBuilder.curve_to].
*/
void
gsk_path_builder_rel_curve_to (GskPathBuilder *self,
float x1,
@@ -725,7 +721,7 @@ gsk_path_builder_rel_curve_to (GskPathBuilder *self,
/**
* gsk_path_builder_conic_to:
* @self: a #GskPathBuilder
* @self: a `GskPathBuilder`
* @x1: x coordinate of control point
* @y1: y coordinate of control point
* @x2: x coordinate of the end of the curve
@@ -739,7 +735,7 @@ gsk_path_builder_rel_curve_to (GskPathBuilder *self,
* Conic curves can be used to draw ellipses and circles.
*
* After this, @x2, @y2 will be the new current point.
**/
*/
void
gsk_path_builder_conic_to (GskPathBuilder *self,
float x1,
@@ -763,7 +759,7 @@ gsk_path_builder_conic_to (GskPathBuilder *self,
/**
* gsk_path_builder_rel_conic_to:
* @self: a #GskPathBuilder
* @self: a `GskPathBuilder`
* @x1: x offset of control point
* @y1: y offset of control point
* @x2: x offset of the end of the curve
@@ -774,8 +770,8 @@ gsk_path_builder_conic_to (GskPathBuilder *self,
* from the current point to @x2, @y2 with the given
* @weight and @x1, @y1 as the single control point.
*
* This is the relative version of gsk_path_builder_conic_to().
**/
* This is the relative version of [Gsk.PathBuilder.conic_to].
*/
void
gsk_path_builder_rel_conic_to (GskPathBuilder *self,
float x1,
@@ -797,16 +793,16 @@ gsk_path_builder_rel_conic_to (GskPathBuilder *self,
/**
* gsk_path_builder_close:
* @self: a #GskPathBuilder
* @self: a `GskPathBuilder`
*
* Ends the current contour with a line back to the start point.
*
* Note that this is different from calling gsk_path_builder_line_to()
* Note that this is different from calling [method@Gsk.PathBuilder.line_to]
* with the start point in that the contour will be closed. A closed
* contour behaves different 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.
**/
*/
void
gsk_path_builder_close (GskPathBuilder *self)
{
@@ -1002,7 +998,7 @@ gsk_path_builder_svg_arc_to (GskPathBuilder *self,
/**
* gsk_path_builder_add_layout:
* @self: a #GskPathBuilder
* @self: a `GskPathBuilder`
* @layout: the pango layout to add
*
* Adds the outlines for the glyphs in @layout to

121
gsk/gskpathmeasure.c
View File

@@ -25,13 +25,14 @@
#include "gskpathprivate.h"
/**
* SECTION:gskpathmeasure
* @Title: PathMeasure
* @Short_description: Measuring operations on paths
* @See_also: #GskPath
* GskPathMeasure:
*
* #GskPathMeasure is an object that allows measuring operations on #GskPaths.
* These operations are useful when implementing animations.
* A `GskPathMeasure` struct is a reference-counted struct
* and should be treated as opaque.
*
* `GskPathMeasure` is an object that allows measuring operations
* on `GskPath`. These operations are useful when implementing
* animations.
*/
typedef struct _GskContourMeasure GskContourMeasure;
@@ -59,10 +60,6 @@ struct _GskPathMeasure
};
/**
* GskPathMeasure:
*
* A #GskPathMeasure struct is a reference counted struct
* and should be treated as opaque.
*/
G_DEFINE_BOXED_TYPE (GskPathMeasure, gsk_path_measure,
@@ -75,8 +72,8 @@ G_DEFINE_BOXED_TYPE (GskPathMeasure, gsk_path_measure,
*
* Creates a measure object for the given @path.
*
* Returns: a new #GskPathMeasure representing @path
**/
* Returns: a new `GskPathMeasure` representing @path
*/
GskPathMeasure *
gsk_path_measure_new (GskPath *path)
{
@@ -90,8 +87,8 @@ gsk_path_measure_new (GskPath *path)
*
* Creates a measure object for the given @path and @tolerance.
*
* Returns: a new #GskPathMeasure representing @path
**/
* Returns: a new `GskPathMeasure` representing @path
*/
GskPathMeasure *
gsk_path_measure_new_with_tolerance (GskPath *path,
float tolerance)
@@ -126,12 +123,12 @@ gsk_path_measure_new_with_tolerance (GskPath *path,
/**
* gsk_path_measure_ref:
* @self: a #GskPathMeasure
* @self: a `GskPathMeasure`
*
* Increases the reference count of a #GskPathMeasure by one.
* Increases the reference count of a `GskPathMeasure` by one.
*
* Returns: the passed in #GskPathMeasure.
**/
* Returns: the passed in `GskPathMeasure`.
*/
GskPathMeasure *
gsk_path_measure_ref (GskPathMeasure *self)
{
@@ -144,11 +141,12 @@ gsk_path_measure_ref (GskPathMeasure *self)
/**
* gsk_path_measure_unref:
* @self: a #GskPathMeasure
* @self: a `GskPathMeasure`
*
* Decreases the reference count of a `GskPathMeasure` by one.
*
* Decreases the reference count of a #GskPathMeasure by one.
* If the resulting reference count is zero, frees the path_measure.
**/
*/
void
gsk_path_measure_unref (GskPathMeasure *self)
{
@@ -173,7 +171,7 @@ gsk_path_measure_unref (GskPathMeasure *self)
/**
* gsk_path_measure_get_path:
* @self: a #GskPathMeasure
* @self: a `GskPathMeasure`
*
* Returns the path that the measure was created for.
*
@@ -189,7 +187,7 @@ gsk_path_measure_get_path (GskPathMeasure *self)
/**
* gsk_path_measure_get_tolerance:
* @self: a #GskPathMeasure
* @self: a `GskPathMeasure`
*
* Returns the tolerance that the measure was created with.
*
@@ -205,7 +203,7 @@ gsk_path_measure_get_tolerance (GskPathMeasure *self)
/**
* gsk_path_measure_get_n_contours:
* @self: a #GskPathMeasure
* @self: a `GskPathMeasure`
*
* Returns the number of contours in the path being measured.
*
@@ -213,7 +211,7 @@ gsk_path_measure_get_tolerance (GskPathMeasure *self)
* or not.
*
* Returns: The number of contours
**/
*/
gsize
gsk_path_measure_get_n_contours (GskPathMeasure *self)
{
@@ -224,7 +222,7 @@ gsk_path_measure_get_n_contours (GskPathMeasure *self)
/**
* gsk_path_measure_restrict_to_contour:
* @self: a #GskPathMeasure
* @self: a `GskPathMeasure`
* @contour: contour to restrict to or (gsize) -1 for using the
* whole path
*
@@ -232,7 +230,7 @@ gsk_path_measure_get_n_contours (GskPathMeasure *self)
*
* If @contour >= gsk_path_measure_get_n_contours() - so in
* particular when it is set to -1 - the whole path will be used.
**/
*/
void
gsk_path_measure_restrict_to_contour (GskPathMeasure *self,
gsize contour)
@@ -259,14 +257,14 @@ gsk_path_measure_restrict_to_contour (GskPathMeasure *self,
/**
* gsk_path_measure_get_length:
* @self: a #GskPathMeasure
* @self: a `GskPathMeasure`
*
* Gets the length of the path being measured.
*
* The length is cached, so this function does not do any work.
*
* Returns: The length of the path measured by @self
**/
*/
float
gsk_path_measure_get_length (GskPathMeasure *self)
{
@@ -277,13 +275,13 @@ gsk_path_measure_get_length (GskPathMeasure *self)
/**
* gsk_path_measure_is_closed:
* @self: a #GskPathMeasure
* @self: a `GskPathMeasure`
*
* Returns if the path being measured represents a single closed
* contour.
*
* Returns: %TRUE if the current path is closed
**/
* Returns: `TRUE` if the current path is closed
*/
gboolean
gsk_path_measure_is_closed (GskPathMeasure *self)
{
@@ -311,12 +309,12 @@ gsk_path_measure_clamp_distance (GskPathMeasure *self,
/**
* gsk_path_measure_get_point:
* @self: a #GskPathMeasure
* @self: a `GskPathMeasure`
* @distance: distance into the path
* @pos: (out caller-allocates) (optional): The coordinates
* of the position at @distance
* of the position at @distance
* @tangent: (out caller-allocates) (optional): The tangent
* to the position at @distance
* to the position at @distance
*
* Calculates the coordinates and tangent of the point @distance
* units into the path. The value will be clamped to the length
@@ -326,9 +324,9 @@ gsk_path_measure_clamp_distance (GskPathMeasure *self,
* point and tangent will describe the line starting at that point
* going forward.
*
* If @self describes an empty path, the returned point will be
* If @self describes an empty path, the returned point will be
* set to `(0, 0)` and the tangent will be the x axis or `(1, 0)`.
**/
*/
void
gsk_path_measure_get_point (GskPathMeasure *self,
float distance,
@@ -378,7 +376,7 @@ gsk_path_measure_get_point (GskPathMeasure *self,
/**
* gsk_path_measure_get_closest_point:
* @self: a #GskPathMeasure
* @self: a `GskPathMeasure`
* @point: the point to fond the closest point to
* @out_pos: (out caller-allocates) (optional): return location
* for the closest point
@@ -388,12 +386,12 @@ gsk_path_measure_get_point (GskPathMeasure *self,
* If the path being measured is empty, return 0 and set
* @out_pos to (0, 0).
*
* This is a simpler and slower version of
* gsk_path_measure_get_closest_point_full(). Use that one if you
* need more control.
* This is a simpler version of
* [method@Gsk.PathMeasure.get_closest_point_full].
* Use that one if you need more control.
*
* Returns: The offset into the path of the closest point
**/
*/
float
gsk_path_measure_get_closest_point (GskPathMeasure *self,
const graphene_point_t *point,
@@ -421,25 +419,27 @@ gsk_path_measure_get_closest_point (GskPathMeasure *self,
/**
* gsk_path_measure_get_closest_point_full:
* @self: a #GskPathMeasure
* @self: a `GskPathMeasure`
* @point: the point to fond the closest point to
* @threshold: The maximum allowed distance between the path and @point.
* Use INFINITY to look for any point.
* Use `INFINITY` to look for any point.
* @out_distance: (out caller-allocates) (optional): The
* distance between the found closest point on the path and the given
* @point.
* distance between the found closest point on the path and the given
* @point.
* @out_pos: (out caller-allocates) (optional): return location
* for the closest point
* for the closest point
* @out_offset: (out caller-allocates) (optional): The offset into
* the path of the found point
* the path of the found point
* @out_tangent: (out caller-allocates) (optional): return location for
* the tangent at the closest point
* the tangent at the closest point
*
* Gets the point on the path that is closest to @point. If no point on
* path is closer to @point than @threshold, return %FALSE.
* Gets the point on the path that is closest to @point.
*
* Returns: %TRUE if a point was found, %FALSE otherwise.
**/
* If no point on path is closer to @point than @threshold,
* return `FALSE`.
*
* Returns: `TRUE` if a point was found, `FALSE` otherwise.
*/
gboolean
gsk_path_measure_get_closest_point_full (GskPathMeasure *self,
const graphene_point_t *point,
@@ -491,14 +491,14 @@ gsk_path_measure_get_closest_point_full (GskPathMeasure *self,
/**
* gsk_path_measure_in_fill:
* @self: a #GskPathMeasure
* @self: a `GskPathMeasure`
* @point: the point to test
* @fill_rule: the fill rule to follow
*
* Returns whether the given point is inside the area that would be
* affected if the path of @self was filled according to @fill_rule.
*
* Returns: %TRUE if @point is inside
* Returns: `TRUE` if @point is inside
*/
gboolean
gsk_path_measure_in_fill (GskPathMeasure *self,
@@ -571,23 +571,22 @@ gsk_path_builder_add_segment_chunk (GskPathBuilder *self,
/**
* gsk_path_builder_add_segment:
* @self: a #GskPathBuilder
* @measure: the #GskPathMeasure to take the segment to
* @self: a `GskPathBuilder`
* @measure: the `GskPathMeasure` to take the segment to
* @start: start distance into the path
* @end: end distance into the path
*
* Adds to @self the segment of @measure from @start to @end.
*
* The distances are given relative to the length of @measure's path,
* from 0 for the beginning of the path to
* gsk_path_measure_get_length() for the end of the path. The values
* will be clamped to that range.
* from 0 for the beginning of the path to [method@Gsk.PathMeasure.get_length]
* for the end of the path. The values will be clamped to that range.
*
* If @start >= @end after clamping, 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.
**/
*/
void
gsk_path_builder_add_segment (GskPathBuilder *self,
GskPathMeasure *measure,

2
gsk/gskrendernodeimpl.c
View File

@@ -4701,7 +4701,7 @@ gsk_stroke_node_get_child (GskRenderNode *node)
* gsk_stroke_node_get_path:
* @node: (type GskStrokeNode): a stroke #GskRenderNode
*
* Retrievs the path that will be stroked with the contents of
* Retrieves the path that will be stroked with the contents of
* the @node.
*
* Returns: (transfer none): a #GskPath

155
gsk/gskstroke.c
View File

@@ -22,24 +22,8 @@
#include "gskstrokeprivate.h"
/**
* SECTION:gskstroke
* @Title: Stroke
* @Short_description: Properties of a stroke operation
* @See_also: #GskPath, gsk_stroke_node_new()
*
* This section describes the #GskStroke structure that is used to
* describe lines and curves that are more complex than simple rectangles.
*
* #GskStroke is an immutable struct. After creation, you cannot change
* the types it represents. Instead, new #GskStroke have to be created.
* The #GskStrokeBuilder structure is meant to help in this endeavor.
*/
/**
* GskStroke:
*
* A #GskStroke struct is an opaque struct that should be copied
* on use.
* A `GskStroke` struct collects the parameters that influence
* the operation of stroking a path.
*/
G_DEFINE_BOXED_TYPE (GskStroke, gsk_stroke,
@@ -53,8 +37,8 @@ G_DEFINE_BOXED_TYPE (GskStroke, gsk_stroke,
*
* Creates a new #GskStroke with the given @line_width.
*
* Returns: a new #GskStroke
**/
* Returns: a new `GskStroke`
*/
GskStroke *
gsk_stroke_new (float line_width)
{
@@ -74,12 +58,12 @@ gsk_stroke_new (float line_width)
/**
* gsk_stroke_copy:
* @other: #GskStroke to copy
* @other: `GskStroke` to copy
*
* Creates a copy of the given @other stroke.
*
* Returns: a new #GskStroke. Use gsk_stroke_free() to free it.
**/
* Returns: a new `GskStroke`. Use [method@Gsk.Stroke.free] to free it
*/
GskStroke *
gsk_stroke_copy (const GskStroke *other)
{
@@ -96,10 +80,10 @@ gsk_stroke_copy (const GskStroke *other)
/**
* gsk_stroke_free:
* @self: a #GskStroke
* @self: a `GskStroke`
*
* Frees a #GskStroke.
**/
* Frees a `GskStroke`.
*/
void
gsk_stroke_free (GskStroke *self)
{
@@ -176,8 +160,9 @@ gsk_stroke_to_cairo (const GskStroke *self,
*
* Checks if 2 strokes are identical.
*
* Returns: %TRUE if the 2 strokes are equal, %FALSE otherwise
**/
* Returns: `TRUE` if the 2 strokes are equal,
* `FALSE` otherwise
*/
gboolean
gsk_stroke_equal (gconstpointer stroke1,
gconstpointer stroke2)
@@ -190,12 +175,12 @@ gsk_stroke_equal (gconstpointer stroke1,
/**
* gsk_stroke_set_line_width:
* @self: a #GskStroke
* @self: a `GskStroke`
* @line_width: width of the line in pixels
*
* Sets the line width to be used when stroking. The line width
* must be > 0.
**/
*/
void
gsk_stroke_set_line_width (GskStroke *self,
float line_width)
@@ -208,12 +193,12 @@ gsk_stroke_set_line_width (GskStroke *self,
/**
* gsk_stroke_get_line_width:
* @self: a #GskStroke
* @self: a `GskStroke`
*
* Gets the line width used.
*
* Returns: The line width
**/
*/
float
gsk_stroke_get_line_width (const GskStroke *self)
{
@@ -224,12 +209,13 @@ gsk_stroke_get_line_width (const GskStroke *self)
/**
* gsk_stroke_set_line_cap:
* @self: a #GskStroke
* @line_cap: the #GskLineCap
* @self: a`GskStroke`
* @line_cap: the `GskLineCap`
*
* Sets the line cap to be used when stroking.
* See #GskLineCap for details.
**/
*
* See [enum@Gsk.LineCap] for details.
*/
void
gsk_stroke_set_line_cap (GskStroke *self,
GskLineCap line_cap)
@@ -241,12 +227,14 @@ gsk_stroke_set_line_cap (GskStroke *self,
/**
* gsk_stroke_get_line_cap:
* @self: a #GskStroke
* @self: a `GskStroke`
*
* Gets the line cap used. See #GskLineCap for details.
* Gets the line cap used.
*
* See [enum@Gsk.LineCap] for details.
*
* Returns: The line cap
**/
*/
GskLineCap
gsk_stroke_get_line_cap (const GskStroke *self)
{
@@ -257,12 +245,13 @@ gsk_stroke_get_line_cap (const GskStroke *self)
/**
* gsk_stroke_set_line_join:
* @self: a #GskStroke
* @self: a `GskStroke`
* @line_join: The line join to use
*
* Sets the line join to be used when stroking.
* See #GskLineJoin for details.
**/
*
* See [enum@Gsk.LineJoin] for details.
*/
void
gsk_stroke_set_line_join (GskStroke *self,
GskLineJoin line_join)
@@ -274,12 +263,14 @@ gsk_stroke_set_line_join (GskStroke *self,
/**
* gsk_stroke_get_line_join:
* @self: a #GskStroke
* @self: a `GskStroke`
*
* Gets the line join used. See #GskLineJoin for details.
* Gets the line join used.
*
* See [enum@Gsk.LineJoin] for details.
*
* Returns: The line join
**/
*/
GskLineJoin
gsk_stroke_get_line_join (const GskStroke *self)
{
@@ -290,16 +281,16 @@ gsk_stroke_get_line_join (const GskStroke *self)
/**
* gsk_stroke_set_miter_limit:
* @self: a #GskStroke
* @self: a `GskStroke`
* @limit: the miter limit, must be non-negative
*
* Sets the limit for the distance from the corner where sharp
* turns of joins get cut off. The miter limit is in units of
* line width.
*
* For joins of type %GSK_LINE_JOIN_MITER that exceed the miter
* For joins of type `GSK_LINE_JOIN_MITER` that exceed the miter
* limit, the join gets rendered as if it was of type
* %GSK_LINE_JOIN_BEVEL. For joins of type %GSK_LINE_JOIN_MITER_CLIP,
* `GSK_LINE_JOIN_BEVEL`. For joins of type `GSK_LINE_JOIN_MITER_CLIP`,
* the miter is clipped at a distance of half the miter limit.
*/
void
@@ -314,9 +305,9 @@ gsk_stroke_set_miter_limit (GskStroke *self,
/**
* gsk_stroke_get_miter_limit:
* @self: a #GskStroke
* @self: a `GskStroke`
*
* Returns the miter limit of a #GskStroke.
* Returns the miter limit of a `GskStroke`.
*/
float
gsk_stroke_get_miter_limit (const GskStroke *self)
@@ -328,32 +319,35 @@ gsk_stroke_get_miter_limit (const GskStroke *self)
/**
* gsk_stroke_set_dash:
* @self: a #GskStroke
* @self: a `GskStroke`
* @dash: (array length=n_dash) (transfer none) (nullable):
* the array of dashes
* the array of dashes
* @n_dash: number of elements in @dash
*
* Sets the dash pattern to use by this stroke. A dash pattern is specified by
* an array of alternating non-negative values. Each value provides the length
* of alternate "on" and "off" portions of the stroke.
*
* Each "on" segment will have caps applied as if the segment were a separate
* contour. In particular, it is valid to use an "on" length of 0 with
* @GSK_LINE_CAP_ROUND or @GSK_LINE_CAP_SQUARE to draw dots or squares along
* a path.
* Sets the dash pattern to use by this stroke.
*
* If @n_dash is 0, if all elements in @dash are 0, or if there are negative
* values in @dash, then dashing is disabled.
* A dash pattern is specified by an array of alternating non-negative
* values. Each value provides the length of alternate "on" and "off"
* portions of the stroke.
*
* If @n_dash is 1, an alternating "on" and "off" pattern with the single
* dash length provided is assumed.
* Each "on" segment will have caps applied as if the segment were a
* separate contour. In particular, it is valid to use an "on" length
* of 0 with `GSK_LINE_CAP_ROUND` or `GSK_LINE_CAP_SQUARE` to draw dots
* or squares along a path.
*
* If @n_dash is uneven, the dash array will be used with the first element
* in @dash defining an "on" or "off" in alternating passes through the array.
* If @n_dash is 0, if all elements in @dash are 0, or if there are
* negative values in @dash, then dashing is disabled.
*
* If @n_dash is 1, an alternating "on" and "off" pattern with the
* single dash length provided is assumed.
*
* If @n_dash is uneven, the dash array will be used with the first
* element in @dash defining an "on" or "off" in alternating passes
* through the array.
*
* You can specify a starting offset into the dash with
* @gsk_stroke_set_dash_offset().
**/
* [method@Gsk.Stroke.set_dash_offset].
*/
void
gsk_stroke_set_dash (GskStroke *self,
const float *dash,
@@ -385,15 +379,15 @@ gsk_stroke_set_dash (GskStroke *self,
/**
* gsk_stroke_get_dash:
* @self: a #GskStroke
* @self: a `GskStroke`
* @n_dash: (out caller-allocates): number of elements
* in the array returned
*
* Gets the dash array in use or %NULL if dashing is disabled.
* Gets the dash array in use or `NULL` if dashing is disabled.
*
* Returns: (array length=n_dash) (transfer none) (nullable):
* The dash array or %NULL if the dash array is empty.
**/
* The dash array or `NULL` if the dash array is empty.
*/
const float *
gsk_stroke_get_dash (const GskStroke *self,
gsize *n_dash)
@@ -408,15 +402,16 @@ gsk_stroke_get_dash (const GskStroke *self,
/**
* gsk_stroke_set_dash_offset:
* @self: a #GskStroke
* @self: a `GskStroke`
* @offset: offset into the dash pattern
*
* Sets the offset into the dash pattern set via gsk_stroke_set_dash() where
* dashing should begin.
* Sets the offset into the dash pattern where dashing should begin.
*
* This is an offset into the length of the path, not an index into the array values of
* the dash array.
**/
* This is an offset into the length of the path, not an index into
* the array values of the dash array.
*
* See [method@Gsk.Stroke.set_dash] for more details on dashing.
*/
void
gsk_stroke_set_dash_offset (GskStroke *self,
float offset)
@@ -428,9 +423,9 @@ gsk_stroke_set_dash_offset (GskStroke *self,
/**
* gsk_stroke_get_dash_offset:
* @self: a #GskStroke
* @self: a `GskStroke`
*
* Returns the dash_offset of a #GskStroke.
* Returns the dash_offset of a `GskStroke`.
*/
float
gsk_stroke_get_dash_offset (const GskStroke *self)