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