src/adg/adg-point.c

   1 /* ADG - Automatic Drawing Generation
   2  * Copyright (C) 2007,2008,2009,2010,2011,2012  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-point
  23  * @Section_Id:AdgPoint
  24  * @title: AdgPoint
  25  * @short_description: A struct holding x, y coordinates
  26  *                     (either named or explicit)
  27  *
  28  * AdgPoint is an opaque structure that manages 2D coordinates,
  29  * either set explicitely throught adg_point_set_pair() and
  30  * adg_point_set_pair_explicit() or taken from a model with
  31  * adg_point_set_pair_from_model(). It can be thought as an
  32  * #AdgPair on steroid, because it adds named pair support to
  33  * a simple pair, enabling coordinates depending on #AdgModel.
  34  *
  35  * Since: 1.0
  36  **/
  37
  38 /**
  39  * AdgPoint:
  40  *
  41  * This is an opaque struct: all its fields are privates.
  42  *
  43  * Since: 1.0
  44  **/
  45
  46
  47 #include "adg-internal.h"
  48 #include "adg-model.h"
  49 #include <string.h>
  50
  51 #include "adg-point.h"
  52
  53
  54 struct _AdgPoint {
  55     AdgPair      pair;
  56     AdgModel    *model;
  57     gchar       *name;
  58     gboolean     is_uptodate;
  59 };
  60
  61
  62 GType
  63 adg_point_get_type(void)
  64 {
  65     static int type = 0;
  66
  67     if (G_UNLIKELY(type == 0))
  68         type = g_boxed_type_register_static("AdgPoint",
  69                                             (GBoxedCopyFunc) adg_point_dup,
  70                                             (GBoxedFreeFunc) adg_point_destroy);
  71
  72     return type;
  73 }
  74
  75 /**
  76  * adg_point_new:
  77  *
  78  * Creates a new empty #AdgPoint. The returned pointer
  79  * should be freed with adg_point_destroy() when no longer needed.
  80  *
  81  * Returns: a newly created #AdgPoint
  82  *
  83  * Since: 1.0
  84  **/
  85 AdgPoint *
  86 adg_point_new(void)
  87 {
  88     return g_new0(AdgPoint, 1);
  89 }
  90
  91 /**
  92  * adg_point_dup:
  93  * @src: an #AdgPoint
  94  *
  95  * Duplicates @src. This operation also adds a new reference
  96  * to the internal model if @src is linked to a named pair.
  97  *
  98  * The returned value should be freed with adg_point_destroy()
  99  * when no longer needed.
 100  *
 101  * Returns: the duplicated #AdgPoint struct or %NULL on errors
 102  *
 103  * Since: 1.0
 104  **/
 105 AdgPoint *
 106 adg_point_dup(const AdgPoint *src)
 107 {
 108     AdgPoint *point;
 109
 110     g_return_val_if_fail(src != NULL, NULL);
 111
 112     if (src->model)
 113         g_object_ref(src->model);
 114
 115     point = g_memdup(src, sizeof(AdgPoint));
 116     point->name = g_strdup(src->name);
 117
 118     return point;
 119 }
 120
 121 /**
 122  * adg_point_destroy:
 123  * @point: an #AdgPoint
 124  *
 125  * Destroys the @point instance, unreferencing the internal model if
 126  * @point is linked to a named pair.
 127  *
 128  * Since: 1.0
 129  **/
 130 void
 131 adg_point_destroy(AdgPoint *point)
 132 {
 133     g_return_if_fail(point != NULL);
 134
 135     adg_point_unset(point);
 136     g_free(point);
 137 }
 138
 139 /**
 140  * adg_point_copy:
 141  * @point: an #AdgPoint
 142  * @src: the source point to copy
 143  *
 144  * Copies @src into @point. If the old content of @point was linked
 145  * to the named pair of a model, the reference to that model is
 146  * dropped. Similary, if @src is a named pair, a new reference to
 147  * the new model is added.
 148  *
 149  * Since: 1.0
 150  **/
 151 void
 152 adg_point_copy(AdgPoint *point, const AdgPoint *src)
 153 {
 154     g_return_if_fail(point != NULL);
 155     g_return_if_fail(src != NULL);
 156
 157     if (src->model != NULL)
 158         g_object_ref(src->model);
 159
 160     if (point->model != NULL)
 161         g_object_unref(point->model);
 162
 163     if (point->name != NULL)
 164         g_free(point->name);
 165
 166     memcpy(point, src, sizeof(AdgPoint));
 167     point->name = g_strdup(src->name);
 168 }
 169
 170 /**
 171  * adg_point_set_pair:
 172  * @point: an #AdgPoint
 173  * @pair: the #AdgPair to use
 174  *
 175  * Sets an explicit pair in @point by using the given @pair. If
 176  * @point was linked to a named pair in a model, this link is
 177  * dropped before setting the pair.
 178  *
 179  * Since: 1.0
 180  **/
 181 void
 182 adg_point_set_pair(AdgPoint *point, const AdgPair *pair)
 183 {
 184     g_return_if_fail(point != NULL);
 185     g_return_if_fail(pair != NULL);
 186
 187     adg_point_set_pair_explicit(point, pair->x, pair->y);
 188 }
 189
 190 /**
 191  * adg_point_set_pair_explicit:
 192  * @point: an #AdgPoint
 193  * @x: the x coordinate of the point
 194  * @y: the y coordinate of the point
 195  *
 196  * Works in the same way of adg_point_set_pair() but accept direct numbers
 197  * instead of an #AdgPair structure.
 198  *
 199  * Since: 1.0
 200  **/
 201 void
 202 adg_point_set_pair_explicit(AdgPoint *point, gdouble x, gdouble y)
 203 {
 204     g_return_if_fail(point != NULL);
 205
 206     adg_point_unset(point);
 207     point->pair.x = x;
 208     point->pair.y = y;
 209     point->is_uptodate = TRUE;
 210 }
 211
 212 /**
 213  * adg_point_set_pair_from_model:
 214  * @point: an #AdgPoint
 215  * @model: the #AdgModel
 216  * @name: the id of a named pair in @model
 217  *
 218  * Links the @name named pair of @model to @point, so any subsequent
 219  * call to adg_point_get_pair() will return the named pair value.
 220  * A new reference is added to @model while the previous model (if any)
 221  * is unreferenced.
 222  *
 223  * Since: 1.0
 224  **/
 225 void
 226 adg_point_set_pair_from_model(AdgPoint *point,
 227                               AdgModel *model, const gchar *name)
 228 {
 229     g_return_if_fail(point != NULL);
 230     g_return_if_fail(ADG_IS_MODEL(model));
 231     g_return_if_fail(name != NULL);
 232
 233     /* Return if the new named pair is the same of the old one */
 234     if (model == point->model && strcmp(point->name, name) == 0)
 235         return;
 236
 237     g_object_ref(model);
 238
 239     if (point->model) {
 240         /* Remove the old named pair */
 241         g_object_unref(point->model);
 242         g_free(point->name);
 243     }
 244
 245     /* Set the new named pair */
 246     point->is_uptodate = FALSE;
 247     point->model = model;
 248     point->name = g_strdup(name);
 249 }
 250
 251 /**
 252  * adg_point_unset:
 253  * @point: a pointer to an #AdgPoint
 254  *
 255  * Unsets @point by resetting the internal "is_uptodate" flag.
 256  * This also means @point is unlinked from the model if it is
 257  * a named pair. In any cases, after this call the content of
 258  * @point is undefined, that is calling adg_point_get_pair()
 259  * will return %NULL.
 260  *
 261  * Since: 1.0
 262  **/
 263 void
 264 adg_point_unset(AdgPoint *point)
 265 {
 266     g_return_if_fail(point != NULL);
 267
 268     if (point->model) {
 269         /* Remove the old named pair */
 270         g_object_unref(point->model);
 271         g_free(point->name);
 272     }
 273
 274     point->is_uptodate = FALSE;
 275     point->model = NULL;
 276     point->name = NULL;
 277 }
 278
 279 /**
 280  * adg_point_get_pair:
 281  * @point: an #AdgPoint
 282  *
 283  * #AdgPoint is an evolution of the pair concept but internally the
 284  * relevant data is still stored in an #AdgPair struct. This function
 285  * gets the pointer to this struct, updating the value prior to
 286  * return it if needed (that is, if @point is linked to a not up
 287  * to date named pair).
 288  *
 289  * Returns: the pair of @point or %NULL if the named pair does not exist
 290  *
 291  * Since: 1.0
 292  **/
 293 const AdgPair *
 294 adg_point_get_pair(AdgPoint *point)
 295 {
 296     g_return_val_if_fail(point != NULL, NULL);
 297
 298     if (!point->is_uptodate) {
 299         const AdgPair *pair;
 300
 301         if (point->model == NULL) {
 302             /* A point with explicit coordinates not up to date
 303              * is an unexpected condition */
 304             g_warning(_("%s: trying to get a pair from an undefined point"),
 305                       G_STRLOC);
 306             return NULL;
 307         }
 308
 309         pair = adg_model_get_named_pair(point->model, point->name);
 310
 311         /* "Named pair not found" condition: return NULL without warnings */
 312         if (pair == NULL)
 313             return NULL;
 314
 315         cpml_pair_copy(&point->pair, pair);
 316         point->is_uptodate = TRUE;
 317     }
 318
 319     return (AdgPair *) point;
 320 }
 321
 322 /**
 323  * adg_point_get_model:
 324  * @point: an #AdgPoint
 325  *
 326  * Gets the source model of the named pair bound to @point, or
 327  * returns %NULL if @point is an explicit pair. The returned
 328  * value is owned by @point.
 329  *
 330  * Returns: (transfer none): an #AdgModel or %NULL.
 331  *
 332  * Since: 1.0
 333  **/
 334 AdgModel *
 335 adg_point_get_model(AdgPoint *point)
 336 {
 337     g_return_val_if_fail(point != NULL, NULL);
 338     return point->model;
 339 }
 340
 341 /**
 342  * adg_point_get_name:
 343  * @point: an #AdgPoint
 344  *
 345  * Gets the name of the named pair bound to @point, or returns
 346  * %NULL if @point is an explicit pair. The returned value is
 347  * owned by @point and should not be modified or freed.
 348  *
 349  * Returns: the name of the named pair or %NULL
 350  *
 351  * Since: 1.0
 352  **/
 353 const gchar *
 354 adg_point_get_name(AdgPoint *point)
 355 {
 356     g_return_val_if_fail(point != NULL, NULL);
 357     return point->name;
 358 }
 359
 360 /**
 361  * adg_point_invalidate:
 362  * @point: an #AdgPoint
 363  *
 364  * Invalidates @point, forcing a refresh of its internal #AdgPair if
 365  * the point is linked to a named pair. If @point is explicitely set,
 366  * this function has no effect.
 367  *
 368  * Since: 1.0
 369  **/
 370 void
 371 adg_point_invalidate(AdgPoint *point)
 372 {
 373     g_return_if_fail(point != NULL);
 374
 375     if (point->model)
 376         point->is_uptodate = FALSE;
 377 }
 378
 379 /**
 380  * adg_point_equal:
 381  * @point1: the first point to compare
 382  * @point2: the second point to compare
 383  *
 384  * Compares @point1 and @point2 and returns %TRUE if the points are
 385  * equals. The comparison is made by matching also where the points
 386  * are bound. If you want to compare only the coordinates, use
 387  * cpml_pair_equal() directly on their pairs:
 388  *
 389  * |[
 390  * cpml_pair_equal(adg_point_get_pair(point1), adg_point_get_pair(point2));
 391  * ]|
 392  *
 393  * %NULL values are handled gracefully.
 394  *
 395  * Returns: %TRUE if @point1 is equal to @point2, %FALSE otherwise
 396  *
 397  * Since: 1.0
 398  **/
 399 gboolean
 400 adg_point_equal(const AdgPoint *point1, const AdgPoint *point2)
 401 {
 402     if (point1 == point2)
 403         return TRUE;
 404
 405     if (point1 == NULL || point2 == NULL)
 406         return FALSE;
 407
 408     /* Check if the points are not bound to the same model
 409      * or if only one of the two points is explicit */
 410     if (point1->model != point2->model)
 411         return FALSE;
 412
 413     /* Handle points bound to named pairs */
 414     if (point1->model)
 415         return g_strcmp0(point1->name, point2->name) == 0;
 416
 417     /* Handle points with explicit coordinates */
 418     return cpml_pair_equal(&point1->pair, &point2->pair);
 419 }