src/adg/adg-point.c

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