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 != NULL)
 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     g_return_val_if_fail(ADG_IS_CONTAINER(container), NULL);
 280
 281     return ADG_CONTAINER_GET_CLASS(container)->get_children(container);
 282 }
 283
 284 /**
 285  * adg_container_foreach:
 286  * @container: an #AdgContainer
 287  * @callback: a callback
 288  * @user_data: callback user data
 289  *
 290  * Invokes @callback on each child of @container.
 291  * The callback should be declared as:
 292  *
 293  * |[
 294  * void callback(AdgEntity *entity, gpointer user_data);
 295  * ]|
 296  **/
 297 void
 298 adg_container_foreach(AdgContainer *container,
 299                       GCallback callback, gpointer user_data)
 300 {
 301     GSList *children;
 302
 303     g_return_if_fail(ADG_IS_CONTAINER(container));
 304     g_return_if_fail(callback != NULL);
 305
 306     children = adg_container_get_children(container);
 307
 308     while (children != NULL) {
 309         if (children->data != NULL)
 310             ((void (*) (gpointer, gpointer)) callback) (children->data, user_data);
 311
 312         children = g_slist_delete_link(children, children);
 313     }
 314 }
 315
 316 /**
 317  * adg_container_propagate:
 318  * @container: an #AdgContainer
 319  * @signal_id: the signal id
 320  * @detail: the detail
 321  * @...: parameters to be passed to the signal, followed by a pointer
 322  *       to the allocated memory where to store the return type: if
 323  *       the signal is %G_TYPE_NONE (void return type), this trailing
 324  *       pointer should be omitted
 325  *
 326  * Emits the specified signal to all the children of @container
 327  * using g_signal_emit_valist() calls.
 328  **/
 329 void
 330 adg_container_propagate(AdgContainer *container,
 331                         guint signal_id, GQuark detail, ...)
 332 {
 333     va_list var_args;
 334
 335     va_start(var_args, detail);
 336     adg_container_propagate_valist(container, signal_id, detail, var_args);
 337     va_end(var_args);
 338 }
 339
 340 /**
 341  * adg_container_propagate_by_name:
 342  * @container: an #AdgContainer
 343  * @detailed_signal: a string of the form "signal-name::detail".
 344  * @...: parameters to be passed to the signal, followed by a pointer
 345  *       to the allocated memory where to store the return type: if
 346  *       the signal is %G_TYPE_NONE (void return type), this trailing
 347  *       pointer should be omitted
 348  *
 349  * Emits the specified signal to all the children of @container
 350  * using g_signal_emit_valist() calls.
 351  **/
 352 void
 353 adg_container_propagate_by_name(AdgContainer *container,
 354                                 const gchar *detailed_signal, ...)
 355 {
 356     guint   signal_id;
 357     GQuark  detail = 0;
 358     va_list var_args;
 359
 360     if (!g_signal_parse_name(detailed_signal, G_TYPE_FROM_INSTANCE(container),
 361                              &signal_id, &detail, FALSE)) {
 362         g_warning("%s: signal `%s' is invalid for instance `%p'",
 363                   G_STRLOC, detailed_signal, container);
 364         return;
 365     }
 366
 367     va_start(var_args, detailed_signal);
 368     adg_container_propagate_valist(container, signal_id, detail, var_args);
 369     va_end(var_args);
 370 }
 371
 372 /**
 373  * adg_container_propagate_valist:
 374  * @container: an #AdgContainer
 375  * @signal_id: the signal id
 376  * @detail: the detail
 377  * @var_args: parameters to be passed to the signal, followed by a
 378  *            pointer to the allocated memory where to store the
 379  *            return type: if the signal is %G_TYPE_NONE (void return
 380  *            type), this trailing pointer should be omitted
 381  *
 382  * Emits the specified signal to all the children of @container
 383  * using g_signal_emit_valist() calls.
 384  **/
 385 void
 386 adg_container_propagate_valist(AdgContainer *container,
 387                                guint signal_id, GQuark detail, va_list var_args)
 388 {
 389     GSList *children;
 390     va_list var_copy;
 391
 392     g_return_if_fail(ADG_IS_CONTAINER(container));
 393
 394     children = adg_container_get_children(container);
 395
 396     while (children != NULL) {
 397         if (children->data != NULL) {
 398             G_VA_COPY(var_copy, var_args);
 399             g_signal_emit_valist(children->data, signal_id, detail, var_copy);
 400         }
 401
 402         children = g_slist_delete_link(children, children);
 403     }
 404 }
 405
 406
 407 static void
 408 global_changed(AdgEntity *entity)
 409 {
 410     PARENT_ENTITY_CLASS->global_changed(entity);
 411     adg_container_propagate_by_name((AdgContainer *) entity, "global-changed");
 412 }
 413
 414 static void
 415 local_changed(AdgEntity *entity)
 416 {
 417     PARENT_ENTITY_CLASS->local_changed(entity);
 418     adg_container_propagate_by_name((AdgContainer *) entity, "local-changed");
 419 }
 420
 421 static void
 422 invalidate(AdgEntity *entity)
 423 {
 424     adg_container_propagate_by_name((AdgContainer *) entity, "invalidate");
 425 }
 426
 427 static void
 428 arrange(AdgEntity *entity)
 429 {
 430     AdgContainer *container = (AdgContainer *) entity;
 431     CpmlExtents extents = { 0 };
 432
 433     adg_container_propagate_by_name(container, "arrange", NULL);
 434     adg_container_foreach(container, G_CALLBACK(add_extents), &extents);
 435     adg_entity_set_extents(entity, &extents);
 436 }
 437
 438 static void
 439 add_extents(AdgEntity *entity, CpmlExtents *container_extents)
 440 {
 441     CpmlExtents extents;
 442     AdgMatrix map;
 443
 444     adg_entity_get_extents(entity, &extents);
 445     adg_entity_get_global_map(entity, &map);
 446
 447     cairo_matrix_transform_point(&map, &extents.org.x, &extents.org.y);
 448     cairo_matrix_transform_distance(&map, &extents.size.x, &extents.size.y);
 449     cpml_extents_add(container_extents, &extents);
 450 }
 451
 452 static void
 453 render(AdgEntity *entity, cairo_t *cr)
 454 {
 455     adg_container_propagate_by_name((AdgContainer *) entity, "render", cr);
 456 }
 457
 458
 459 static GSList *
 460 get_children(AdgContainer *container)
 461 {
 462     AdgContainerPrivate *data = container->data;
 463
 464     /* The NULL case is yet managed by GLib */
 465     return g_slist_copy(data->children);
 466 }
 467
 468 static void
 469 add(AdgContainer *container, AdgEntity *entity)
 470 {
 471     AdgEntity *old_parent;
 472     AdgContainerPrivate *data;
 473
 474     old_parent = adg_entity_get_parent(entity);
 475     if (old_parent != NULL) {
 476         g_warning("Attempting to add an entity with type %s to a container "
 477                   "of type %s, but the entity is already inside a container "
 478                   "of type %s.",
 479                   g_type_name(G_OBJECT_TYPE(entity)),
 480                   g_type_name(G_OBJECT_TYPE(container)),
 481                   g_type_name(G_OBJECT_TYPE(old_parent)));
 482         return;
 483     }
 484
 485     data = container->data;
 486     data->children = g_slist_prepend(data->children, entity);
 487
 488     g_object_ref_sink(entity);
 489     adg_entity_set_parent(entity, (AdgEntity *) container);
 490 }
 491
 492 static void
 493 remove(AdgContainer *container, AdgEntity *entity)
 494 {
 495     AdgContainerPrivate *data;
 496     GSList *node;
 497
 498     data = container->data;
 499     node = g_slist_find(data->children, entity);
 500
 501     if (node == NULL) {
 502         g_warning("Attempting to remove an entity with type %s from a "
 503                   "container of type %s, but the entity is not present.",
 504                   g_type_name(G_OBJECT_TYPE(entity)),
 505                   g_type_name(G_OBJECT_TYPE(container)));
 506         return;
 507     }
 508
 509     data->children = g_slist_delete_link(data->children, node);
 510     adg_entity_set_parent(entity, NULL);
 511     g_object_unref(entity);
 512 }