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