adg/adg-container.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-container
  23  * @short_description: Base class for entity that can contain other entities
  24  *
  25  * The #AdgContainer is an entity that can contains more sub-entities.
  26  * Moreover, it can apply a common transformation to local and/or global
  27  * maps: see http://adg.entidi.com/tutorial/view/3 for further details.
  28  **/
  29
  30 /**
  31  * AdgContainer:
  32  *
  33  * All fields are private and should not be used directly.
  34  * Use its public methods instead.
  35  **/
  36
  37 #include "adg-container.h"
  38 #include "adg-container-private.h"
  39 #include "adg-marshal.h"
  40 #include "adg-intl.h"
  41
  42 #define PARENT_OBJECT_CLASS  ((GObjectClass *) adg_container_parent_class)
  43 #define PARENT_ENTITY_CLASS  ((AdgEntityClass *) adg_container_parent_class)
  44
  45
  46 enum {
  47     PROP_0,
  48     PROP_CHILD
  49 };
  50
  51 enum {
  52     ADD,
  53     REMOVE,
  54     LAST_SIGNAL
  55 };
  56
  57
  58 static void             dispose                 (GObject        *object);
  59 static void             set_property            (GObject        *object,
  60                                                  guint           prop_id,
  61                                                  const GValue   *value,
  62                                                  GParamSpec     *pspec);
  63 static void             global_changed          (AdgEntity      *entity);
  64 static void             local_changed           (AdgEntity      *entity);
  65 static void             invalidate              (AdgEntity      *entity);
  66 static void             arrange                 (AdgEntity      *entity);
  67 static void             add_extents             (AdgEntity      *entity,
  68                                                  CpmlExtents    *container_extents);
  69 static void             render                  (AdgEntity      *entity,
  70                                                  cairo_t        *cr);
  71 static GSList *         get_children            (AdgContainer   *container);
  72 static void             add                     (AdgContainer   *container,
  73                                                  AdgEntity      *entity);
  74 static void             remove                  (AdgContainer   *container,
  75                                                  AdgEntity      *entity);
  76
  77 static guint signals[LAST_SIGNAL] = { 0 };
  78
  79
  80 G_DEFINE_TYPE(AdgContainer, adg_container, ADG_TYPE_ENTITY);
  81
  82
  83 static void
  84 adg_container_class_init(AdgContainerClass *klass)
  85 {
  86     GObjectClass *gobject_class;
  87     AdgEntityClass *entity_class;
  88     GParamSpec *param;
  89
  90     gobject_class = (GObjectClass *) klass;
  91     entity_class = (AdgEntityClass *) klass;
  92
  93     g_type_class_add_private(klass, sizeof(AdgContainerPrivate));
  94
  95     gobject_class->dispose = dispose;
  96     gobject_class->set_property = set_property;
  97
  98     entity_class->global_changed = global_changed;
  99     entity_class->local_changed = local_changed;
 100     entity_class->invalidate = invalidate;
 101     entity_class->arrange = arrange;
 102     entity_class->render = render;
 103
 104     klass->get_children = get_children;
 105     klass->add = add;
 106     klass->remove = remove;
 107
 108     param = g_param_spec_object("child",
 109                                 P_("Child"),
 110                                 P_("Can be used to add a new child to the container"),
 111                                 ADG_TYPE_ENTITY, G_PARAM_WRITABLE);
 112     g_object_class_install_property(gobject_class, PROP_CHILD, param);
 113
 114     /**
 115      * AdgContainer::add:
 116      * @container: an #AdgContainer
 117      * @entity: the #AdgEntity to add
 118      *
 119      * Adds @entity to @container. @entity must not be inside another
 120      * container or the operation will fail.
 121      **/
 122     signals[ADD] = g_signal_new("add",
 123                                 G_OBJECT_CLASS_TYPE(gobject_class),
 124                                 G_SIGNAL_RUN_FIRST,
 125                                 G_STRUCT_OFFSET(AdgContainerClass, add),
 126                                 NULL, NULL,
 127                                 adg_marshal_VOID__OBJECT,
 128                                 G_TYPE_NONE, 1, ADG_TYPE_ENTITY);
 129
 130     /**
 131      * AdgContainer::remove:
 132      * @container: an #AdgContainer
 133      * @entity: the #AdgEntity to remove
 134      *
 135      * Removes @entity from @container.
 136      **/
 137     signals[REMOVE] = g_signal_new("remove",
 138                                    G_OBJECT_CLASS_TYPE(gobject_class),
 139                                    G_SIGNAL_RUN_FIRST,
 140                                    G_STRUCT_OFFSET(AdgContainerClass, remove),
 141                                    NULL, NULL,
 142                                    adg_marshal_VOID__OBJECT,
 143                                    G_TYPE_NONE, 1, ADG_TYPE_ENTITY);
 144 }
 145
 146 static void
 147 adg_container_init(AdgContainer *container)
 148 {
 149     AdgContainerPrivate *data = G_TYPE_INSTANCE_GET_PRIVATE(container,
 150                                                             ADG_TYPE_CONTAINER,
 151                                                             AdgContainerPrivate);
 152
 153     data->children = NULL;
 154
 155     container->data = data;
 156 }
 157
 158 static void
 159 dispose(GObject *object)
 160 {
 161     AdgContainer *container;
 162     AdgContainerPrivate *data;
 163
 164     container = (AdgContainer *) object;
 165     data = container->data;
 166
 167     /* Remove all the children from the container: these will emit
 168      * a "remove" signal for every child and will drop all the
 169      * references from the children to this container (and, obviously,
 170      * from the container to the children). */
 171     while (data->children != NULL)
 172         adg_container_remove(container, (AdgEntity *) data->children->data);
 173
 174     if (PARENT_OBJECT_CLASS->dispose)
 175         PARENT_OBJECT_CLASS->dispose(object);
 176 }
 177
 178 static void
 179 set_property(GObject *object,
 180              guint prop_id, const GValue *value, GParamSpec *pspec)
 181 {
 182     AdgContainer *container = (AdgContainer *) object;
 183
 184     switch (prop_id) {
 185     case PROP_CHILD:
 186         adg_container_add(container, g_value_get_object(value));
 187         break;
 188     default:
 189         G_OBJECT_WARN_INVALID_PROPERTY_ID(object, prop_id, pspec);
 190     }
 191 }
 192
 193
 194 /**
 195  * adg_container_new:
 196  *
 197  * Creates a new container entity.
 198  *
 199  * Returns: the newly created container entity
 200  **/
 201 AdgContainer *
 202 adg_container_new(void)
 203 {
 204     return g_object_new(ADG_TYPE_CONTAINER, NULL);
 205 }
 206
 207
 208 /**
 209  * adg_container_add:
 210  * @container: an #AdgContainer
 211  * @entity: an #AdgEntity
 212  *
 213  * Emits a #AdgContainer::add signal on @container passing @entity
 214  * as argument. @entity must be added to only one container at a time,
 215  * you can't place the same entity inside two different containers.
 216  *
 217  * Once @entity has been added, the floating reference will be removed
 218  * and @container will own a reference to @entity. This means the only
 219  * proper way to destroy @entity is to call adg_container_remove().
 220  **/
 221 void
 222 adg_container_add(AdgContainer *container, AdgEntity *entity)
 223 {
 224     g_return_if_fail(ADG_IS_CONTAINER(container));
 225     g_return_if_fail(ADG_IS_ENTITY(entity));
 226
 227     g_signal_emit(container, signals[ADD], 0, entity);
 228 }
 229
 230 /**
 231  * adg_container_remove:
 232  * @container: an #AdgContainer
 233  * @entity: an #AdgEntity
 234  *
 235  * Emits a #AdgContainer::remove signal on @container passing
 236  * @entity as argument. @entity must be inside @container.
 237  *
 238  * Note that @container will own a reference to @entity and it
 239  * may be the last reference held: this means removing an entity
 240  * from its container can destroy it.
 241  *
 242  * If you want to use @entity again, you need to add a reference
 243  * to it, using g_object_ref(), before removing it from @container.
 244  * The following typical example shows you how to properly move
 245  * <varname>entity</varname> from <varname>container1</varname>
 246  * to <varname>container2</varname>:
 247  *
 248  * |[
 249  * g_object_ref(entity);
 250  * adg_container_remove(container1, entity);
 251  * adg_container_add(container2, entity)
 252  * g_object_unref(entity);
 253  * ]|
 254  **/
 255 void
 256 adg_container_remove(AdgContainer *container, AdgEntity *entity)
 257 {
 258     g_return_if_fail(ADG_IS_CONTAINER(container));
 259     g_return_if_fail(ADG_IS_ENTITY(entity));
 260
 261     g_signal_emit(container, signals[REMOVE], 0, entity);
 262 }
 263
 264 /**
 265  * adg_container_get_children:
 266  * @container: an #AdgContainer
 267  *
 268  * Gets the children list of @container. This list must be manually
 269  * freed with g_slist_free() when no longer user.
 270  *
 271  * The returned list is ordered from the most recently added child
 272  * to the oldest one.
 273  *
 274  * Returns: a newly allocated #GSList or %NULL empty list or on errors
 275  **/
 276 GSList *
 277 adg_container_get_children(AdgContainer *container)
 278 {
 279     AdgContainerClass *klass;
 280
 281     g_return_val_if_fail(ADG_IS_CONTAINER(container), NULL);
 282
 283     klass = ADG_CONTAINER_GET_CLASS(container);
 284
 285     if (klass->get_children == NULL)
 286         return NULL;
 287
 288     return klass->get_children(container);
 289 }
 290
 291 /**
 292  * adg_container_foreach:
 293  * @container: an #AdgContainer
 294  * @callback: a callback
 295  * @user_data: callback user data
 296  *
 297  * Invokes @callback on each child of @container.
 298  * The callback should be declared as:
 299  *
 300  * |[
 301  * void callback(AdgEntity *entity, gpointer user_data);
 302  * ]|
 303  **/
 304 void
 305 adg_container_foreach(AdgContainer *container,
 306                       GCallback callback, gpointer user_data)
 307 {
 308     GSList *children;
 309
 310     g_return_if_fail(ADG_IS_CONTAINER(container));
 311     g_return_if_fail(callback != NULL);
 312
 313     children = adg_container_get_children(container);
 314
 315     while (children != NULL) {
 316         if (children->data != NULL)
 317             ((void (*) (gpointer, gpointer)) callback) (children->data, user_data);
 318
 319         children = g_slist_delete_link(children, children);
 320     }
 321 }
 322
 323 /**
 324  * adg_container_propagate:
 325  * @container: an #AdgContainer
 326  * @signal_id: the signal id
 327  * @detail: the detail
 328  * @...: parameters to be passed to the signal, followed by a pointer
 329  *       to the allocated memory where to store the return type: if
 330  *       the signal is %G_TYPE_NONE (void return type), this trailing
 331  *       pointer should be omitted
 332  *
 333  * Emits the specified signal to all the children of @container
 334  * using g_signal_emit_valist() calls.
 335  **/
 336 void
 337 adg_container_propagate(AdgContainer *container,
 338                         guint signal_id, GQuark detail, ...)
 339 {
 340     va_list var_args;
 341
 342     va_start(var_args, detail);
 343     adg_container_propagate_valist(container, signal_id, detail, var_args);
 344     va_end(var_args);
 345 }
 346
 347 /**
 348  * adg_container_propagate_by_name:
 349  * @container: an #AdgContainer
 350  * @detailed_signal: a string of the form "signal-name::detail".
 351  * @...: parameters to be passed to the signal, followed by a pointer
 352  *       to the allocated memory where to store the return type: if
 353  *       the signal is %G_TYPE_NONE (void return type), this trailing
 354  *       pointer should be omitted
 355  *
 356  * Emits the specified signal to all the children of @container
 357  * using g_signal_emit_valist() calls.
 358  **/
 359 void
 360 adg_container_propagate_by_name(AdgContainer *container,
 361                                 const gchar *detailed_signal, ...)
 362 {
 363     guint   signal_id;
 364     GQuark  detail = 0;
 365     va_list var_args;
 366
 367     if (!g_signal_parse_name(detailed_signal, G_TYPE_FROM_INSTANCE(container),
 368                              &signal_id, &detail, FALSE)) {
 369         g_warning("%s: signal `%s' is invalid for instance `%p'",
 370                   G_STRLOC, detailed_signal, container);
 371         return;
 372     }
 373
 374     va_start(var_args, detailed_signal);
 375     adg_container_propagate_valist(container, signal_id, detail, var_args);
 376     va_end(var_args);
 377 }
 378
 379 /**
 380  * adg_container_propagate_valist:
 381  * @container: an #AdgContainer
 382  * @signal_id: the signal id
 383  * @detail: the detail
 384  * @var_args: parameters to be passed to the signal, followed by a
 385  *            pointer to the allocated memory where to store the
 386  *            return type: if the signal is %G_TYPE_NONE (void return
 387  *            type), this trailing pointer should be omitted
 388  *
 389  * Emits the specified signal to all the children of @container
 390  * using g_signal_emit_valist() calls.
 391  **/
 392 void
 393 adg_container_propagate_valist(AdgContainer *container,
 394                                guint signal_id, GQuark detail, va_list var_args)
 395 {
 396     GSList *children;
 397     va_list var_copy;
 398
 399     g_return_if_fail(ADG_IS_CONTAINER(container));
 400
 401     children = adg_container_get_children(container);
 402
 403     while (children != NULL) {
 404         if (children->data != NULL) {
 405             G_VA_COPY(var_copy, var_args);
 406             g_signal_emit_valist(children->data, signal_id, detail, var_copy);
 407         }
 408
 409         children = g_slist_delete_link(children, children);
 410     }
 411 }
 412
 413
 414 static void
 415 global_changed(AdgEntity *entity)
 416 {
 417     if (PARENT_ENTITY_CLASS->global_changed)
 418         PARENT_ENTITY_CLASS->global_changed(entity);
 419
 420     adg_container_propagate_by_name((AdgContainer *) entity, "global-changed");
 421 }
 422
 423 static void
 424 local_changed(AdgEntity *entity)
 425 {
 426     if (PARENT_ENTITY_CLASS->local_changed)
 427         PARENT_ENTITY_CLASS->local_changed(entity);
 428
 429     adg_container_propagate_by_name((AdgContainer *) entity, "local-changed");
 430 }
 431
 432 static void
 433 invalidate(AdgEntity *entity)
 434 {
 435     adg_container_propagate_by_name((AdgContainer *) entity, "invalidate");
 436 }
 437
 438 static void
 439 arrange(AdgEntity *entity)
 440 {
 441     AdgContainer *container = (AdgContainer *) entity;
 442     CpmlExtents extents = { 0 };
 443
 444     adg_container_propagate_by_name(container, "arrange", NULL);
 445     adg_container_foreach(container, G_CALLBACK(add_extents), &extents);
 446     adg_entity_set_extents(entity, &extents);
 447 }
 448
 449 static void
 450 add_extents(AdgEntity *entity, CpmlExtents *container_extents)
 451 {
 452     cpml_extents_add(container_extents, adg_entity_get_extents(entity));
 453 }
 454
 455 static void
 456 render(AdgEntity *entity, cairo_t *cr)
 457 {
 458     adg_container_propagate_by_name((AdgContainer *) entity, "render", cr);
 459 }
 460
 461
 462 static GSList *
 463 get_children(AdgContainer *container)
 464 {
 465     AdgContainerPrivate *data = container->data;
 466
 467     /* The NULL case is yet managed by GLib */
 468     return g_slist_copy(data->children);
 469 }
 470
 471 static void
 472 add(AdgContainer *container, AdgEntity *entity)
 473 {
 474     const AdgEntity *old_parent;
 475     AdgContainerPrivate *data;
 476
 477     old_parent = adg_entity_get_parent(entity);
 478     if (old_parent != NULL) {
 479         g_warning("Attempting to add an entity with type %s to a container "
 480                   "of type %s, but the entity is already inside a container "
 481                   "of type %s.",
 482                   g_type_name(G_OBJECT_TYPE(entity)),
 483                   g_type_name(G_OBJECT_TYPE(container)),
 484                   g_type_name(G_OBJECT_TYPE(old_parent)));
 485         return;
 486     }
 487
 488     data = container->data;
 489     data->children = g_slist_prepend(data->children, entity);
 490
 491     g_object_ref_sink(entity);
 492     adg_entity_set_parent(entity, (AdgEntity *) container);
 493 }
 494
 495 static void
 496 remove(AdgContainer *container, AdgEntity *entity)
 497 {
 498     AdgContainerPrivate *data;
 499     GSList *node;
 500
 501     data = container->data;
 502     node = g_slist_find(data->children, entity);
 503
 504     if (node == NULL) {
 505         g_warning("Attempting to remove an entity with type %s from a "
 506                   "container of type %s, but the entity is not present.",
 507                   g_type_name(G_OBJECT_TYPE(entity)),
 508                   g_type_name(G_OBJECT_TYPE(container)));
 509         return;
 510     }
 511
 512     data->children = g_slist_delete_link(data->children, node);
 513     adg_entity_set_parent(entity, NULL);
 514     g_object_unref(entity);
 515 }