adg/adg-dress.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-dress
  23  * @Section_Id:AdgDress
  24  * @title: AdgDress
  25  * @short_description: The ADG way to associate styles to entities
  26  *
  27  * The dress is a virtualization of an #AdgStyle instance. #AdgEntity
  28  * objects do not directly refer to #AdgStyle but use #AdgDress values
  29  * instead. This allows some advanced operations, such as overriding
  30  * a dress only in a specific entity branch of the hierarchy or
  31  * customize multiple entities at once.
  32  **/
  33
  34 /**
  35  * AdgDress:
  36  *
  37  * An index representing a virtual #AdgStyle.
  38  **/
  39
  40 /**
  41  * ADG_TYPE_DRESS:
  42  *
  43  * The type used to express a dress index. It is defined only for GObject
  44  * internal and should not be used directly (at least, as far as I know).
  45  **/
  46
  47 /**
  48  * ADG_VALUE_HOLDS_DRESS:
  49  * @value: a #GValue
  50  *
  51  * Checks whether a #GValue is actually holding an #AdgDress value or not.
  52  *
  53  * Returns: %TRUE is @value is holding an #AdgDress, %FALSE otherwise
  54  **/
  55
  56
  57 #include "adg-internal.h"
  58 #include "adg-dress.h"
  59 #include "adg-dress-private.h"
  60 #include "adg-dress-builtins.h"
  61
  62
  63 static AdgDress         quark_to_dress          (GQuark          quark);
  64 static void             dress_to_string         (const GValue   *src,
  65                                                  GValue         *dst);
  66 static void             string_to_dress         (const GValue   *src,
  67                                                  GValue         *dst);
  68 static void             param_class_init        (GParamSpecClass*klass);
  69 static gboolean         value_validate          (GParamSpec     *spec,
  70                                                  GValue         *value);
  71
  72 static guint            array_append            (AdgDressPrivate*data);
  73 static AdgDressPrivate *array_lookup            (guint           n);
  74 static guint            array_len               (void);
  75
  76
  77 GType
  78 adg_dress_get_type(void)
  79 {
  80     static GType type = 0;
  81
  82     if (G_UNLIKELY(type == 0)) {
  83         const GTypeInfo info = { 0, };
  84
  85         type = g_type_register_static(G_TYPE_INT, "AdgDress", &info, 0);
  86
  87         g_value_register_transform_func(type, G_TYPE_STRING, dress_to_string);
  88         g_value_register_transform_func(G_TYPE_STRING, type, string_to_dress);
  89     }
  90
  91     return type;
  92 }
  93
  94 /**
  95  * adg_dress_new:
  96  * @name: the dress name
  97  * @fallback: the fallback style
  98  *
  99  * Creates a new dress. It is a convenient wrapper of adg_dress_new_full()
 100  * that uses as ancestor the G_TYPE_FROM_INSTANCE() of @fallback.
 101  *
 102  * After a succesfull call, a new reference is added to @fallback.
 103  *
 104  * Returns: the new #AdgDress value or #ADG_DRESS_UNDEFINED on errors
 105  **/
 106 AdgDress
 107 adg_dress_new(const gchar *name, AdgStyle *fallback)
 108 {
 109     g_return_val_if_fail(ADG_IS_STYLE(fallback), ADG_DRESS_UNDEFINED);
 110
 111     return adg_dress_new_full(name, fallback, G_TYPE_FROM_INSTANCE(fallback));
 112 }
 113
 114 /**
 115  * adg_dress_new_full:
 116  * @name: the dress name
 117  * @fallback: the fallback style
 118  * @ancestor_type: the common ancestor type
 119  *
 120  * Creates a new dress, explicitely setting the ancestor type.
 121  * If @fallback is not %NULL, @ancestor_type must be present in
 122  * its hierarchy: check out the adg_dress_style_is_compatible()
 123  * documentation to know what the ancestor type is used for.
 124  *
 125  * @fallback can be %NULL, in which case a "transparent" dress
 126  * is created. This kind of dress does not change the cairo
 127  * context because there is no style to apply. Any entity could
 128  * override it to change this behavior though.
 129  *
 130  * After a succesfull call, a new reference is added to @fallback
 131  * if needed.
 132  *
 133  * Returns: the new #AdgDress value or #ADG_DRESS_UNDEFINED on errors
 134  **/
 135 AdgDress
 136 adg_dress_new_full(const gchar *name, AdgStyle *fallback, GType ancestor_type)
 137 {
 138     GQuark quark;
 139     AdgDress dress;
 140     AdgDressPrivate data;
 141
 142     g_return_val_if_fail(name != NULL, ADG_DRESS_UNDEFINED);
 143     g_return_val_if_fail(g_type_is_a(ancestor_type, ADG_TYPE_STYLE),
 144                          ADG_DRESS_UNDEFINED);
 145     g_return_val_if_fail(fallback == NULL ||
 146                          G_TYPE_CHECK_INSTANCE_TYPE(fallback, ancestor_type),
 147                          ADG_DRESS_UNDEFINED);
 148
 149     quark = g_quark_from_string(name);
 150     dress = quark_to_dress(quark);
 151
 152     if (dress > 0) {
 153         g_warning("%s: `%s' name yet used by the `%d' dress",
 154                   G_STRLOC, name, dress);
 155         return ADG_DRESS_UNDEFINED;
 156     }
 157
 158     data.quark = quark;
 159     data.fallback = fallback;
 160     data.ancestor_type = ancestor_type;
 161
 162     if (fallback != NULL)
 163         g_object_ref(fallback);
 164
 165     return array_append(&data) - 1;
 166 }
 167
 168 /**
 169  * adg_dress_from_name:
 170  * @name: the name of a dress
 171  *
 172  * Gets the dress bound to a @name string. No warnings are raised
 173  * if the dress is not found.
 174  *
 175  * Returns: the #AdgDress code or #ADG_DRESS_UNDEFINED if not found
 176  **/
 177 AdgDress
 178 adg_dress_from_name(const gchar *name)
 179 {
 180     return quark_to_dress(g_quark_try_string(name));
 181 }
 182
 183 /**
 184  * adg_dress_are_related:
 185  * @dress1: an #AdgDress
 186  * @dress2: another #AdgDress
 187  *
 188  * Checks whether @dress1 and @dress2 are related, that is
 189  * if they have the same ancestor type as returned by
 190  * adg_dress_get_ancestor_type().
 191  *
 192  * Returns: %TRUE if the dresses are related, %FALSE otherwise
 193  **/
 194 gboolean
 195 adg_dress_are_related(AdgDress dress1, AdgDress dress2)
 196 {
 197     GType ancestor_type1, ancestor_type2;
 198
 199     ancestor_type1 = adg_dress_get_ancestor_type(dress1);
 200     if (ancestor_type1 <= 0)
 201         return FALSE;
 202
 203     ancestor_type2 = adg_dress_get_ancestor_type(dress2);
 204     if (ancestor_type2 <= 0)
 205         return FALSE;
 206
 207     return ancestor_type1 == ancestor_type2;
 208 }
 209
 210 /**
 211  * adg_dress_set:
 212  * @dress: a pointer to an #AdgDress
 213  * @src: the source dress
 214  *
 215  * Copies @src in @dress. This operation can be succesful only if
 216  * @dress is #ADG_DRESS_UNDEFINED or if it contains a dress related
 217  * to @src, that is adg_dress_are_related() returns %TRUE.
 218  *
 219  * Returns: %TRUE on copy done, %FALSE on copy failed or not needed
 220  **/
 221 gboolean
 222 adg_dress_set(AdgDress *dress, AdgDress src)
 223 {
 224     if (*dress == src)
 225         return FALSE;
 226
 227     if (*dress != ADG_DRESS_UNDEFINED &&
 228         !adg_dress_are_related(*dress, src)) {
 229         const gchar *dress_name;
 230         const gchar *src_name;
 231
 232         dress_name = adg_dress_get_name(*dress);
 233         if (dress_name == NULL)
 234             dress_name = "UNDEFINED";
 235
 236         src_name = adg_dress_get_name(src);
 237         if (src_name == NULL)
 238             src_name = "UNDEFINED";
 239
 240         g_warning("%s: `%d' (%s) and `%d' (%s) dresses are not related",
 241                   G_STRLOC, *dress, dress_name, src, src_name);
 242
 243         return FALSE;
 244     }
 245
 246     *dress = src;
 247
 248     return TRUE;
 249 }
 250
 251 /**
 252  * adg_dress_get_name:
 253  * @dress: an #AdgDress
 254  *
 255  * Gets the name associated to @dress. No warnings are raised if
 256  * @dress is not found.
 257  *
 258  * Returns: the requested name or %NULL if not found
 259  **/
 260 const gchar *
 261 adg_dress_get_name(AdgDress dress)
 262 {
 263     if (dress <= 0 || dress >= array_len())
 264         return NULL;
 265
 266     return g_quark_to_string(array_lookup(dress)->quark);
 267 }
 268
 269 /**
 270  * adg_dress_get_ancestor_type:
 271  * @dress: an #AdgDress
 272  *
 273  * Gets the base type that should be present in every #AdgStyle
 274  * acceptable by @dress.
 275  *
 276  * Returns: the ancestor type
 277  **/
 278 GType
 279 adg_dress_get_ancestor_type(AdgDress dress)
 280 {
 281     AdgDressPrivate *data;
 282
 283     if (dress <= 0 || dress >= array_len())
 284         return 0;
 285
 286     data = array_lookup(dress);
 287
 288     return data->ancestor_type;
 289 }
 290
 291 /**
 292  * adg_dress_set_fallback:
 293  * @dress: an #AdgDress
 294  * @fallback: the new fallback style
 295  *
 296  * Associates a new @fallback style to @dress. If the dress does
 297  * not exist (it was not previously created by adg_dress_new()),
 298  * a warning message is raised and the function fails.
 299  *
 300  * @fallback is checked for compatibily with @dress. Any dress holds
 301  * an ancestor type: if this type is not found in the @fallback
 302  * hierarchy, a warning message is raised and the function fails.
 303  *
 304  * After a succesfull call, the reference to the previous fallback
 305  * (if any) is dropped while a new reference to @fallback is added.
 306  **/
 307 void
 308 adg_dress_set_fallback(AdgDress dress, AdgStyle *fallback)
 309 {
 310     AdgDressPrivate *data;
 311
 312     if (dress <= 0 || dress >= array_len()) {
 313         g_warning("%s: `%d' dress undefined", G_STRLOC, dress);
 314         return;
 315     }
 316
 317     data = array_lookup(dress);
 318
 319     if (data->fallback == fallback)
 320         return;
 321
 322     /* Check if the new fallback style is compatible with this dress */
 323     if (fallback != NULL && !adg_dress_style_is_compatible(dress, fallback)) {
 324         g_warning("%s: `%s' is not compatible with `%s' for `%s' dress",
 325                   G_STRLOC, g_type_name(G_TYPE_FROM_INSTANCE(fallback)),
 326                   g_type_name(data->ancestor_type), adg_dress_get_name(dress));
 327         return;
 328     }
 329
 330     if (data->fallback != NULL)
 331         g_object_unref(data->fallback);
 332
 333     data->fallback = fallback;
 334
 335     if (data->fallback != NULL)
 336         g_object_ref(data->fallback);
 337 }
 338
 339 /**
 340  * adg_dress_get_fallback:
 341  * @dress: an #AdgDress
 342  *
 343  * Gets the fallback style associated to @dress. No warnings
 344  * are raised if the dress is not found.
 345  *
 346  * Returns: the requested #AdgStyle derived instance or %NULL if not set
 347  **/
 348 AdgStyle *
 349 adg_dress_get_fallback(AdgDress dress)
 350 {
 351     AdgDressPrivate *data;
 352
 353     if (dress <= 0 || dress >= array_len())
 354         return NULL;
 355
 356     data = array_lookup(dress);
 357
 358     return data->fallback;
 359 }
 360
 361 /**
 362  * adg_dress_style_is_compatible:
 363  * @dress: an #AdgDress
 364  * @style: the #AdgStyle to check
 365  *
 366  * Checks whether @style is compatible with @dress, that is if
 367  * @style has the ancestor style type (as returned by
 368  * adg_dress_get_ancestor_type()) in its hierarchy.
 369  *
 370  * Returns: %TRUE if @dress can accept @style, %FALSE otherwise
 371  **/
 372 gboolean
 373 adg_dress_style_is_compatible(AdgDress dress, AdgStyle *style)
 374 {
 375     GType ancestor_type = adg_dress_get_ancestor_type(dress);
 376
 377     g_return_val_if_fail(ancestor_type > 0, FALSE);
 378     g_return_val_if_fail(ADG_IS_STYLE(style), FALSE);
 379
 380     return G_TYPE_CHECK_INSTANCE_TYPE(style, ancestor_type);
 381 }
 382
 383
 384 static AdgDress
 385 quark_to_dress(GQuark quark)
 386 {
 387     AdgDress dress;
 388     AdgDressPrivate *data;
 389
 390     for (dress = 0; dress < array_len(); ++dress) {
 391         data = array_lookup(dress);
 392
 393         if (data->quark == quark)
 394             return dress;
 395     }
 396
 397     return ADG_DRESS_UNDEFINED;
 398 }
 399
 400 static void
 401 dress_to_string(const GValue *src, GValue *dst)
 402 {
 403     g_value_set_string(dst, adg_dress_get_name(g_value_get_int(src)));
 404 }
 405
 406 static void
 407 string_to_dress(const GValue *src, GValue *dst)
 408 {
 409     g_value_set_int(dst, adg_dress_from_name(g_value_get_string(src)));
 410 }
 411
 412
 413 typedef struct _AdgParamSpecDress AdgParamSpecDress;
 414
 415 struct _AdgParamSpecDress {
 416     GParamSpecInt parent;
 417     AdgDress     source_dress;
 418 };
 419
 420
 421 GType
 422 _adg_param_spec_dress_get_type(void)
 423 {
 424     static GType type = 0;
 425
 426     if (G_UNLIKELY(type == 0)) {
 427         const GTypeInfo info = {
 428             sizeof(GParamSpecClass),
 429             NULL,
 430             NULL,
 431             (GClassInitFunc) param_class_init,
 432             NULL,
 433             NULL,
 434             sizeof(AdgParamSpecDress),
 435             0,
 436         };
 437
 438         type = g_type_register_static(G_TYPE_PARAM_INT,
 439                                       "AdgParamSpecDress", &info, 0);
 440     }
 441
 442     return type;
 443 }
 444
 445 static void
 446 param_class_init(GParamSpecClass *klass)
 447 {
 448     klass->value_type = ADG_TYPE_DRESS;
 449     klass->value_validate = value_validate;
 450 }
 451
 452 static gboolean
 453 value_validate(GParamSpec *spec, GValue *value)
 454 {
 455     AdgParamSpecDress *fspec;
 456     AdgDress dress, new_dress;
 457
 458     fspec = (AdgParamSpecDress *) spec;
 459     dress = value->data[0].v_int;
 460     new_dress = ADG_DRESS_UNDEFINED;
 461
 462     adg_dress_set(&new_dress, dress);
 463     value->data[0].v_int = new_dress;
 464
 465     return dress != new_dress;
 466 }
 467
 468
 469 /**
 470  * adg_param_spec_dress:
 471  * @name: canonical name
 472  * @nick: nickname of the param
 473  * @blurb: brief desciption
 474  * @dress: the #AdgDress dress
 475  * @flags: a combination of #GParamFlags
 476  *
 477  * Creates a param spec to hold a dress value.
 478  *
 479  * Returns: the newly allocated #GParamSpec
 480  **/
 481 GParamSpec *
 482 adg_param_spec_dress(const gchar *name, const gchar *nick, const gchar *blurb,
 483                      AdgDress dress, GParamFlags flags)
 484 {
 485     AdgParamSpecDress *fspec;
 486
 487     if (dress <= 0 || dress >= array_len()) {
 488         g_warning("%s: `%d' dress undefined", G_STRLOC, dress);
 489         return NULL;
 490     }
 491
 492     fspec = g_param_spec_internal(ADG_TYPE_PARAM_SPEC_DRESS,
 493                                   name, nick, blurb, flags);
 494     fspec->source_dress = dress;
 495
 496     return (GParamSpec *) fspec;
 497 }
 498
 499
 500 static GArray * array_singleton         (void) G_GNUC_CONST;
 501
 502 static GArray *
 503 array_singleton(void)
 504 {
 505     static GArray *array = NULL;
 506
 507     if (array == NULL) {
 508         const AdgDressPrivate data = { 0, };
 509
 510         array = g_array_new(FALSE, FALSE, sizeof(AdgDressPrivate));
 511
 512         /* Reserve the first item for the undefined dress */
 513         g_array_append_val(array, data);
 514     }
 515
 516     return array;
 517 }
 518
 519 static guint
 520 array_append(AdgDressPrivate *data)
 521 {
 522     return g_array_append_val(array_singleton(), *data)->len;
 523 }
 524
 525 static AdgDressPrivate *
 526 array_lookup(guint n)
 527 {
 528     return &g_array_index(array_singleton(), AdgDressPrivate, n);
 529 }
 530
 531 static guint
 532 array_len(void)
 533 {
 534     return array_singleton()->len;
 535 }