adg/adg-marker.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-marker
  23  * @short_description: Base entity for markers
  24  *
  25  * A marker is an entity to be applied at the start or end of a segment.
  26  * Typical examples include arrows, ticks, dots and so on.
  27  *
  28  * The #AdgMarker:trail and #AdgMarker:n-segment properties specify the
  29  * segment where the marker should be applied. Similarly to the
  30  * #AdgStroke type, if the associated trail is destroyed the above
  31  * properties are unset.
  32  *
  33  * The local map is used internally to align the marker to the trail end,
  34  * so adg_entity_set_local_map() and friends is reserved. Therefore, if
  35  * the trail is modified and the marker had no way to know it, you should
  36  * call adg_entity_local_changed() to update the marker position.
  37  *
  38  * Use adg_marker_set_pos() to select the position where the marker
  39  * should be put: %0 means the start point of the segment while %1
  40  * means the end point.
  41  *
  42  * The #AdgMarker:model property and APIs are intended only for marker
  43  * implementation purposes.
  44  **/
  45
  46 /**
  47  * AdgMarker:
  48  *
  49  * All fields are privates and should not be used directly.
  50  * Use its public methods instead.
  51  **/
  52
  53
  54 #include "adg-marker.h"
  55 #include "adg-marker-private.h"
  56 #include "adg-intl.h"
  57
  58 #define PARENT_OBJECT_CLASS  ((GObjectClass *) adg_marker_parent_class)
  59 #define PARENT_ENTITY_CLASS  ((AdgEntityClass *) adg_marker_parent_class)
  60
  61
  62 enum {
  63     PROP_0,
  64     PROP_TRAIL,
  65     PROP_N_SEGMENT,
  66     PROP_POS,
  67     PROP_SIZE,
  68     PROP_MODEL
  69 };
  70
  71
  72 static void             dispose                 (GObject        *object);
  73 static void             get_property            (GObject        *object,
  74                                                  guint           prop_id,
  75                                                  GValue         *value,
  76                                                  GParamSpec     *pspec);
  77 static void             set_property            (GObject        *object,
  78                                                  guint           prop_id,
  79                                                  const GValue   *value,
  80                                                  GParamSpec     *pspec);
  81 static void             local_changed           (AdgEntity      *entity);
  82 static void             invalidate              (AdgEntity      *entity);
  83 static gboolean         set_segment             (AdgMarker      *marker,
  84                                                  AdgTrail       *trail,
  85                                                  guint           n_segment);
  86 static void             unset_trail             (AdgMarker      *marker);
  87 static gboolean         set_n_segment           (AdgMarker      *marker,
  88                                                  guint           n_segment);
  89 static gboolean         set_pos                 (AdgMarker      *marker,
  90                                                  gdouble         pos);
  91 static gboolean         set_size                (AdgMarker      *marker,
  92                                                  gdouble         size);
  93 static gboolean         set_model               (AdgMarker      *marker,
  94                                                  AdgModel       *model);
  95 static AdgModel *       create_model            (AdgMarker      *marker);
  96
  97
  98 G_DEFINE_ABSTRACT_TYPE(AdgMarker, adg_marker, ADG_TYPE_ENTITY);
  99
 100
 101 static void
 102 adg_marker_class_init(AdgMarkerClass *klass)
 103 {
 104     GObjectClass *gobject_class;
 105     AdgEntityClass *entity_class;
 106     GParamSpec *param;
 107
 108     gobject_class = (GObjectClass *) klass;
 109     entity_class = (AdgEntityClass *) klass;
 110
 111     g_type_class_add_private(klass, sizeof(AdgMarkerPrivate));
 112
 113     gobject_class->dispose = dispose;
 114     gobject_class->set_property = set_property;
 115     gobject_class->get_property = get_property;
 116
 117     entity_class->local_changed = local_changed;
 118     entity_class->invalidate = invalidate;
 119
 120     klass->create_model = create_model;
 121
 122     param = g_param_spec_object("trail",
 123                                 P_("Trail"),
 124                                 P_("The subject AdgTrail for this marker"),
 125                                 ADG_TYPE_TRAIL,
 126                                 G_PARAM_READWRITE | G_PARAM_CONSTRUCT);
 127     g_object_class_install_property(gobject_class, PROP_TRAIL, param);
 128
 129     param = g_param_spec_uint("n-segment",
 130                               P_("Segment Index"),
 131                               P_("The segment on trail where this marker should be applied (where 0 means undefined segment, 1 the first segment and so on)"),
 132                               0, G_MAXUINT, 0,
 133                               G_PARAM_READWRITE);
 134     g_object_class_install_property(gobject_class, PROP_N_SEGMENT, param);
 135
 136     param = g_param_spec_double("pos",
 137                                 P_("Position"),
 138                                 P_("The position ratio inside the segment where to put the marker (0 means the start point while 1 means the end point)"),
 139                                 0, 1, 0,
 140                                 G_PARAM_READWRITE);
 141     g_object_class_install_property(gobject_class, PROP_POS, param);
 142
 143     param = g_param_spec_double("size",
 144                                 P_("Marker Size"),
 145                                 P_("The size (in global space) of the marker"),
 146                                 0, G_MAXDOUBLE, 10,
 147                                 G_PARAM_READWRITE);
 148     g_object_class_install_property(gobject_class, PROP_SIZE, param);
 149
 150     param = g_param_spec_object("model",
 151                                 P_("Model"),
 152                                 P_("A general purpose model usable by the marker implementations"),
 153                                 ADG_TYPE_MODEL,
 154                                 G_PARAM_READWRITE);
 155     g_object_class_install_property(gobject_class, PROP_MODEL, param);
 156 }
 157
 158 static void
 159 adg_marker_init(AdgMarker *marker)
 160 {
 161     AdgMarkerPrivate *data = G_TYPE_INSTANCE_GET_PRIVATE(marker,
 162                                                          ADG_TYPE_MARKER,
 163                                                          AdgMarkerPrivate);
 164     data->trail = NULL;
 165     data->n_segment = 0;
 166     data->backup_segment = NULL;
 167     memset(&data->segment, 0, sizeof(data->segment));
 168     data->pos = 0;
 169     data->size = 10;
 170     data->model = NULL;
 171
 172     marker->data = data;
 173 }
 174
 175 static void
 176 dispose(GObject *object)
 177 {
 178     AdgMarker *marker = (AdgMarker *) object;
 179
 180     adg_marker_set_model(marker, NULL);
 181     adg_marker_set_segment(marker, NULL, 0);
 182
 183     if (PARENT_OBJECT_CLASS->dispose)
 184         PARENT_OBJECT_CLASS->dispose(object);
 185 }
 186
 187
 188 static void
 189 get_property(GObject *object,
 190              guint prop_id, GValue *value, GParamSpec *pspec)
 191 {
 192     AdgMarkerPrivate *data = ((AdgMarker *) object)->data;
 193
 194     switch (prop_id) {
 195     case PROP_TRAIL:
 196         g_value_set_object(value, data->trail);
 197         break;
 198     case PROP_N_SEGMENT:
 199         g_value_set_uint(value, data->n_segment);
 200         break;
 201     case PROP_POS:
 202         g_value_set_double(value, data->pos);
 203         break;
 204     case PROP_SIZE:
 205         g_value_set_double(value, data->size);
 206         break;
 207     case PROP_MODEL:
 208         g_value_set_object(value, data->model);
 209         break;
 210     default:
 211         G_OBJECT_WARN_INVALID_PROPERTY_ID(object, prop_id, pspec);
 212         break;
 213     }
 214 }
 215
 216 static void
 217 set_property(GObject *object,
 218              guint prop_id, const GValue *value, GParamSpec *pspec)
 219 {
 220     AdgMarker *marker = (AdgMarker *) object;
 221
 222     switch (prop_id) {
 223     case PROP_TRAIL:
 224         set_segment(marker, g_value_get_object(value), 1);
 225         break;
 226     case PROP_N_SEGMENT:
 227         set_n_segment(marker, g_value_get_uint(value));
 228         break;
 229     case PROP_POS:
 230         set_pos(marker, g_value_get_double(value));
 231         break;
 232     case PROP_SIZE:
 233         set_size(marker, g_value_get_double(value));
 234         break;
 235     case PROP_MODEL:
 236         set_model(marker, g_value_get_object(value));
 237         break;
 238     default:
 239         G_OBJECT_WARN_INVALID_PROPERTY_ID(object, prop_id, pspec);
 240         break;
 241     }
 242 }
 243
 244
 245 /**
 246  * adg_marker_set_segment:
 247  * @marker: an #AdgMarker
 248  * @trail: the #AdgTrail
 249  * @n_segment: a segment index
 250  *
 251  * Sets the new segment where the marker should be applied. The weak
 252  * reference to the old trail (if an old trail was present) is dropped
 253  * while a new weak reference is added to @trail. If @trail is destroyed,
 254  * the weak reference callback will automatically unset #AdgMarker:trai
 255  * and will set #AdgMarker:n-segment to %0.
 256  **/
 257 void
 258 adg_marker_set_segment(AdgMarker *marker, AdgTrail *trail, guint n_segment)
 259 {
 260     g_return_if_fail(ADG_IS_MARKER(marker));
 261
 262     if (set_segment(marker, trail, n_segment))
 263         g_object_notify((GObject *) marker, "trail");
 264 }
 265
 266 /**
 267  * adg_marker_get_trail:
 268  * @marker: an #AdgMarker
 269  *
 270  * Gets the trail where this marker should be applied.
 271  *
 272  * Returns: the trail owned by @marker or %NULL on errors
 273  **/
 274 AdgTrail *
 275 adg_marker_get_trail(AdgMarker *marker)
 276 {
 277     AdgMarkerPrivate *data;
 278
 279     g_return_val_if_fail(ADG_IS_MARKER(marker), NULL);
 280
 281     data = marker->data;
 282
 283     return data->trail;
 284 }
 285
 286 /**
 287  * adg_marker_get_n_segment:
 288  * @marker: an #AdgMarker
 289  *
 290  * Returns the segment of the associated trail where this marker
 291  * will be applied, where %1 is the first segment.
 292  *
 293  * Returns: an index greather than %0 on success or %0 on errors
 294  **/
 295 guint
 296 adg_marker_get_n_segment(AdgMarker *marker)
 297 {
 298     AdgMarkerPrivate *data;
 299
 300     g_return_val_if_fail(ADG_IS_MARKER(marker), 0);
 301
 302     data = marker->data;
 303
 304     return data->n_segment;
 305 }
 306
 307 /**
 308  * adg_marker_get_segment:
 309  * @marker: an #AdgMarker
 310  *
 311  * <note><para>
 312  * This function is only useful in marker implementations.
 313  * </para></note>
 314  *
 315  * Gets the segment where the marker will be applied. This segment
 316  * is eventually a modified version of the backup segment, after
 317  * having applied the marker.
 318  *
 319  * Returns: the segment or %NULL on errors
 320  **/
 321 const AdgSegment *
 322 adg_marker_get_segment(AdgMarker *marker)
 323 {
 324     AdgMarkerPrivate *data;
 325
 326     g_return_val_if_fail(ADG_IS_MARKER(marker), NULL);
 327
 328     data = marker->data;
 329
 330     return &data->segment;
 331 }
 332
 333 /**
 334  * adg_marker_backup_segment:
 335  * @marker: an #AdgMarker
 336  *
 337  * <note><para>
 338  * This function is only useful in marker implementations.
 339  * </para></note>
 340  *
 341  * Duplicates the current subject segment for backup purpose: this
 342  * segment can be accessed by adg_marker_get_backup_segment().
 343  * Obviously, a current segment should exist (either the
 344  * #AdgMarker:trail and #AdgMarker:n-segment properties must be
 345  * properly defined) or this method will fail without further
 346  * processing.
 347  *
 348  * When the subject segment is changed (either by changing
 349  * #AdgMarker:trail or #AdgMarker:n-segment) the original segment
 350  * is automatically restored.
 351  **/
 352 void
 353 adg_marker_backup_segment(AdgMarker *marker)
 354 {
 355     AdgMarkerPrivate *data;
 356
 357     g_return_if_fail(ADG_IS_MARKER(marker));
 358
 359     data = marker->data;
 360
 361     if (data->n_segment > 0) {
 362         g_return_if_fail(data->trail != NULL);
 363
 364         g_free(data->backup_segment);
 365
 366         /* Backup the segment, if a segment to backup exists */
 367         if (adg_trail_put_segment(data->trail, data->n_segment,
 368                                   &data->segment))
 369             data->backup_segment = adg_segment_deep_dup(&data->segment);
 370     }
 371 }
 372
 373 /**
 374  * adg_marker_get_backup_segment:
 375  * @marker: an #AdgMarker
 376  *
 377  * <note><para>
 378  * This function is only useful in marker implementations.
 379  * </para></note>
 380  *
 381  * Gets the original segment where the marker has been applied.
 382  * Applying a marker could modify the underlying trail, usually
 383  * by trimming the original segment of a #AdgMarker:size dependent
 384  * length from the ends. The marker instance holds a copy of the
 385  * original segment, generated by adg_marker_backup_segment(),
 386  * to be used in recomputation, for example when the marker
 387  * changes its size.
 388  *
 389  * When the subject segment is changed (either by changing
 390  * #AdgMarker:trail or #AdgMarker:n-segment) the original segment
 391  * is automatically restored.
 392  *
 393  * Returns: the original segment or %NULL on errors
 394  **/
 395 const AdgSegment *
 396 adg_marker_get_backup_segment(AdgMarker *marker)
 397 {
 398     AdgMarkerPrivate *data;
 399
 400     g_return_val_if_fail(ADG_IS_MARKER(marker), NULL);
 401
 402     data = marker->data;
 403
 404     return data->backup_segment;
 405 }
 406
 407 /**
 408  * adg_marker_set_pos:
 409  * @marker: an #AdgMarker
 410  * @pos: the new pos
 411  *
 412  * Sets a new position on @marker. Check out adg_marker_get_pos() for
 413  * details on what @pos represents.
 414  **/
 415 void
 416 adg_marker_set_pos(AdgMarker *marker, gdouble pos)
 417 {
 418     g_return_if_fail(ADG_IS_MARKER(marker));
 419
 420     if (set_pos(marker, pos))
 421         g_object_notify((GObject *) marker, "pos");
 422 }
 423
 424 /**
 425  * adg_marker_get_pos:
 426  * @marker: an #AdgMarker
 427  *
 428  * Gets the current position of @marker. The returned value is a ratio
 429  * position referred to the segment associated to @marker: %0 means the
 430  * start point and %1 means the end point of the segment.
 431  *
 432  * Returns: the marker position
 433  **/
 434 gdouble
 435 adg_marker_get_pos(AdgMarker *marker)
 436 {
 437     AdgMarkerPrivate *data;
 438
 439     g_return_val_if_fail(ADG_IS_MARKER(marker), 0);
 440
 441     data = marker->data;
 442
 443     return data->pos;
 444 }
 445
 446 /**
 447  * adg_marker_set_size:
 448  * @marker: an #AdgMarker
 449  * @size: the new size
 450  *
 451  * Sets a new size on @marker. The @size is an implementation-dependent
 452  * property: it has meaning only when used by an #AdgMarker derived type.
 453  **/
 454 void
 455 adg_marker_set_size(AdgMarker *marker, gdouble size)
 456 {
 457     g_return_if_fail(ADG_IS_MARKER(marker));
 458
 459     if (set_size(marker, size))
 460         g_object_notify((GObject *) marker, "size");
 461 }
 462
 463 /**
 464  * adg_marker_get_size:
 465  * @marker: an #AdgMarker
 466  *
 467  * Gets the current size of @marker.
 468  *
 469  * Returns: the marker size, in global space
 470  **/
 471 gdouble
 472 adg_marker_get_size(AdgMarker *marker)
 473 {
 474     AdgMarkerPrivate *data;
 475
 476     g_return_val_if_fail(ADG_IS_MARKER(marker), 0);
 477
 478     data = marker->data;
 479
 480     return data->size;
 481 }
 482
 483 /**
 484  * adg_marker_set_model:
 485  * @marker: an #AdgMarker
 486  * @model: a new #AdgModel
 487  *
 488  * <note><para>
 489  * This function is only useful in marker implementations.
 490  * </para></note>
 491  *
 492  * Sets a new model for @marker. The reference to the old model (if an
 493  * old model was present) is dropped while a new reference is added to
 494  * @model.
 495  **/
 496 void
 497 adg_marker_set_model(AdgMarker *marker, AdgModel *model)
 498 {
 499     g_return_if_fail(ADG_IS_MARKER(marker));
 500
 501     if (set_model(marker, model))
 502         g_object_notify((GObject *) marker, "model");
 503 }
 504
 505 /**
 506  * adg_marker_get_model:
 507  * @marker: an #AdgMarker
 508  *
 509  * <note><para>
 510  * This function is only useful in marker implementations.
 511  * </para></note>
 512  *
 513  * Gets the current model of @marker. This is an accessor method:
 514  * if you need to get the model for rendering, use adg_marker_model()
 515  * instead.
 516  *
 517  * Returns: the cached model owned by @marker or %NULL on errors
 518  **/
 519 AdgModel *
 520 adg_marker_get_model(AdgMarker *marker)
 521 {
 522     AdgMarkerPrivate *data;
 523
 524     g_return_val_if_fail(ADG_IS_MARKER(marker), NULL);
 525
 526     data = marker->data;
 527
 528     return data->model;
 529 }
 530
 531 /**
 532  * adg_marker_model:
 533  * @marker: an #AdgMarker
 534  *
 535  * <note><para>
 536  * This function is only useful in marker implementations.
 537  * </para></note>
 538  *
 539  * Gets the model of @marker. If the model is not found, it is
 540  * automatically created by calling the create_model() virtual method.
 541  *
 542  * Returns: the current model owned by @marker or %NULL on errors
 543  **/
 544 AdgModel *
 545 adg_marker_model(AdgMarker *marker)
 546 {
 547     AdgMarkerPrivate *data;
 548
 549     g_return_val_if_fail(ADG_IS_MARKER(marker), NULL);
 550
 551     data = marker->data;
 552
 553     if (data->model == NULL) {
 554         /* Model not found: regenerate it */
 555         AdgMarkerClass *marker_class = ADG_MARKER_GET_CLASS(marker);
 556
 557         if (marker_class->create_model)
 558             adg_marker_set_model(marker, marker_class->create_model(marker));
 559     }
 560
 561     return data->model;
 562 }
 563
 564
 565 static void
 566 local_changed(AdgEntity *entity)
 567 {
 568     AdgMarkerPrivate *data;
 569     CpmlPair pair;
 570     CpmlVector vector;
 571     AdgMatrix map;
 572
 573     data = ((AdgMarker *) entity)->data;
 574     if (data->trail == NULL)
 575         return;
 576
 577     cpml_segment_pair_at(&data->segment, &pair, data->pos);
 578     cpml_segment_vector_at(&data->segment, &vector, data->pos);
 579     cpml_vector_set_length(&vector, data->size);
 580
 581     if (data->pos > 0.5) {
 582         vector.x = -vector.x;
 583         vector.y = -vector.y;
 584     }
 585
 586     cairo_matrix_init(&map, vector.x, vector.y,
 587                       -vector.y, vector.x, pair.x, pair.y);
 588
 589     adg_entity_set_local_map(entity, &map);
 590
 591     if (PARENT_ENTITY_CLASS->local_changed)
 592         PARENT_ENTITY_CLASS->local_changed(entity);
 593 }
 594
 595 static void
 596 invalidate(AdgEntity *entity)
 597 {
 598     adg_marker_set_model((AdgMarker *) entity, NULL);
 599 }
 600
 601
 602 static gboolean
 603 set_segment(AdgMarker *marker, AdgTrail *trail, guint n_segment)
 604 {
 605     AdgMarkerPrivate *data;
 606     AdgEntity *entity;
 607
 608     data = marker->data;
 609     entity = (AdgEntity *) marker;
 610
 611     if (trail == data->trail && n_segment == data->n_segment)
 612         return FALSE;
 613
 614     if (data->trail != NULL) {
 615         /* Restore the original segment in the old trail */
 616         set_n_segment(marker, 0);
 617
 618         g_object_weak_unref((GObject *) data->trail,
 619                             (GWeakNotify) unset_trail, marker);
 620         adg_model_remove_dependency((AdgModel *) data->trail, entity);
 621     }
 622
 623     data->trail = trail;
 624     data->n_segment = 0;
 625
 626     if (data->trail != NULL) {
 627         g_object_weak_ref((GObject *) data->trail,
 628                           (GWeakNotify) unset_trail, marker);
 629         adg_model_add_dependency((AdgModel *) data->trail, entity);
 630
 631         set_n_segment(marker, n_segment);
 632     }
 633
 634     return TRUE;
 635 }
 636
 637 static void
 638 unset_trail(AdgMarker *marker)
 639 {
 640     AdgMarkerPrivate *data = marker->data;
 641
 642     if (data->trail != NULL)
 643         set_segment(marker, NULL, 0);
 644 }
 645
 646 static gboolean
 647 set_n_segment(AdgMarker *marker, guint n_segment)
 648 {
 649     AdgMarkerPrivate *data = marker->data;
 650
 651     if (n_segment == data->n_segment)
 652         return FALSE;
 653
 654     if (data->backup_segment != NULL) {
 655         /* Restore the original segment, if any */
 656         if (data->trail != NULL)
 657             adg_segment_deep_copy(&data->segment, data->backup_segment);
 658
 659         g_free(data->backup_segment);
 660         data->backup_segment = NULL;
 661     }
 662
 663     data->n_segment = n_segment;
 664
 665     if (n_segment == 0) {
 666         memset(&data->segment, 0, sizeof(data->segment));
 667         return TRUE;
 668     }
 669
 670     return adg_trail_put_segment(data->trail, n_segment, &data->segment);
 671 }
 672
 673 static gboolean
 674 set_pos(AdgMarker *marker, gdouble pos)
 675 {
 676     AdgMarkerPrivate *data = marker->data;
 677
 678     if (pos == data->pos)
 679         return FALSE;
 680
 681     data->pos = pos;
 682
 683     return TRUE;
 684 }
 685
 686 static gboolean
 687 set_size(AdgMarker *marker, gdouble size)
 688 {
 689     AdgMarkerPrivate *data = marker->data;
 690
 691     if (size == data->size)
 692         return FALSE;
 693
 694     data->size = size;
 695
 696     return TRUE;
 697 }
 698
 699 static gboolean
 700 set_model(AdgMarker *marker, AdgModel *model)
 701 {
 702     AdgMarkerPrivate *data = marker->data;
 703
 704     if (model == data->model)
 705         return FALSE;
 706
 707     if (data->model != NULL)
 708         g_object_unref((GObject *) data->model);
 709
 710     data->model = model;
 711
 712     if (data->model != NULL) {
 713         g_object_ref((GObject *) data->model);
 714         adg_entity_local_changed((AdgEntity *) marker);
 715     }
 716
 717     return TRUE;
 718 }
 719
 720 static AdgModel *
 721 create_model(AdgMarker *marker)
 722 {
 723     g_warning("%s: `create_model' method not implemented for type `%s'",
 724               G_STRLOC, g_type_name(G_OBJECT_TYPE(marker)));
 725     return NULL;
 726 }