src/adg/adg-dash.c

   1 /* ADG - Automatic Drawing Generation
   2  * Copyright (C) 2007-2017  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     dash = adg_dash_new();
 138
 139     va_start(var_args, num_dashes);
 140     adg_dash_append_dashes_valist(dash, num_dashes, var_args);
 141     va_end(var_args);
 142
 143     return dash;
 144 }
 145
 146 /**
 147  * adg_dash_append_dash:
 148  * @dash: an #AdgDash instance
 149  * @length: the length value
 150  *
 151  * Appends to the @dash pattern a new dash of the specified @length value.
 152  *
 153  * Since: 1.0
 154  **/
 155 void
 156 adg_dash_append_dash(AdgDash *dash, gdouble length)
 157 {
 158     g_return_if_fail(dash != NULL);
 159
 160     ++ dash->num_dashes;
 161     dash->dashes = g_realloc(dash->dashes, sizeof(gdouble) * dash->num_dashes);
 162     dash->dashes[dash->num_dashes - 1] = length;
 163 }
 164
 165 /**
 166  * adg_dash_append_dashes:
 167  * @dash: an #AdgDash instance
 168  * @num_dashes: number of dashes to append
 169  * @...: a @num_dashes list of #gdouble
 170  *
 171  * Appends to the current @dash pattern @num_dashes number of dashes.
 172  * The length of each dash must be specified as gdouble in the arguments.
 173  *
 174  * Since: 1.0
 175  **/
 176 void
 177 adg_dash_append_dashes(AdgDash *dash, gint num_dashes, ...)
 178 {
 179     va_list var_args;
 180
 181     va_start(var_args, num_dashes);
 182     adg_dash_append_dashes_valist(dash, num_dashes,  var_args);
 183     va_end(var_args);
 184 }
 185
 186 /**
 187  * adg_dash_append_dashes_valist:
 188  * @dash: an #AdgDash instance
 189  * @num_dashes: number of dashes to append
 190  * @var_args: a va_list containing @num_dashes list of #gdouble
 191  *
 192  * Variadic version of adg_dash_append_dashes().
 193  *
 194  * Since: 1.0
 195  **/
 196 void
 197 adg_dash_append_dashes_valist(AdgDash *dash, gint num_dashes, va_list var_args)
 198 {
 199     gdouble length;
 200
 201     g_return_if_fail(dash != NULL);
 202     g_return_if_fail(num_dashes > 0);
 203
 204     while (num_dashes --) {
 205         length = va_arg(var_args, gdouble);
 206         adg_dash_append_dash(dash, length);
 207     }
 208 }
 209
 210 /**
 211  * adg_dash_append_dashes_array: (rename-to adg_dash_append_dashes)
 212  * @dash: an #AdgDash instance
 213  * @num_dashes: number of dashes to append
 214  * @dashes: (array length=num_dashes): array of @num_dashes gdoubles
 215  *
 216  * Array version of adg_dash_append_dashes().
 217  *
 218  * Since: 1.0
 219  **/
 220 void
 221 adg_dash_append_dashes_array(AdgDash *dash,
 222                              gint num_dashes, const gdouble *dashes)
 223 {
 224     g_return_if_fail(dash != NULL);
 225
 226     if (num_dashes > 0) {
 227         gint old_dashes = dash->num_dashes;
 228         dash->num_dashes += num_dashes;
 229         dash->dashes = g_realloc(dash->dashes, sizeof(gdouble) * dash->num_dashes);
 230         memcpy(dash->dashes + old_dashes, dashes, sizeof(gdouble) * num_dashes);
 231     }
 232 }
 233
 234 /**
 235  * adg_dash_get_num_dashes:
 236  * @dash: an #AdgDash instance
 237  *
 238  * Gets the number of dashes stored inside this dash pattern.
 239  *
 240  * Returns: the number of dashes or -1 if @dash is invalid.
 241  *
 242  * Since: 1.0
 243  **/
 244 gint
 245 adg_dash_get_num_dashes(const AdgDash *dash)
 246 {
 247     g_return_val_if_fail(dash != NULL, -1);
 248     return dash->num_dashes;
 249 }
 250
 251 /**
 252  * adg_dash_get_dashes:
 253  * @dash: an #AdgDash instance
 254  *
 255  * Gets the array of gdoubles containing the length of each dash of the
 256  * pattern of @dash.
 257  *
 258  * 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.
 259  *
 260  * Since: 1.0
 261  **/
 262 const gdouble *
 263 adg_dash_get_dashes(const AdgDash *dash)
 264 {
 265     g_return_val_if_fail(dash != NULL, NULL);
 266     return dash->dashes;
 267 }
 268
 269 /**
 270  * adg_dash_clear_dashes:
 271  * @dash: an #AdgDash instance
 272  *
 273  * Resets the dashes of @dash, effectively clearing the pattern.
 274  *
 275  * Since: 1.0
 276  **/
 277 void
 278 adg_dash_clear_dashes(AdgDash *dash)
 279 {
 280     g_return_if_fail(dash != NULL);
 281
 282     g_free(dash->dashes);
 283     dash->dashes = NULL;
 284     dash->num_dashes = 0;
 285 }
 286
 287 /**
 288  * adg_dash_set_offset:
 289  * @dash: an #AdgDash instance
 290  * @offset: the new offset value
 291  *
 292  * Sets the pattern offset of @dash to @offset.
 293  *
 294  * Since: 1.0
 295  **/
 296 void
 297 adg_dash_set_offset(AdgDash *dash, gdouble offset)
 298 {
 299     g_return_if_fail(dash != NULL);
 300
 301     dash->offset = offset;
 302 }
 303
 304 /**
 305  * adg_dash_get_offset:
 306  * @dash: an #AdgDash instance
 307  *
 308  * Gets the offset of the pattern in @dash.
 309  *
 310  * Returns: the offset of @dash or 0 on invalid @dash.
 311  *
 312  * Since: 1.0
 313  **/
 314 gdouble
 315 adg_dash_get_offset(const AdgDash *dash)
 316 {
 317     g_return_val_if_fail(dash != NULL, 0);
 318     return dash->offset;
 319 }
 320
 321 /**
 322  * adg_dash_destroy:
 323  * @dash: an #AdgDash instance
 324  *
 325  * Destroys @dash, freeing every resource owned by it. After the destruction
 326  * @dash cannot be used anymore.
 327  *
 328  * Since: 1.0
 329  **/
 330 void
 331 adg_dash_destroy(AdgDash *dash)
 332 {
 333     g_return_if_fail(dash != NULL);
 334
 335     g_free(dash->dashes);
 336     g_free(dash);
 337 }