adg/adg-point.c

   1 /* ADG - Automatic Drawing Generation
   2  * Copyright (C) 2007,2008,2009 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-point.h"
  44 #include "adg-intl.h"
  45
  46 #include <string.h>
  47
  48
  49 struct _AdgPoint {
  50     AdgPair      pair;
  51     AdgModel    *model;
  52     gchar       *name;
  53     gboolean     is_uptodate;
  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_dup:
  71  * @point: an #AdgPoint structure
  72  *
  73  * Duplicates @point. This operation also adds a new reference
  74  * to the internal model if @point is linked to a named pair.
  75  *
  76  * The returned value should be freed with adg_point_destroy()
  77  * when no longer needed.
  78  *
  79  * Returns: the duplicated #AdgPoint struct or %NULL on errors
  80  **/
  81 AdgPoint *
  82 adg_point_dup(const AdgPoint *point)
  83 {
  84     g_return_val_if_fail(point != NULL, NULL);
  85
  86     if (point->model != NULL)
  87         g_object_ref(point->model);
  88
  89     return g_memdup(point, sizeof(AdgPoint));
  90 }
  91
  92 /**
  93  * adg_point_new:
  94  *
  95  * Creates a new empty #AdgPoint. The returned pointer
  96  * should be freed with adg_point_destroy() when no longer needed.
  97  *
  98  * The returned value should be freed with adg_point_destroy()
  99  * when no longer needed.
 100  *
 101  * Returns: a newly created #AdgPoint
 102  **/
 103 AdgPoint *
 104 adg_point_new(void)
 105 {
 106     return g_new0(AdgPoint, 1);
 107 }
 108
 109 /**
 110  * adg_point_destroy:
 111  * @point: an #AdgPoint
 112  *
 113  * Destroys the @point instance, unreferencing the internal model if
 114  * @point is linked to a named pair.
 115  **/
 116 void
 117 adg_point_destroy(AdgPoint *point)
 118 {
 119     g_return_if_fail(point != NULL);
 120
 121     adg_point_set_pair_from_model(point, NULL, NULL);
 122
 123     g_free(point);
 124 }
 125
 126 /**
 127  * adg_point_copy:
 128  * @point: an #AdgPoint
 129  * @src: the source point to copy
 130  *
 131  * Copies @src into @point. If @point was linked to a named pair, the
 132  * reference to the old model is dropped. Similary, if @src is linked
 133  * to a model, a new reference to this new model is added.
 134  **/
 135 void
 136 adg_point_copy(AdgPoint *point, const AdgPoint *src)
 137 {
 138     g_return_if_fail(point != NULL);
 139     g_return_if_fail(src != NULL);
 140
 141     if (src->model != NULL)
 142         g_object_ref(src->model);
 143
 144     if (point->model != NULL)
 145         g_object_unref(point->model);
 146
 147     memcpy(point, src, sizeof(AdgPoint));
 148 }
 149
 150 /**
 151  * adg_point_set_pair:
 152  * @point: an #AdgPoint
 153  * @pair: the #AdgPair to use
 154  *
 155  * Sets an explicit pair in @point by using the given @pair. If
 156  * @point was linked to a named pair in a model, this link is
 157  * dropped before setting the pair.
 158  **/
 159 void
 160 adg_point_set_pair(AdgPoint *point, const AdgPair *pair)
 161 {
 162     g_return_if_fail(point != NULL);
 163     g_return_if_fail(pair != NULL);
 164
 165     adg_point_set_pair_explicit(point, pair->x, pair->y);
 166 }
 167
 168 /**
 169  * adg_point_set_pair_explicit:
 170  * @point: an #AdgPoint
 171  * @x: the x coordinate of the point
 172  * @y: the y coordinate of the point
 173  *
 174  * Works in the same way of adg_point_set_pair() but accept direct numbers
 175  * instead of an #AdgPair structure.
 176  **/
 177 void
 178 adg_point_set_pair_explicit(AdgPoint *point, gdouble x, gdouble y)
 179 {
 180     g_return_if_fail(point != NULL);
 181
 182     /* Unlink the named pair dependency, if any */
 183     adg_point_set_pair_from_model(point, NULL, NULL);
 184
 185     point->pair.x = x;
 186     point->pair.y = y;
 187     point->is_uptodate = TRUE;
 188 }
 189
 190 /**
 191  * adg_point_set_pair_from_model:
 192  * @point: an #AdgPoint
 193  * @model: the #AdgModel
 194  * @name: the id of a named pair in @model
 195  *
 196  * Links the @name named pair of @model to @point, so any subsequent
 197  * call to adg_point_update() will read the named pair content. A
 198  * new reference is added to @model while the previous model (if any)
 199  * is unreferenced.
 200  *
 201  * It is allowed to use %NULL as @model, in which case the link
 202  * between @point and the named pair is dropped.
 203  **/
 204 void
 205 adg_point_set_pair_from_model(AdgPoint *point,
 206                               AdgModel *model, const gchar *name)
 207 {
 208     g_return_if_fail(point != NULL);
 209     g_return_if_fail(model == NULL || name != NULL);
 210
 211     /* Check if unlinking a yet unlinked point */
 212     if (model == NULL && point->model == NULL)
 213         return;
 214
 215     /* Return if the named pair is not changed */
 216     if (model == point->model &&
 217         (model == NULL || strcmp(point->name, name) == 0)) {
 218         return;
 219     }
 220
 221     if (model != NULL)
 222         g_object_ref(model);
 223
 224     if (point->model != NULL) {
 225         /* Remove the old named pair */
 226         g_object_unref(point->model);
 227         g_free(point->name);
 228         point->model = NULL;
 229         point->name = NULL;
 230     }
 231
 232     point->is_uptodate = FALSE;
 233
 234     if (model != NULL) {
 235         /* Set the new named pair */
 236         point->model = model;
 237         point->name = g_strdup(name);
 238     }
 239 }
 240
 241 /**
 242  * adg_point_get_pair:
 243  * @point: an #AdgPoint
 244  *
 245  * #AdgPoint is an evolution of the pair concept, but internally the
 246  * relevant data is still stored in an #AdgPair struct. This function
 247  * gets this struct, optionally updating the internal value from the
 248  * linked named pair if necessary.
 249  *
 250  * Returns: the pair of @point
 251  **/
 252 const AdgPair *
 253 adg_point_get_pair(AdgPoint *point)
 254 {
 255     g_return_val_if_fail(point != NULL, NULL);
 256
 257     if (!point->is_uptodate) {
 258         const AdgPair *pair;
 259
 260         if (point->model == NULL) {
 261             /* A point with explicit coordinates not up to date
 262              * is an unexpected condition */
 263             g_warning(_("%s: trying to get a pair from an undefined point"),
 264                       G_STRLOC);
 265             return NULL;
 266         }
 267
 268         pair = adg_model_get_named_pair(point->model, point->name);
 269
 270         if (pair == NULL) {
 271             g_warning(_("%s: `%s' named pair not found in `%s' model instance"),
 272                       G_STRLOC, point->name,
 273                       g_type_name(G_TYPE_FROM_INSTANCE(point->model)));
 274             return NULL;
 275         }
 276
 277         cpml_pair_copy(&point->pair, pair);
 278     }
 279
 280     return (AdgPair *) point;
 281 }
 282
 283 /**
 284  * adg_point_invalidate:
 285  * @point: an #AdgPoint
 286  *
 287  * Invalidates @point, forcing a refresh of its internal #AdgPair if
 288  * the point is linked to a named pair. If @point is explicitely set,
 289  * this function has no effect.
 290  **/
 291 void
 292 adg_point_invalidate(AdgPoint *point)
 293 {
 294     g_return_if_fail(point != NULL);
 295
 296     if (point->model != NULL)
 297         point->is_uptodate = FALSE;
 298 }