src/adg/adg-dash.c

   1 /* ADG - Automatic Drawing Generation
   2  * Copyright (C) 2007,2008,2009,2010,2011,2012,2013  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  * @dash: an #AdgDash instance
  78  *
  79  * Duplicates @dash.
  80  *
  81  * Returns: (transfer full): the duplicate of @dash: must be freed with adg_dash_destroy() when no longer needed.
  82  *
  83  * Since: 1.0
  84  **/
  85 AdgDash *
  86 adg_dash_dup(const AdgDash *dash)
  87 {
  88     AdgDash *dup;
  89
  90     if (dash == NULL)
  91         return NULL;
  92
  93     dup = g_memdup(dash, sizeof(AdgDash));
  94     dup->dashes = g_memdup(dash->dashes, sizeof(gdouble) * dash->num_dashes);
  95
  96     return dup;
  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:
 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  * Rename to: adg_dash_append_dashes
 219  * Since: 1.0
 220  **/
 221 void
 222 adg_dash_append_dashes_array(AdgDash *dash,
 223                              gint num_dashes, const gdouble *dashes)
 224 {
 225     g_return_if_fail(dash != NULL);
 226
 227     if (num_dashes > 0) {
 228         gint old_dashes = dash->num_dashes;
 229         dash->num_dashes += num_dashes;
 230         dash->dashes = g_realloc(dash->dashes, sizeof(gdouble) * dash->num_dashes);
 231         memcpy(dash->dashes + old_dashes, dashes, sizeof(gdouble) * num_dashes);
 232     }
 233 }
 234
 235 /**
 236  * adg_dash_get_num_dashes:
 237  * @dash: an #AdgDash instance
 238  *
 239  * Gets the number of dashes stored inside this dash pattern.
 240  *
 241  * Returns: the number of dashes or %-1 if @dash is invalid.
 242  *
 243  * Since: 1.0
 244  **/
 245 gint
 246 adg_dash_get_num_dashes(const AdgDash *dash)
 247 {
 248     g_return_val_if_fail(dash != NULL, -1);
 249     return dash->num_dashes;
 250 }
 251
 252 /**
 253  * adg_dash_get_dashes:
 254  * @dash: an #AdgDash instance
 255  *
 256  * Gets the array of gdoubles containing the length of each dash of the
 257  * pattern of @dash.
 258  *
 259  * Returns: the array of lengths or %NULL on invalid @dash. The array is owned by @dash and must not be modified or freed.
 260  *
 261  * Since: 1.0
 262  **/
 263 const gdouble *
 264 adg_dash_get_dashes(const AdgDash *dash)
 265 {
 266     g_return_val_if_fail(dash != NULL, NULL);
 267     return dash->dashes;
 268 }
 269
 270 /**
 271  * adg_dash_clear_dashes:
 272  * @dash: an #AdgDash instance
 273  *
 274  * Resets the dashes of @dash, effectively clearing the pattern.
 275  *
 276  * Since: 1.0
 277  **/
 278 void
 279 adg_dash_clear_dashes(AdgDash *dash)
 280 {
 281     g_return_if_fail(dash != NULL);
 282
 283     g_free(dash->dashes);
 284     dash->dashes = NULL;
 285     dash->num_dashes = 0;
 286 }
 287
 288 /**
 289  * adg_dash_set_offset:
 290  * @dash: an #AdgDash instance
 291  * @offset: the new offset value
 292  *
 293  * Sets the pattern offset of @dash to @offset.
 294  *
 295  * Since: 1.0
 296  **/
 297 void
 298 adg_dash_set_offset(AdgDash *dash, gdouble offset)
 299 {
 300     g_return_if_fail(dash != NULL);
 301
 302     dash->offset = offset;
 303 }
 304
 305 /**
 306  * adg_dash_get_offset:
 307  * @dash: an #AdgDash instance
 308  *
 309  * Gets the offset of the pattern in @dash.
 310  *
 311  * Returns: the offset of @dash or %0 on invalid @dash.
 312  *
 313  * Since: 1.0
 314  **/
 315 gdouble
 316 adg_dash_get_offset(const AdgDash *dash)
 317 {
 318     g_return_val_if_fail(dash != NULL, 0);
 319     return dash->offset;
 320 }
 321
 322 /**
 323  * adg_dash_destroy:
 324  * @dash: an #AdgDash instance
 325  *
 326  * Destroys @dash, freeing every resource owned by it. After the destruction
 327  * @dash cannot be used anymore.
 328  *
 329  * Since: 1.0
 330  **/
 331 void
 332 adg_dash_destroy(AdgDash *dash)
 333 {
 334     g_return_if_fail(dash != NULL);
 335
 336     g_free(dash->dashes);
 337     g_free(dash);
 338 }