1 /* ADG - Automatic Drawing Generation
2 * Copyright (C) 2007-2021 Nicola Fontana <ntd at entidi.it>
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2 of the License, or (at your option) any later version.
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with this library; if not, write to the
16 * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
17 * Boston, MA 02110-1301, USA.
25 * @short_description: Dash pattern for line stroking
27 * The #AdgDash boxed type wraps the values needed by cairo to
28 * univoquely identify a dash pattern, an array of positive values. Each
29 * value provides the length of alternate "on" and "off" portions of the
30 * stroke. The offset specifies an offset into the pattern at which the
33 * Each "on" segment will have caps applied as if the segment were a
34 * separate sub-path. In particular, it is valid to use an "on" length of
35 * 0 with %CAIRO_LINE_CAP_ROUND or %CAIRO_LINE_CAP_SQUARE in order to
36 * distribute dots or squares along a path.
38 * Check the cairo_set_dash() documentation for further details:
39 * http://www.cairographics.org/manual/cairo-cairo-t.html#cairo-set-dash
47 * All fields are private and should not be used directly.
48 * Use its public methods instead.
54 #include "adg-internal.h"
57 #include "adg-dash-private.h"
63 adg_dash_get_type(void)
65 static GType dash_type
= 0;
67 if (G_UNLIKELY(dash_type
== 0))
68 dash_type
= g_boxed_type_register_static("AdgDash",
69 (GBoxedCopyFunc
) adg_dash_dup
,
70 (GBoxedFreeFunc
) adg_dash_destroy
);
77 * @src: an #AdgDash instance
79 * Duplicates @src. The returned value must be freed with adg_dash_destroy()
80 * when no longer needed.
82 * Returns: (transfer full): the duplicate of @src.
87 adg_dash_dup(const AdgDash
*src
)
91 g_return_val_if_fail(src
!= NULL
, NULL
);
93 dash
= cpml_memdup(src
, sizeof(AdgDash
));
94 dash
->dashes
= cpml_memdup(src
->dashes
, sizeof(gdouble
) * src
->num_dashes
);
102 * Creates a new empty dash pattern.
104 * Returns: (transfer full): the newly created dash pattern.
111 AdgDash
*dash
= g_new(AdgDash
, 1);
114 dash
->num_dashes
= 0;
121 * adg_dash_new_with_dashes:
122 * @num_dashes: the number of dashes to set
123 * @...: lengths (a list of double values) of each dash
125 * Creates a new dash pattern, presetting some dashes on it.
127 * Returns: (transfer full): the newly created dash pattern.
132 adg_dash_new_with_dashes(gint num_dashes
, ...)
137 va_start(var_args
, num_dashes
);
138 dash
= adg_dash_new_with_dashes_valist(num_dashes
, var_args
);
145 * adg_dash_new_with_dashes_valist:
146 * @num_dashes: number of dashes to append
147 * @var_args: a va_list containing @num_dashes list of #gdouble
149 * Variadic version of adg_dash_new_with_dashes().
151 * Returns: (transfer full): the newly created dash pattern.
156 adg_dash_new_with_dashes_valist(gint num_dashes
, va_list var_args
)
158 AdgDash
*dash
= adg_dash_new();
159 adg_dash_append_dashes_valist(dash
, num_dashes
, var_args
);
164 * adg_dash_new_with_dashes_array: (rename-to adg_dash_new_with_dashes)
165 * @num_dashes: number of dashes to append
166 * @dashes: (array length=num_dashes): array of @num_dashes gdoubles
168 * Array version of adg_dash_new_with_dashes().
170 * Returns: (transfer full): the newly created dash pattern.
175 adg_dash_new_with_dashes_array(gint num_dashes
, const gdouble
*dashes
)
177 AdgDash
*dash
= adg_dash_new();
178 adg_dash_append_dashes_array(dash
, num_dashes
, dashes
);
183 * adg_dash_append_dash:
184 * @dash: an #AdgDash instance
185 * @length: the length value
187 * Appends to the @dash pattern a new dash of the specified @length value.
192 adg_dash_append_dash(AdgDash
*dash
, gdouble length
)
194 g_return_if_fail(dash
!= NULL
);
197 dash
->dashes
= g_realloc(dash
->dashes
, sizeof(gdouble
) * dash
->num_dashes
);
198 dash
->dashes
[dash
->num_dashes
- 1] = length
;
202 * adg_dash_append_dashes:
203 * @dash: an #AdgDash instance
204 * @num_dashes: number of dashes to append
205 * @...: a @num_dashes list of #gdouble
207 * Appends to the current @dash pattern @num_dashes number of dashes.
208 * The length of each dash must be specified as gdouble in the arguments.
213 adg_dash_append_dashes(AdgDash
*dash
, gint num_dashes
, ...)
217 va_start(var_args
, num_dashes
);
218 adg_dash_append_dashes_valist(dash
, num_dashes
, var_args
);
223 * adg_dash_append_dashes_valist:
224 * @dash: an #AdgDash instance
225 * @num_dashes: number of dashes to append
226 * @var_args: a va_list containing @num_dashes list of #gdouble
228 * Variadic version of adg_dash_append_dashes().
233 adg_dash_append_dashes_valist(AdgDash
*dash
, gint num_dashes
, va_list var_args
)
237 g_return_if_fail(dash
!= NULL
);
238 g_return_if_fail(num_dashes
> 0);
240 while (num_dashes
--) {
241 length
= va_arg(var_args
, gdouble
);
242 adg_dash_append_dash(dash
, length
);
247 * adg_dash_append_dashes_array: (rename-to adg_dash_append_dashes)
248 * @dash: an #AdgDash instance
249 * @num_dashes: number of dashes to append
250 * @dashes: (array length=num_dashes): array of @num_dashes gdoubles
252 * Array version of adg_dash_append_dashes().
257 adg_dash_append_dashes_array(AdgDash
*dash
,
258 gint num_dashes
, const gdouble
*dashes
)
260 g_return_if_fail(dash
!= NULL
);
262 if (num_dashes
> 0) {
263 gint old_dashes
= dash
->num_dashes
;
264 dash
->num_dashes
+= num_dashes
;
265 dash
->dashes
= g_realloc(dash
->dashes
, sizeof(gdouble
) * dash
->num_dashes
);
266 memcpy(dash
->dashes
+ old_dashes
, dashes
, sizeof(gdouble
) * num_dashes
);
271 * adg_dash_get_num_dashes:
272 * @dash: an #AdgDash instance
274 * Gets the number of dashes stored inside this dash pattern.
276 * Returns: the number of dashes or -1 if @dash is invalid.
281 adg_dash_get_num_dashes(const AdgDash
*dash
)
283 g_return_val_if_fail(dash
!= NULL
, -1);
284 return dash
->num_dashes
;
288 * adg_dash_get_dashes:
289 * @dash: an #AdgDash instance
291 * Gets the array of gdoubles containing the length of each dash of the
294 * Returns: the array of lengths or <constant>NULL</constant> on invalid @dash. The array is owned by @dash and must not be modified or freed.
299 adg_dash_get_dashes(const AdgDash
*dash
)
301 g_return_val_if_fail(dash
!= NULL
, NULL
);
306 * adg_dash_clear_dashes:
307 * @dash: an #AdgDash instance
309 * Resets the dashes of @dash, effectively clearing the pattern.
314 adg_dash_clear_dashes(AdgDash
*dash
)
316 g_return_if_fail(dash
!= NULL
);
318 g_free(dash
->dashes
);
320 dash
->num_dashes
= 0;
324 * adg_dash_set_offset:
325 * @dash: an #AdgDash instance
326 * @offset: the new offset value
328 * Sets the pattern offset of @dash to @offset.
333 adg_dash_set_offset(AdgDash
*dash
, gdouble offset
)
335 g_return_if_fail(dash
!= NULL
);
337 dash
->offset
= offset
;
341 * adg_dash_get_offset:
342 * @dash: an #AdgDash instance
344 * Gets the offset of the pattern in @dash.
346 * Returns: the offset of @dash or 0 on invalid @dash.
351 adg_dash_get_offset(const AdgDash
*dash
)
353 g_return_val_if_fail(dash
!= NULL
, 0);
359 * @dash: an #AdgDash instance
361 * Destroys @dash, freeing every resource owned by it. After the destruction
362 * @dash cannot be used anymore.
367 adg_dash_destroy(AdgDash
*dash
)
369 g_return_if_fail(dash
!= NULL
);
371 g_free(dash
->dashes
);