adg/adg-entity.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-entity
  23  * @short_description: The base class for renderable objects
  24  *
  25  * This abstract class provides the base for all renderable objects.
  26  *
  27  * To provide a proper #AdgEntity derived type, you must at least
  28  * implement its arrange() and render() virtual methods. Also, if
  29  * you are using some sort of caching, ensure to clear it in the
  30  * invalidate() method.
  31  **/
  32
  33 /**
  34  * AdgEntity:
  35  *
  36  * All fields are private and should not be used directly.
  37  * Use its public methods instead.
  38  **/
  39
  40 /**
  41  * AdgEntityClass:
  42  * @parent_set: called after the parent has changed
  43  * @invalidate: invalidating callback, used to clear the cache
  44  * @arrange: prepare the layout and fill the extents struct
  45  * @render: rendering callback, it must be implemented
  46  *
  47  * Any entity (if not abstract) must implement at least the @render method.
  48  **/
  49
  50 /**
  51  * AdgEntityCallback:
  52  * @entity: an #AdgEntity
  53  * @user_data: a general purpose pointer
  54  *
  55  * Callback used when inspecting or browsing entities. For example,
  56  * it is passed to adg_model_foreach_dependency() to perform an
  57  * operation on all the entities depending on an #AdgModel.
  58  **/
  59
  60
  61 #include "adg-entity.h"
  62 #include "adg-entity-private.h"
  63 #include "adg-canvas.h"
  64 #include "adg-font-style.h"
  65 #include "adg-dim-style.h"
  66 #include "adg-marshal.h"
  67 #include "adg-intl.h"
  68
  69 #define PARENT_OBJECT_CLASS  ((GObjectClass *) adg_entity_parent_class)
  70
  71
  72 enum {
  73     PROP_0,
  74     PROP_PARENT,
  75     PROP_GLOBAL_MAP,
  76     PROP_LOCAL_MAP,
  77     PROP_LOCAL_METHOD
  78 };
  79
  80 enum {
  81     PARENT_SET,
  82     GLOBAL_CHANGED,
  83     LOCAL_CHANGED,
  84     INVALIDATE,
  85     ARRANGE,
  86     RENDER,
  87     LAST_SIGNAL
  88 };
  89
  90
  91 static void             dispose                 (GObject         *object);
  92 static void             get_property            (GObject         *object,
  93                                                  guint            prop_id,
  94                                                  GValue          *value,
  95                                                  GParamSpec      *pspec);
  96 static void             set_property            (GObject         *object,
  97                                                  guint            prop_id,
  98                                                  const GValue    *value,
  99                                                  GParamSpec      *pspec);
 100 static gboolean         set_parent              (AdgEntity       *entity,
 101                                                  AdgEntity       *parent);
 102 static void             global_changed          (AdgEntity       *entity);
 103 static void             local_changed           (AdgEntity       *entity);
 104 static gboolean         set_global_map          (AdgEntity       *entity,
 105                                                  const AdgMatrix *map);
 106 static gboolean         set_local_map           (AdgEntity       *entity,
 107                                                  const AdgMatrix *map);
 108 static gboolean         set_local_method        (AdgEntity       *entity,
 109                                                  AdgMixMethod     local_method);
 110 static void             real_invalidate         (AdgEntity       *entity);
 111 static void             real_arrange            (AdgEntity       *entity);
 112 static void             real_render             (AdgEntity       *entity,
 113                                                  cairo_t         *cr);
 114
 115 static guint    signals[LAST_SIGNAL] = { 0 };
 116 static gboolean show_extents = FALSE;
 117
 118
 119 G_DEFINE_ABSTRACT_TYPE(AdgEntity, adg_entity, G_TYPE_INITIALLY_UNOWNED);
 120
 121
 122 static void
 123 adg_entity_class_init(AdgEntityClass *klass)
 124 {
 125     GObjectClass *gobject_class;
 126     GParamSpec *param;
 127     GClosure *closure;
 128     GType param_types[1];
 129
 130     gobject_class = (GObjectClass *) klass;
 131
 132     g_type_class_add_private(klass, sizeof(AdgEntityPrivate));
 133
 134     gobject_class->dispose = dispose;
 135     gobject_class->get_property = get_property;
 136     gobject_class->set_property = set_property;
 137
 138     klass->parent_set = NULL;
 139     klass->global_changed = global_changed;
 140     klass->local_changed = local_changed;
 141     klass->invalidate = NULL;
 142     klass->arrange= NULL;
 143     klass->render = NULL;
 144
 145     param = g_param_spec_object("parent",
 146                                 P_("Parent Entity"),
 147                                 P_("The parent entity of this entity or NULL if this is a top-level entity"),
 148                                 ADG_TYPE_ENTITY,
 149                                 G_PARAM_READWRITE);
 150     g_object_class_install_property(gobject_class, PROP_PARENT, param);
 151
 152     param = g_param_spec_boxed("global-map",
 153                                P_("Global Map"),
 154                                P_("The transformation to be combined with the parent ones to get the global matrix"),
 155                                ADG_TYPE_MATRIX,
 156                                G_PARAM_READWRITE);
 157     g_object_class_install_property(gobject_class, PROP_GLOBAL_MAP, param);
 158
 159     param = g_param_spec_boxed("local-map",
 160                                P_("Local Map"),
 161                                P_("The local transformation that could be used to compute the local matrix in the way specified by the #AdgEntity:local-method property"),
 162                                ADG_TYPE_MATRIX,
 163                                G_PARAM_READWRITE);
 164     g_object_class_install_property(gobject_class, PROP_LOCAL_MAP, param);
 165
 166     param = g_param_spec_enum("local-method",
 167                               P_("Local Mix Method"),
 168                               P_("Define how the local maps of the entity and its ancestors should be combined to get the local matrix"),
 169                               ADG_TYPE_MIX_METHOD, ADG_MIX_ANCESTORS,
 170                               G_PARAM_READWRITE);
 171     g_object_class_install_property(gobject_class, PROP_LOCAL_METHOD, param);
 172
 173     /**
 174      * AdgEntity::parent-set:
 175      * @entity: an #AdgEntity
 176      * @old_parent: the old parent
 177      *
 178      * Emitted after the parent entity has changed. The new parent
 179      * can be inspected using adg_entity_get_parent().
 180      *
 181      * It is allowed for both old and new parent to be %NULL.
 182      **/
 183     signals[PARENT_SET] = g_signal_new("parent-set",
 184                                        G_OBJECT_CLASS_TYPE(gobject_class),
 185                                        G_SIGNAL_RUN_FIRST,
 186                                        G_STRUCT_OFFSET(AdgEntityClass, parent_set),
 187                                        NULL, NULL,
 188                                        adg_marshal_VOID__OBJECT,
 189                                        G_TYPE_NONE, 1, ADG_TYPE_ENTITY);
 190
 191     /**
 192      * AdgEntity::global-changed
 193      * @entity: an #AdgEntity
 194      *
 195      * Emitted when the global map of @entity or any of its parent
 196      * has changed. The default handler will compute the new global
 197      * matrix, updating the internal cache.
 198      **/
 199     signals[GLOBAL_CHANGED] = g_signal_new("global-changed",
 200                                            G_OBJECT_CLASS_TYPE(gobject_class),
 201                                            G_SIGNAL_RUN_FIRST,
 202                                            G_STRUCT_OFFSET(AdgEntityClass, global_changed),
 203                                            NULL, NULL,
 204                                            adg_marshal_VOID__VOID,
 205                                            G_TYPE_NONE, 0);
 206
 207     /**
 208      * AdgEntity::local-changed
 209      * @entity: an #AdgEntity
 210      *
 211      * Emitted when the local map of @entity or any of its parent
 212      * has changed. The default handler will compute the new local
 213      * matrix, updating the internal cache.
 214      **/
 215     signals[LOCAL_CHANGED] = g_signal_new("local-changed",
 216                                           G_OBJECT_CLASS_TYPE(gobject_class),
 217                                           G_SIGNAL_RUN_FIRST,
 218                                           G_STRUCT_OFFSET(AdgEntityClass, local_changed),
 219                                           NULL, NULL,
 220                                           adg_marshal_VOID__VOID,
 221                                           G_TYPE_NONE, 0);
 222
 223     /**
 224      * AdgEntity::invalidate:
 225      * @entity: an #AdgEntity
 226      *
 227      * Invalidates the whole @entity, that is resets all the cache
 228      * (if present) built during the #AdgEntity::arrange signal.
 229      * The resulting state is a clean entity, similar to what you
 230      * have just before the first rendering.
 231      **/
 232     closure = g_cclosure_new(G_CALLBACK(real_invalidate), NULL, NULL);
 233     signals[INVALIDATE] = g_signal_newv("invalidate", ADG_TYPE_ENTITY,
 234                                         G_SIGNAL_RUN_LAST, closure, NULL, NULL,
 235                                         adg_marshal_VOID__VOID,
 236                                         G_TYPE_NONE, 0, param_types);
 237
 238     /**
 239      * AdgEntity::arrange:
 240      * @entity: an #AdgEntity
 241      *
 242      * Arranges the layout of @entity, updating the cache if necessary,
 243      * and computes the extents of @entity.
 244      **/
 245     closure = g_cclosure_new(G_CALLBACK(real_arrange), NULL, NULL);
 246     signals[ARRANGE] = g_signal_newv("arrange", ADG_TYPE_ENTITY,
 247                                      G_SIGNAL_RUN_LAST, closure, NULL, NULL,
 248                                      adg_marshal_VOID__VOID,
 249                                      G_TYPE_NONE, 0, param_types);
 250     /**
 251      * AdgEntity::render:
 252      * @entity: an #AdgEntity
 253      * @cr: a #cairo_t drawing context
 254      *
 255      * Causes the rendering of @entity on @cr. A render signal will
 256      * automatically emit #AdgEntity::arrange just before the real
 257      * rendering on the cairo context.
 258      **/
 259     closure = g_cclosure_new(G_CALLBACK(real_render), NULL, NULL);
 260     param_types[0] = G_TYPE_POINTER;
 261     signals[RENDER] = g_signal_newv("render", ADG_TYPE_ENTITY,
 262                                     G_SIGNAL_RUN_LAST, closure, NULL, NULL,
 263                                     adg_marshal_VOID__POINTER,
 264                                     G_TYPE_NONE, 1, param_types);
 265 }
 266
 267 static void
 268 adg_entity_init(AdgEntity *entity)
 269 {
 270     AdgEntityPrivate *data = G_TYPE_INSTANCE_GET_PRIVATE(entity,
 271                                                          ADG_TYPE_ENTITY,
 272                                                          AdgEntityPrivate);
 273     data->parent = NULL;
 274     cairo_matrix_init_identity(&data->global_map);
 275     cairo_matrix_init_identity(&data->local_map);
 276     data->local_method = ADG_MIX_ANCESTORS;
 277     data->hash_styles = NULL;
 278     cairo_matrix_init_identity(&data->global_matrix);
 279     cairo_matrix_init_identity(&data->local_matrix);
 280     data->extents.is_defined = FALSE;
 281
 282     entity->data = data;
 283 }
 284
 285 static void
 286 dispose(GObject *object)
 287 {
 288     AdgEntity *entity;
 289     AdgEntityPrivate *data;
 290
 291     entity = (AdgEntity *) object;
 292     data = entity->data;
 293
 294     /* This call will emit a "notify" signal for parent.
 295      * Consequentially, the references to the old parent is dropped. */
 296     adg_entity_set_parent(entity, NULL);
 297
 298     if (data->hash_styles != NULL) {
 299         g_hash_table_destroy(data->hash_styles);
 300         data->hash_styles = NULL;
 301     }
 302
 303     if (PARENT_OBJECT_CLASS->dispose)
 304         PARENT_OBJECT_CLASS->dispose(object);
 305 }
 306
 307
 308 static void
 309 get_property(GObject *object, guint prop_id, GValue *value, GParamSpec *pspec)
 310 {
 311     AdgEntity *entity;
 312     AdgEntityPrivate *data;
 313
 314     entity = (AdgEntity *) object;
 315     data = entity->data;
 316
 317     switch (prop_id) {
 318     case PROP_PARENT:
 319         g_value_set_object(value, data->parent);
 320         break;
 321     case PROP_GLOBAL_MAP:
 322         g_value_set_boxed(value, &data->global_map);
 323         break;
 324     case PROP_LOCAL_MAP:
 325         g_value_set_boxed(value, &data->local_map);
 326         break;
 327     case PROP_LOCAL_METHOD:
 328         g_value_set_enum(value, data->local_method);
 329         break;
 330     default:
 331         G_OBJECT_WARN_INVALID_PROPERTY_ID(object, prop_id, pspec);
 332         break;
 333     }
 334 }
 335
 336 static void
 337 set_property(GObject *object,
 338              guint prop_id, const GValue *value, GParamSpec *pspec)
 339 {
 340     AdgEntity *entity;
 341     AdgEntityPrivate *data;
 342
 343     entity = (AdgEntity *) object;
 344     data = entity->data;
 345
 346     switch (prop_id) {
 347     case PROP_PARENT:
 348         set_parent(entity, g_value_get_object(value));
 349         break;
 350     case PROP_GLOBAL_MAP:
 351         set_global_map(entity, g_value_get_boxed(value));
 352         break;
 353     case PROP_LOCAL_MAP:
 354         set_local_map(entity, g_value_get_boxed(value));
 355         break;
 356     case PROP_LOCAL_METHOD:
 357         set_local_method(entity, g_value_get_enum(value));
 358         break;
 359     default:
 360         G_OBJECT_WARN_INVALID_PROPERTY_ID(object, prop_id, pspec);
 361         break;
 362     }
 363 }
 364
 365
 366 /**
 367  * adg_switch_extents:
 368  * @state: new extents state
 369  *
 370  * Strokes (if @state is %TRUE) a rectangle around every entity to
 371  * show their extents. Useful for debugging purposes.
 372  **/
 373 void
 374 adg_switch_extents(gboolean state)
 375 {
 376     show_extents = state;
 377 }
 378
 379 /**
 380  * adg_entity_get_parent:
 381  * @entity: an #AdgEntity
 382  *
 383  * Gets the parent of @entity.
 384  *
 385  * Returns: the parent entity or %NULL on errors or if @entity is a toplevel
 386  **/
 387 AdgEntity *
 388 adg_entity_get_parent(AdgEntity *entity)
 389 {
 390     AdgEntityPrivate *data;
 391
 392     g_return_val_if_fail(ADG_IS_ENTITY(entity), NULL);
 393
 394     data = entity->data;
 395
 396     return data->parent;
 397 }
 398
 399 /**
 400  * adg_entity_set_parent:
 401  * @entity: an #AdgEntity
 402  * @parent: the parent entity
 403  *
 404  * <note><para>
 405  * This function is only useful in entity implementations.
 406  * </para></note>
 407  *
 408  * Sets a new parent on @entity.
 409  **/
 410 void
 411 adg_entity_set_parent(AdgEntity *entity, AdgEntity *parent)
 412 {
 413     g_return_if_fail(ADG_IS_ENTITY(entity));
 414
 415     if (set_parent(entity, parent))
 416         g_object_notify((GObject *) entity, "parent");
 417 }
 418
 419 /**
 420  * adg_entity_get_canvas:
 421  * @entity: an #AdgEntity
 422  *
 423  * Walks on the @entity hierarchy and gets the first parent of @entity that is
 424  * of #AdgCanvas derived type.
 425  *
 426  * Returns: the requested canvas or %NULL on errors or if there is
 427  *          no #AdgCanvas in the @entity hierarchy
 428  **/
 429 AdgCanvas *
 430 adg_entity_get_canvas(AdgEntity *entity)
 431 {
 432     g_return_val_if_fail(ADG_IS_ENTITY(entity), NULL);
 433
 434     while (entity) {
 435         if (ADG_IS_CANVAS(entity))
 436             return (AdgCanvas *) entity;
 437
 438         entity = (AdgEntity *) adg_entity_get_parent(entity);
 439     }
 440
 441     return NULL;
 442 }
 443
 444 /**
 445  * adg_entity_get_global_map:
 446  * @entity: an #AdgEntity object
 447  * @map: where to store the global map
 448  *
 449  * Gets the transformation to be used to compute the global matrix
 450  * of @entity and store it in @map.
 451  **/
 452 void
 453 adg_entity_get_global_map(AdgEntity *entity, AdgMatrix *map)
 454 {
 455     AdgEntityPrivate *data;
 456
 457     g_return_if_fail(ADG_IS_ENTITY(entity));
 458     g_return_if_fail(map != NULL);
 459
 460     data = entity->data;
 461     adg_matrix_copy(map, &data->global_map);
 462 }
 463
 464 /**
 465  * adg_entity_set_global_map:
 466  * @entity: an #AdgEntity object
 467  * @map: the new map
 468  *
 469  * Sets the new global transformation of @entity to @map:
 470  * the old map is discarded. If @map is %NULL an identity
 471  * matrix is implied.
 472  **/
 473 void
 474 adg_entity_set_global_map(AdgEntity *entity, const AdgMatrix *map)
 475 {
 476     g_return_if_fail(ADG_IS_ENTITY(entity));
 477
 478     if (set_global_map(entity, map))
 479         g_object_notify((GObject *) entity, "global-map");
 480 }
 481
 482 /**
 483  * adg_entity_transform_global_map:
 484  * @entity: an #AdgEntity object
 485  * @transformation: the transformation to apply
 486  * @mode: how @transformation should be applied
 487  *
 488  * Convenient function to change the global map of @entity by
 489  * applying @tranformation using the @mode operator. This is
 490  * logically equivalent to the following:
 491  *
 492  * |[
 493  * AdgMatrix tmp_map;
 494  * adg_entity_get_global_map(entity, &tmp_map);
 495  * adg_matrix_transform(&tmp_map, transformation, mode);
 496  * adg_entity_set_global_map(entity, &tmp_map);
 497  * ]|
 498  **/
 499 void
 500 adg_entity_transform_global_map(AdgEntity *entity,
 501                                 const AdgMatrix *transformation,
 502                                 AdgTransformMode mode)
 503 {
 504     AdgEntityPrivate *data;
 505     AdgMatrix map;
 506
 507     g_return_if_fail(ADG_IS_ENTITY(entity));
 508     g_return_if_fail(transformation != NULL);
 509
 510     data = entity->data;
 511
 512     adg_matrix_copy(&map, &data->global_map);
 513     adg_matrix_transform(&map, transformation, mode);
 514
 515     if (set_global_map(entity, &map))
 516         g_object_notify((GObject *) entity, "global-map");
 517 }
 518
 519 /**
 520  * adg_entity_get_local_map:
 521  * @entity: an #AdgEntity object
 522  * @map: where to store the local map
 523  *
 524  * Gets the transformation to be used to compute the local matrix
 525  * of @entity and store it in @map.
 526  **/
 527 void
 528 adg_entity_get_local_map(AdgEntity *entity, AdgMatrix *map)
 529 {
 530     AdgEntityPrivate *data;
 531
 532     g_return_if_fail(ADG_IS_ENTITY(entity));
 533     g_return_if_fail(map != NULL);
 534
 535     data = entity->data;
 536
 537     adg_matrix_copy(map, &data->local_map);
 538 }
 539
 540 /**
 541  * adg_entity_set_local_map:
 542  * @entity: an #AdgEntity object
 543  * @map: the new map
 544  *
 545  * Sets the new local transformation of @entity to @map:
 546  * the old map is discarded. If @map is %NULL an identity
 547  * matrix is implied.
 548  **/
 549 void
 550 adg_entity_set_local_map(AdgEntity *entity, const AdgMatrix *map)
 551 {
 552     g_return_if_fail(ADG_IS_ENTITY(entity));
 553
 554     if (set_local_map(entity, map))
 555         g_object_notify((GObject *) entity, "local-map");
 556 }
 557
 558 /**
 559  * adg_entity_transform_local_map:
 560  * @entity: an #AdgEntity object
 561  * @transformation: the transformation to apply
 562  * @mode: how @transformation should be applied
 563  *
 564  * Convenient function to change the local map of @entity by
 565  * applying @tranformation using the @mode operator. This is
 566  * logically equivalent to the following:
 567  *
 568  * |[
 569  * AdgMatrix tmp_map;
 570  * adg_entity_get_local_map(entity, &tmp_map);
 571  * adg_matrix_transform(&tmp_map, transformation, mode);
 572  * adg_entity_set_local_map(entity, &tmp_map);
 573  * ]|
 574  **/
 575 void
 576 adg_entity_transform_local_map(AdgEntity *entity,
 577                                const AdgMatrix *transformation,
 578                                AdgTransformMode mode)
 579 {
 580     AdgEntityPrivate *data;
 581     AdgMatrix map;
 582
 583     g_return_if_fail(ADG_IS_ENTITY(entity));
 584     g_return_if_fail(transformation != NULL);
 585
 586     data = entity->data;
 587
 588     adg_matrix_copy(&map, &data->local_map);
 589     adg_matrix_transform(&map, transformation, mode);
 590
 591     if (set_local_map(entity, &map))
 592         g_object_notify((GObject *) entity, "local-map");
 593 }
 594
 595 /**
 596  * adg_entity_get_local_method:
 597  * @entity: an #AdgEntity object
 598  *
 599  * Gets the local mix method of @entity. Check out the
 600  * adg_entity_set_local_method() documentation to know what the
 601  * local method is used for.
 602  *
 603  * Returns: the local method of @entity or %ADG_MIX_UNDEFINED on errors
 604  **/
 605 AdgMixMethod
 606 adg_entity_get_local_method(AdgEntity *entity)
 607 {
 608     AdgEntityPrivate *data;
 609
 610     g_return_val_if_fail(ADG_IS_ENTITY(entity), ADG_MIX_UNDEFINED);
 611
 612     data = entity->data;
 613
 614     return data->local_method;
 615 }
 616
 617 /**
 618  * adg_entity_set_local_method:
 619  * @entity: an #AdgEntity object
 620  * @local_method: new method
 621  *
 622  * Sets a new local mix method on @entity. The
 623  * #AdgEntity:local-method property defines how the local
 624  * matrix must be computed: check out the #AdgMixMethod
 625  * documentation to know what are the availables methods
 626  * and how they affect the local matrix computation.
 627  *
 628  * Setting a different local method emits an #Adgentity::local-changed
 629  * signal on @entity.
 630  **/
 631 void
 632 adg_entity_set_local_method(AdgEntity *entity, AdgMixMethod local_method)
 633 {
 634     g_return_if_fail(ADG_IS_ENTITY(entity));
 635
 636     if (set_local_method(entity, local_method))
 637         g_object_notify((GObject *) entity, "local-method");
 638 }
 639
 640 /**
 641  * adg_entity_extents:
 642  * @entity: an #AdgEntity
 643  *
 644  * Gets the bounding box of @entity. The returned struct is
 645  * owned by @entity and should not modified or freed.
 646  *
 647  * This struct specifies the surface portion (in global space
 648  * of @entity) occupied by the entity without taking into
 649  * account rendering properties such as line thickness or caps.
 650  *
 651  * The #AdgEntity::arrange signal should be emitted before
 652  * this call (either explicitely trought adg_entity_arrange()
 653  * or implicitely with adg_entity_render()) in order to get
 654  * an up to date boundary box.
 655  *
 656  * Returns: the bounding box of @entity or %NULL on errors
 657  **/
 658 const CpmlExtents *
 659 adg_entity_extents(AdgEntity *entity)
 660 {
 661     AdgEntityPrivate *data;
 662
 663     g_return_val_if_fail(ADG_IS_ENTITY(entity), NULL);
 664
 665     data = entity->data;
 666
 667     return &data->extents;
 668 }
 669
 670 /**
 671  * adg_entity_set_extents:
 672  * @entity: an #AdgEntity
 673  * @extents: the new extents
 674  *
 675  * <note><para>
 676  * This function is only useful in entity implementations.
 677  * </para></note>
 678  *
 679  * Sets a new bounding box for @entity. @extents can be %NULL,
 680  * in which case the extents are unset.
 681  **/
 682 void
 683 adg_entity_set_extents(AdgEntity *entity, const CpmlExtents *extents)
 684 {
 685     AdgEntityPrivate *data;
 686
 687     g_return_if_fail(ADG_IS_ENTITY(entity));
 688
 689     data = entity->data;
 690
 691     if (extents == NULL)
 692         data->extents.is_defined = FALSE;
 693     else
 694         cpml_extents_copy(&data->extents, extents);
 695 }
 696
 697 /**
 698  * adg_entity_style:
 699  * @entity: an #AdgEntity
 700  * @dress: the dress of the style to get
 701  *
 702  * Gets the style to be used for @entity. @dress specifies which
 703  * "family" of style to get.
 704  *
 705  * The following sequence of checks is performed to get the proper
 706  * style, stopping at the first succesfull result:
 707  *
 708  * <orderedlist>
 709  * <listitem>check if the style is directly overriden by this entity,
 710  *           as returned by adg_entity_get_style();</listitem>
 711  * <listitem>check if @entity has a parent, in which case returns the
 712  *           adg_entity_style() of the parent;</listitem>
 713  * <listitem>returns the main style with adg_dress_get_fallback().</listitem>
 714  * </orderedlist>
 715  *
 716  * Returns: the requested style or %NULL for transparent dresses or errors
 717  **/
 718 AdgStyle *
 719 adg_entity_style(AdgEntity *entity, AdgDress dress)
 720 {
 721     AdgStyle *style;
 722
 723     g_return_val_if_fail(ADG_IS_ENTITY(entity), NULL);
 724
 725     style = adg_entity_get_style(entity, dress);
 726
 727     if (style == NULL) {
 728         AdgEntityPrivate *data = entity->data;
 729
 730         if (data->parent != NULL)
 731             style = adg_entity_style(data->parent, dress);
 732         else
 733             style = adg_dress_get_fallback(dress);
 734     }
 735
 736     return style;
 737 }
 738
 739 /**
 740  * adg_entity_get_style:
 741  * @entity: an #AdgEntity
 742  * @dress: the dress of the style to get
 743  *
 744  * Gets the overriden @dress style from @entity. This is a kind
 745  * of accessor function: to get the style to be used for rendering
 746  * purpose, use adg_entity_style() instead.
 747  *
 748  * Returns: the requested style or %NULL if the @dress style
 749  *          is not overriden
 750  **/
 751 AdgStyle *
 752 adg_entity_get_style(AdgEntity *entity, AdgDress dress)
 753 {
 754     AdgEntityPrivate *data;
 755
 756     g_return_val_if_fail(ADG_IS_ENTITY(entity), NULL);
 757
 758     data = entity->data;
 759
 760     if (data->hash_styles == NULL)
 761         return NULL;
 762
 763     return g_hash_table_lookup(data->hash_styles, GINT_TO_POINTER(dress));
 764 }
 765
 766 /**
 767  * adg_entity_set_style:
 768  * @entity: an #AdgEntity
 769  * @dress: a dress style
 770  * @style: the new style to use
 771  *
 772  * Overrides the style of @dress for @entity and its children.
 773  * If @style is %NULL, any previous override is removed.
 774  *
 775  * The new style must still be compatible with @dress: check out
 776  * the adg_dress_style_is_compatible() documentation to know
 777  * what a compatible style means.
 778  **/
 779 void
 780 adg_entity_set_style(AdgEntity *entity, AdgDress dress, AdgStyle *style)
 781 {
 782     AdgEntityPrivate *data;
 783     gpointer p_dress;
 784     AdgStyle *old_style;
 785
 786     g_return_if_fail(ADG_IS_ENTITY(entity));
 787
 788     data = entity->data;
 789
 790     if (data->hash_styles == NULL && style == NULL)
 791         return;
 792
 793     if (data->hash_styles == NULL)
 794         data->hash_styles = g_hash_table_new_full(NULL, NULL,
 795                                                   NULL, g_object_unref);
 796
 797     p_dress = GINT_TO_POINTER(dress);
 798     old_style = g_hash_table_lookup(data->hash_styles, p_dress);
 799
 800     if (style == old_style)
 801         return;
 802
 803     if (style == NULL) {
 804         g_hash_table_remove(data->hash_styles, p_dress);
 805         return;
 806     }
 807
 808     if (!adg_dress_style_is_compatible(dress, style)) {
 809         GType ancestor_type = adg_dress_get_ancestor_type(dress);
 810
 811         g_warning(_("%s: `%s' is not compatible with `%s' for `%s' dress"),
 812                   G_STRLOC, g_type_name(G_TYPE_FROM_INSTANCE(style)),
 813                   g_type_name(ancestor_type), adg_dress_name(dress));
 814
 815         return;
 816     }
 817
 818     g_object_ref(style);
 819     g_hash_table_replace(data->hash_styles, p_dress, style);
 820 }
 821
 822 /**
 823  * adg_entity_apply_dress:
 824  * @entity: an #AdgEntity
 825  * @dress: the dress style to apply
 826  * @cr: a #cairo_t drawing context
 827  *
 828  * Convenient function to apply a @dress style (as returned by
 829  * adg_entity_style()) to the @cr cairo context.
 830  **/
 831 void
 832 adg_entity_apply_dress(AdgEntity *entity, AdgDress dress, cairo_t *cr)
 833 {
 834     AdgStyle *style;
 835
 836     g_return_if_fail(ADG_IS_ENTITY(entity));
 837     g_return_if_fail(cr != NULL);
 838
 839     style = adg_entity_style(entity, dress);
 840
 841     if (style != NULL)
 842         adg_style_apply(style, entity, cr);
 843 }
 844
 845 /**
 846  * adg_entity_global_changed:
 847  * @entity: an #AdgEntity
 848  *
 849  * Emits the #AdgEntity::global-changed signal on @entity and on all of
 850  * its children, if any.
 851  **/
 852 void
 853 adg_entity_global_changed(AdgEntity *entity)
 854 {
 855     g_return_if_fail(ADG_IS_ENTITY(entity));
 856
 857     g_signal_emit(entity, signals[GLOBAL_CHANGED], 0);
 858 }
 859
 860 /**
 861  * adg_entity_local_changed:
 862  * @entity: an #AdgEntity
 863  *
 864  * Emits the #AdgEntity::local-changed signal on @entity and on all of
 865  * its children, if any.
 866  **/
 867 void
 868 adg_entity_local_changed(AdgEntity *entity)
 869 {
 870     g_return_if_fail(ADG_IS_ENTITY(entity));
 871
 872     g_signal_emit(entity, signals[LOCAL_CHANGED], 0);
 873 }
 874
 875 /**
 876  * adg_entity_get_global_matrix:
 877  * @entity: an #AdgEntity object
 878  *
 879  * Gets the global matrix by combining all the global maps of the
 880  * @entity hierarchy using the %ADG_MIX_ANCESTORS method. The
 881  * returned value is owned by @entity and should not be changed
 882  * or freed.
 883  *
 884  * Returns: the global matrix or %NULL on errors
 885  **/
 886 const AdgMatrix *
 887 adg_entity_get_global_matrix(AdgEntity *entity)
 888 {
 889     AdgEntityPrivate *data;
 890
 891     g_return_val_if_fail(ADG_IS_ENTITY(entity), NULL);
 892
 893     data = entity->data;
 894
 895     return &data->global_matrix;
 896 }
 897
 898 /**
 899  * adg_entity_get_local_matrix:
 900  * @entity: an #AdgEntity object
 901  * @matrix: where to store the local matrix
 902  *
 903  * Gets the local matrix of @entity in the way specified by the
 904  * #AdgEntity:local-method property. The returned value is owned
 905  * by @entity and should not be changed or freed.
 906  *
 907  * Returns: the local matrix or %NULL on errors
 908  **/
 909 const AdgMatrix *
 910 adg_entity_get_local_matrix(AdgEntity *entity)
 911 {
 912     AdgEntityPrivate *data;
 913
 914     g_return_val_if_fail(ADG_IS_ENTITY(entity), NULL);
 915
 916     data = entity->data;
 917
 918     return &data->local_matrix;
 919 }
 920
 921 /**
 922  * adg_entity_ctm:
 923  * @entity: an #AdgEntity object
 924  *
 925  * Returns the current transformation matrix (ctm) of @entity
 926  * by applying the global matrix after the local matrix. This
 927  * is roughly equivalent to the following pseudo code:
 928  *
 929  * |[
 930  * cairo_matrix_multiply(ctm, local_matrix, global_matrix);
 931  * ]|
 932  *
 933  * This method is only useful inside the #AdgEntity::arrange and the
 934  * #AdgEntity::render default signal handlers, that is at the arranging
 935  * or rendering stage. In the other cases, the returned matrix will
 936  * luckely be not up to date.
 937  *
 938  * Returns: the current transformation matrix or %NULL on errors
 939  **/
 940 const AdgMatrix *
 941 adg_entity_ctm(AdgEntity *entity)
 942 {
 943     AdgEntityPrivate *data;
 944
 945     g_return_val_if_fail(ADG_IS_ENTITY(entity), NULL);
 946
 947     data = entity->data;
 948
 949     return &data->ctm;
 950 }
 951
 952 /**
 953  * adg_entity_invalidate:
 954  * @entity: an #AdgEntity
 955  *
 956  * Emits the #AdgEntity::invalidate signal on @entity and on all of
 957  * its children, if any, clearing the eventual cache stored by the
 958  * #AdgEntity::arrange signal and setting the entity state similary
 959  * to the just initialized entity.
 960  **/
 961 void
 962 adg_entity_invalidate(AdgEntity *entity)
 963 {
 964     g_return_if_fail(ADG_IS_ENTITY(entity));
 965
 966     g_signal_emit(entity, signals[INVALIDATE], 0);
 967 }
 968
 969 /**
 970  * adg_entity_arrange:
 971  * @entity: an #AdgEntity
 972  *
 973  * Emits the #AdgEntity::arrange signal on @entity and all its children,
 974  * if any. This function is rarely needed as the arrange call is usually
 975  * implicitely called by the #AdgEntity::render signal or iby a call to
 976  * adg_entity_get_extents().
 977  **/
 978 void
 979 adg_entity_arrange(AdgEntity *entity)
 980 {
 981     g_return_if_fail(ADG_IS_ENTITY(entity));
 982
 983     g_signal_emit(entity, signals[ARRANGE], 0);
 984 }
 985
 986 /**
 987  * adg_entity_render:
 988  * @entity: an #AdgEntity
 989  * @cr: a #cairo_t drawing context
 990  *
 991  * Emits the #AdgEntity::render signal on @entity and on all of its
 992  * children, if any, causing the rendering to the @cr cairo context.
 993  **/
 994 void
 995 adg_entity_render(AdgEntity *entity, cairo_t *cr)
 996 {
 997     g_return_if_fail(ADG_IS_ENTITY(entity));
 998
 999     g_signal_emit(entity, signals[RENDER], 0, cr);
1000 }
1001
1002
1003 static gboolean
1004 set_parent(AdgEntity *entity, AdgEntity *parent)
1005 {
1006     AdgEntityPrivate *data;
1007     AdgEntity *old_parent;
1008
1009     data = entity->data;
1010     old_parent = data->parent;
1011
1012     /* Check if parent has changed */
1013     if (parent == old_parent)
1014         return FALSE;
1015
1016     if (parent != NULL)
1017         g_object_ref(parent);
1018
1019     data->parent = parent;
1020
1021     g_signal_emit(entity, signals[PARENT_SET], 0, old_parent);
1022     g_signal_emit(entity, signals[GLOBAL_CHANGED], 0);
1023     g_signal_emit(entity, signals[LOCAL_CHANGED], 0);
1024
1025     if (old_parent != NULL)
1026         g_object_unref(old_parent);
1027
1028     return TRUE;
1029 }
1030
1031 static void
1032 global_changed(AdgEntity *entity)
1033 {
1034     AdgEntityPrivate *data;
1035     AdgMatrix *map, *matrix;
1036
1037     data = entity->data;
1038     map = &data->global_map;
1039     matrix = &data->global_matrix;
1040
1041     if (data->parent == NULL) {
1042         adg_matrix_copy(matrix, map);
1043     } else {
1044         adg_matrix_copy(matrix, adg_entity_get_global_matrix(data->parent));
1045         adg_matrix_transform(matrix, map, ADG_TRANSFORM_BEFORE);
1046     }
1047 }
1048
1049 static void
1050 local_changed(AdgEntity *entity)
1051 {
1052     AdgEntityPrivate *data;
1053     AdgMatrix *matrix;
1054
1055     data = entity->data;
1056     matrix = &data->local_matrix;
1057
1058     switch (data->local_method) {
1059     case ADG_MIX_DISABLED:
1060         adg_matrix_copy(matrix, adg_matrix_identity());
1061         break;
1062     case ADG_MIX_NONE:
1063         adg_matrix_copy(matrix, &data->local_map);
1064         break;
1065     case ADG_MIX_ANCESTORS:
1066         if (data->parent != NULL) {
1067             adg_matrix_copy(matrix, adg_entity_get_local_matrix(data->parent));
1068             adg_matrix_transform(matrix, &data->local_map, ADG_TRANSFORM_BEFORE);
1069         } else {
1070             adg_matrix_copy(matrix, &data->local_map);
1071         }
1072         break;
1073     case ADG_MIX_ANCESTORS_NORMALIZED:
1074         if (data->parent != NULL) {
1075             adg_matrix_copy(matrix, adg_entity_get_local_matrix(data->parent));
1076             adg_matrix_transform(matrix, &data->local_map, ADG_TRANSFORM_BEFORE);
1077         } else {
1078             adg_matrix_copy(matrix, &data->local_map);
1079         }
1080         adg_matrix_normalize(matrix);
1081         break;
1082     case ADG_MIX_PARENT:
1083         if (data->parent != NULL) {
1084             adg_entity_get_local_map(data->parent, matrix);
1085             adg_matrix_transform(matrix, &data->local_map, ADG_TRANSFORM_BEFORE);
1086         } else {
1087             adg_matrix_copy(matrix, &data->local_map);
1088         }
1089         break;
1090     case ADG_MIX_PARENT_NORMALIZED:
1091         if (data->parent != NULL) {
1092             adg_entity_get_local_map(data->parent, matrix);
1093             adg_matrix_transform(matrix, &data->local_map, ADG_TRANSFORM_BEFORE);
1094         } else {
1095             adg_matrix_copy(matrix, &data->local_map);
1096         }
1097         adg_matrix_normalize(matrix);
1098         break;
1099     case ADG_MIX_UNDEFINED:
1100         g_warning(_("%s: requested to mix the maps using an undefined method"),
1101                   G_STRLOC);
1102         break;
1103     default:
1104         g_assert_not_reached();
1105         break;
1106     }
1107 }
1108
1109 static gboolean
1110 set_global_map(AdgEntity *entity, const AdgMatrix *map)
1111 {
1112     AdgEntityPrivate *data = entity->data;
1113
1114     if (map != NULL && adg_matrix_equal(&data->global_map, map))
1115         return FALSE;
1116
1117     if (map == NULL)
1118         cairo_matrix_init_identity(&data->global_map);
1119     else
1120         adg_matrix_copy(&data->global_map, map);
1121
1122     g_signal_emit(entity, signals[GLOBAL_CHANGED], 0);
1123     return TRUE;
1124 }
1125
1126 static gboolean
1127 set_local_map(AdgEntity *entity, const AdgMatrix *map)
1128 {
1129     AdgEntityPrivate *data = entity->data;
1130
1131     if (map != NULL && adg_matrix_equal(&data->local_map, map))
1132         return FALSE;
1133
1134     if (map == NULL)
1135         cairo_matrix_init_identity(&data->local_map);
1136     else
1137         adg_matrix_copy(&data->local_map, map);
1138
1139     g_signal_emit(entity, signals[LOCAL_CHANGED], 0);
1140     return TRUE;
1141 }
1142
1143 static gboolean
1144 set_local_method(AdgEntity *entity, AdgMixMethod local_method)
1145 {
1146     AdgEntityPrivate *data = entity->data;
1147
1148     if (data->local_method == local_method)
1149         return FALSE;
1150
1151     data->local_method = local_method;
1152     g_signal_emit(entity, signals[LOCAL_CHANGED], 0);
1153
1154     return TRUE;
1155 }
1156
1157 static void
1158 real_invalidate(AdgEntity *entity)
1159 {
1160     AdgEntityPrivate *data = entity->data;
1161     AdgEntityClass *klass = ADG_ENTITY_GET_CLASS(entity);
1162
1163     /* Do not raise any warning if invalidate() is not defined,
1164      * assuming entity does not have additional cache to be cleared */
1165     if (klass->invalidate)
1166         klass->invalidate(entity);
1167
1168     data->extents.is_defined = FALSE;
1169 }
1170
1171 static void
1172 real_arrange(AdgEntity *entity)
1173 {
1174     AdgEntityClass *klass = ADG_ENTITY_GET_CLASS(entity);
1175
1176     if (klass->arrange) {
1177         AdgEntityPrivate *data;
1178         AdgMatrix *ctm;
1179
1180         data = entity->data;
1181         ctm = &data->ctm;
1182
1183         /* Update the ctm (current transformation matrix) */
1184         adg_matrix_copy(ctm, &data->global_matrix);
1185         adg_matrix_transform(ctm, &data->local_matrix, ADG_TRANSFORM_BEFORE);
1186
1187         klass->arrange(entity);
1188     } else {
1189         /* The arrange() method must be defined */
1190         g_warning(_("%s: `arrange' method not implemented for type `%s'"),
1191                   G_STRLOC, g_type_name(G_OBJECT_TYPE(entity)));
1192     }
1193 }
1194
1195 static void
1196 real_render(AdgEntity *entity, cairo_t *cr)
1197 {
1198     AdgEntityPrivate *data = entity->data;
1199     AdgEntityClass *klass = ADG_ENTITY_GET_CLASS(entity);
1200
1201     if (klass->render) {
1202         /* Before the rendering, the entity should be arranged */
1203         g_signal_emit(entity, signals[ARRANGE], 0);
1204
1205         cairo_save(cr);
1206         cairo_set_matrix(cr, &data->global_matrix);
1207
1208         if (show_extents && data->extents.is_defined) {
1209             cairo_save(cr);
1210             cairo_set_line_width(cr, 1);
1211             cairo_set_antialias(cr, CAIRO_ANTIALIAS_NONE);
1212             cairo_rectangle(cr, data->extents.org.x, data->extents.org.y,
1213                             data->extents.size.x, data->extents.size.y);
1214             cairo_stroke(cr);
1215             cairo_restore(cr);
1216         }
1217
1218         klass->render(entity, cr);
1219         cairo_restore(cr);
1220     } else {
1221         /* The render method must be defined */
1222         g_warning(_("%s: `render' method not implemented for type `%s'"),
1223                   G_STRLOC, g_type_name(G_OBJECT_TYPE(entity)));
1224     }
1225 }