src/adg/adg-dash.c

   1 /* ADG - Automatic Drawing Generation
   2  * Copyright (C) 2007-2019  Nicola Fontana <ntd at entidi.it>
   3  *
   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.
   8  *
   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.
  13  *
  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.
  18  */
  19
  20
  21 /**
  22  * SECTION:adg-dash
  23  * @Section_Id:AdgDash
  24  * @title: AdgDash
  25  * @short_description: Dash pattern for line stroking
  26  *
  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
  31  * stroke begins.
  32  *
  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.
  37  *
  38  * Check the cairo_set_dash() documentation for further details:
  39  * http://www.cairographics.org/manual/cairo-cairo-t.html#cairo-set-dash
  40  *
  41  * Since: 1.0
  42  **/
  43
  44 /**
  45  * AdgDash:
  46  *
  47  * All fields are private and should not be used directly.
  48  * Use its public methods instead.
  49  *
  50  * Since: 1.0
  51  **/
  52
  53
  54 #include "adg-internal.h"
  55
  56 #include "adg-dash.h"
  57 #include "adg-dash-private.h"
  58
  59 #include <string.h>
  60
  61
  62 GType
  63 adg_dash_get_type(void)
  64 {
  65     static GType dash_type = 0;
  66
  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);
  71
  72     return dash_type;
  73 }
  74
  75 /**
  76  * adg_dash_dup:
  77  * @src: an #AdgDash instance
  78  *
  79  * Duplicates @src. The returned value must be freed with adg_dash_destroy()
  80  * when no longer needed.
  81  *
  82  * Returns: (transfer full): the duplicate of @src.
  83  *
  84  * Since: 1.0
  85  **/
  86 AdgDash *
  87 adg_dash_dup(const AdgDash *src)
  88 {
  89     AdgDash *dash;
  90
  91     g_return_val_if_fail(src != NULL, NULL);
  92
  93     dash = g_memdup(src, sizeof(AdgDash));
  94     dash->dashes = g_memdup(src->dashes, sizeof(gdouble) * src->num_dashes);
  95
  96     return dash;
  97 }
  98
  99 /**
 100  * adg_dash_new:
 101  *
 102  * Creates a new empty dash pattern.
 103  *
 104  * Returns: (transfer full): the newly created dash pattern.
 105  *
 106  * Since: 1.0
 107  **/
 108 AdgDash *
 109 adg_dash_new(void)
 110 {
 111     AdgDash *dash = g_new(AdgDash, 1);
 112
 113     dash->dashes = NULL;
 114     dash->num_dashes = 0;
 115     dash->offset = 0;
 116
 117     return dash;
 118 }
 119
 120 /**
 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
 124  *
 125  * Creates a new dash pattern, presetting some dashes on it.
 126  *
 127  * Returns: (transfer full): the newly created dash pattern.
 128  *
 129  * Since: 1.0
 130  **/
 131 AdgDash *
 132 adg_dash_new_with_dashes(gint num_dashes, ...)
 133 {
 134     AdgDash *dash;
 135     va_list var_args;
 136
 137     va_start(var_args, num_dashes);
 138     dash = adg_dash_new_with_dashes_valist(num_dashes, var_args);
 139     va_end(var_args);
 140
 141     return dash;
 142 }
 143
 144 /**
 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
 148  *
 149  * Variadic version of adg_dash_new_with_dashes().
 150  *
 151  * Returns: (transfer full): the newly created dash pattern.
 152  *
 153  * Since: 1.0
 154  **/
 155 AdgDash *
 156 adg_dash_new_with_dashes_valist(gint num_dashes, va_list var_args)
 157 {
 158     AdgDash *dash = adg_dash_new();
 159     adg_dash_append_dashes_valist(dash, num_dashes, var_args);
 160     return dash;
 161 }
 162
 163 /**
 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
 167  *
 168  * Array version of adg_dash_new_with_dashes().
 169  *
 170  * Returns: (transfer full): the newly created dash pattern.
 171  *
 172  * Since: 1.0
 173  **/
 174 AdgDash *
 175 adg_dash_new_with_dashes_array(gint num_dashes, const gdouble *dashes)
 176 {
 177     AdgDash *dash = adg_dash_new();
 178     adg_dash_append_dashes_array(dash, num_dashes, dashes);
 179     return dash;
 180 }
 181
 182 /**
 183  * adg_dash_append_dash:
 184  * @dash: an #AdgDash instance
 185  * @length: the length value
 186  *
 187  * Appends to the @dash pattern a new dash of the specified @length value.
 188  *
 189  * Since: 1.0
 190  **/
 191 void
 192 adg_dash_append_dash(AdgDash *dash, gdouble length)
 193 {
 194     g_return_if_fail(dash != NULL);
 195
 196     ++ dash->num_dashes;
 197     dash->dashes = g_realloc(dash->dashes, sizeof(gdouble) * dash->num_dashes);
 198     dash->dashes[dash->num_dashes - 1] = length;
 199 }
 200
 201 /**
 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
 206  *
 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.
 209  *
 210  * Since: 1.0
 211  **/
 212 void
 213 adg_dash_append_dashes(AdgDash *dash, gint num_dashes, ...)
 214 {
 215     va_list var_args;
 216
 217     va_start(var_args, num_dashes);
 218     adg_dash_append_dashes_valist(dash, num_dashes,  var_args);
 219     va_end(var_args);
 220 }
 221
 222 /**
 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
 227  *
 228  * Variadic version of adg_dash_append_dashes().
 229  *
 230  * Since: 1.0
 231  **/
 232 void
 233 adg_dash_append_dashes_valist(AdgDash *dash, gint num_dashes, va_list var_args)
 234 {
 235     gdouble length;
 236
 237     g_return_if_fail(dash != NULL);
 238     g_return_if_fail(num_dashes > 0);
 239
 240     while (num_dashes --) {
 241         length = va_arg(var_args, gdouble);
 242         adg_dash_append_dash(dash, length);
 243     }
 244 }
 245
 246 /**
 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
 251  *
 252  * Array version of adg_dash_append_dashes().
 253  *
 254  * Since: 1.0
 255  **/
 256 void
 257 adg_dash_append_dashes_array(AdgDash *dash,
 258                              gint num_dashes, const gdouble *dashes)
 259 {
 260     g_return_if_fail(dash != NULL);
 261
 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);
 267     }
 268 }
 269
 270 /**
 271  * adg_dash_get_num_dashes:
 272  * @dash: an #AdgDash instance
 273  *
 274  * Gets the number of dashes stored inside this dash pattern.
 275  *
 276  * Returns: the number of dashes or -1 if @dash is invalid.
 277  *
 278  * Since: 1.0
 279  **/
 280 gint
 281 adg_dash_get_num_dashes(const AdgDash *dash)
 282 {
 283     g_return_val_if_fail(dash != NULL, -1);
 284     return dash->num_dashes;
 285 }
 286
 287 /**
 288  * adg_dash_get_dashes:
 289  * @dash: an #AdgDash instance
 290  *
 291  * Gets the array of gdoubles containing the length of each dash of the
 292  * pattern of @dash.
 293  *
 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.
 295  *
 296  * Since: 1.0
 297  **/
 298 const gdouble *
 299 adg_dash_get_dashes(const AdgDash *dash)
 300 {
 301     g_return_val_if_fail(dash != NULL, NULL);
 302     return dash->dashes;
 303 }
 304
 305 /**
 306  * adg_dash_clear_dashes:
 307  * @dash: an #AdgDash instance
 308  *
 309  * Resets the dashes of @dash, effectively clearing the pattern.
 310  *
 311  * Since: 1.0
 312  **/
 313 void
 314 adg_dash_clear_dashes(AdgDash *dash)
 315 {
 316     g_return_if_fail(dash != NULL);
 317
 318     g_free(dash->dashes);
 319     dash->dashes = NULL;
 320     dash->num_dashes = 0;
 321 }
 322
 323 /**
 324  * adg_dash_set_offset:
 325  * @dash: an #AdgDash instance
 326  * @offset: the new offset value
 327  *
 328  * Sets the pattern offset of @dash to @offset.
 329  *
 330  * Since: 1.0
 331  **/
 332 void
 333 adg_dash_set_offset(AdgDash *dash, gdouble offset)
 334 {
 335     g_return_if_fail(dash != NULL);
 336
 337     dash->offset = offset;
 338 }
 339
 340 /**
 341  * adg_dash_get_offset:
 342  * @dash: an #AdgDash instance
 343  *
 344  * Gets the offset of the pattern in @dash.
 345  *
 346  * Returns: the offset of @dash or 0 on invalid @dash.
 347  *
 348  * Since: 1.0
 349  **/
 350 gdouble
 351 adg_dash_get_offset(const AdgDash *dash)
 352 {
 353     g_return_val_if_fail(dash != NULL, 0);
 354     return dash->offset;
 355 }
 356
 357 /**
 358  * adg_dash_destroy:
 359  * @dash: an #AdgDash instance
 360  *
 361  * Destroys @dash, freeing every resource owned by it. After the destruction
 362  * @dash cannot be used anymore.
 363  *
 364  * Since: 1.0
 365  **/
 366 void
 367 adg_dash_destroy(AdgDash *dash)
 368 {
 369     g_return_if_fail(dash != NULL);
 370
 371     g_free(dash->dashes);
 372     g_free(dash);
 373 }