Pileus Git - ~andy/gtk/blob - gtk/gtkwidgetpath.c

   1 /* GTK - The GIMP Toolkit
   2  * Copyright (C) 2010 Carlos Garnacho <carlosg@gnome.org>
   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., 59 Temple Place - Suite 330,
  17  * Boston, MA 02111-1307, USA.
  18  */
  19
  20 #include "config.h"
  21
  22 #include <string.h>
  23
  24 #include "gtkwidget.h"
  25 #include "gtkwidgetpath.h"
  26 #include "gtkstylecontextprivate.h"
  27
  28 /**
  29  * SECTION:gtkwidgetpath
  30  * @Short_description: Widget path abstraction
  31  * @Title: GtkWidgetPath
  32  * @See_also: #GtkStyleContext
  33  *
  34  * GtkWidgetPath is a boxed type that represents a widget hierarchy from
  35  * the topmost widget, typically a toplevel, to any child. This widget
  36  * path abstraction is used in #GtkStyleContext on behalf of the real
  37  * widget in order to query style information.
  38  *
  39  * If you are using GTK+ widgets, you probably will not need to use
  40  * this API directly, as there is gtk_widget_get_path(), and the style
  41  * context returned by gtk_widget_get_style_context() will be automatically
  42  * updated on widget hierarchy changes.
  43  *
  44  * The widget path generation is generally simple:
  45  * <example>
  46  * <title>Defining a button within a window</title>
  47  * <programlisting>
  48  * {
  49  *   GtkWidgetPath *path;
  50  *
  51  *   path = gtk_widget_path_new ();
  52  *   gtk_widget_path_append_type (path, GTK_TYPE_WINDOW);
  53  *   gtk_widget_path_append_type (path, GTK_TYPE_BUTTON);
  54  * }
  55  * </programlisting>
  56  * </example>
  57  *
  58  * Although more complex information, such as widget names, or
  59  * different classes (property that may be used by other widget
  60  * types) and intermediate regions may be included:
  61  *
  62  * <example>
  63  * <title>Defining the first tab widget in a notebook</title>
  64  * <programlisting>
  65  * {
  66  *   GtkWidgetPath *path;
  67  *   guint pos;
  68  *
  69  *   path = gtk_widget_path_new ();
  70  *
  71  *   pos = gtk_widget_path_append_type (path, GTK_TYPE_NOTEBOOK);
  72  *   gtk_widget_path_iter_add_region (path, pos, "tab", GTK_REGION_EVEN | GTK_REGION_FIRST);
  73  *
  74  *   pos = gtk_widget_path_append_type (path, GTK_TYPE_LABEL);
  75  *   gtk_widget_path_iter_set_name (path, pos, "first tab label");
  76  * }
  77  * </programlisting>
  78  * </example>
  79  *
  80  * All this information will be used to match the style information
  81  * that applies to the described widget.
  82  **/
  83
  84 G_DEFINE_BOXED_TYPE (GtkWidgetPath, gtk_widget_path,
  85                      gtk_widget_path_ref, gtk_widget_path_unref)
  86
  87
  88 typedef struct GtkPathElement GtkPathElement;
  89
  90 struct GtkPathElement
  91 {
  92   GType type;
  93   GQuark name;
  94   GHashTable *regions;
  95   GArray *classes;
  96   GtkWidgetPath *siblings;
  97   guint sibling_index;
  98 };
  99
 100 struct _GtkWidgetPath
 101 {
 102   volatile guint ref_count;
 103
 104   GArray *elems; /* First element contains the described widget */
 105 };
 106
 107 /**
 108  * gtk_widget_path_new:
 109  *
 110  * Returns an empty widget path.
 111  *
 112  * Returns: (transfer full): A newly created, empty, #GtkWidgetPath
 113  *
 114  * Since: 3.0
 115  **/
 116 GtkWidgetPath *
 117 gtk_widget_path_new (void)
 118 {
 119   GtkWidgetPath *path;
 120
 121   path = g_slice_new0 (GtkWidgetPath);
 122   path->elems = g_array_new (FALSE, TRUE, sizeof (GtkPathElement));
 123   path->ref_count = 1;
 124
 125   return path;
 126 }
 127
 128 static void
 129 gtk_path_element_copy (GtkPathElement       *dest,
 130                        const GtkPathElement *src)
 131 {
 132   memset (dest, 0, sizeof (GtkPathElement));
 133
 134   dest->type = src->type;
 135   dest->name = src->name;
 136   if (src->siblings)
 137     dest->siblings = gtk_widget_path_ref (src->siblings);
 138   dest->sibling_index = src->sibling_index;
 139
 140   if (src->regions)
 141     {
 142       GHashTableIter iter;
 143       gpointer key, value;
 144
 145       g_hash_table_iter_init (&iter, src->regions);
 146       dest->regions = g_hash_table_new (NULL, NULL);
 147
 148       while (g_hash_table_iter_next (&iter, &key, &value))
 149         g_hash_table_insert (dest->regions, key, value);
 150     }
 151
 152   if (src->classes)
 153     {
 154       dest->classes = g_array_new (FALSE, FALSE, sizeof (GQuark));
 155       g_array_append_vals (dest->classes, src->classes->data, src->classes->len);
 156     }
 157 }
 158
 159 /**
 160  * gtk_widget_path_copy:
 161  * @path: a #GtkWidgetPath
 162  *
 163  * Returns a copy of @path
 164  *
 165  * Returns: (transfer full): a copy of @path
 166  *
 167  * Since: 3.0
 168  **/
 169 GtkWidgetPath *
 170 gtk_widget_path_copy (const GtkWidgetPath *path)
 171 {
 172   GtkWidgetPath *new_path;
 173   guint i;
 174
 175   g_return_val_if_fail (path != NULL, NULL);
 176
 177   new_path = gtk_widget_path_new ();
 178
 179   for (i = 0; i < path->elems->len; i++)
 180     {
 181       GtkPathElement *elem, new;
 182
 183       elem = &g_array_index (path->elems, GtkPathElement, i);
 184
 185       gtk_path_element_copy (&new, elem);
 186
 187       g_array_append_val (new_path->elems, new);
 188     }
 189
 190   return new_path;
 191 }
 192
 193 /**
 194  * gtk_widget_path_ref:
 195  * @path: a #GtkWidgetPath
 196  *
 197  * Increments the reference count on @path.
 198  *
 199  * Returns: @path itself.
 200  *
 201  * Since: 3.2
 202  **/
 203 GtkWidgetPath *
 204 gtk_widget_path_ref (GtkWidgetPath *path)
 205 {
 206   g_return_val_if_fail (path != NULL, path);
 207
 208   g_atomic_int_add (&path->ref_count, 1);
 209
 210   return path;
 211 }
 212
 213 /**
 214  * gtk_widget_path_unref:
 215  * @path: a #GtkWidgetPath
 216  *
 217  * Decrements the reference count on @path, freeing the structure
 218  * if the reference count reaches 0.
 219  *
 220  * Since: 3.2
 221  **/
 222 void
 223 gtk_widget_path_unref (GtkWidgetPath *path)
 224 {
 225   guint i;
 226
 227   g_return_if_fail (path != NULL);
 228
 229   if (!g_atomic_int_dec_and_test (&path->ref_count))
 230     return;
 231
 232   for (i = 0; i < path->elems->len; i++)
 233     {
 234       GtkPathElement *elem;
 235
 236       elem = &g_array_index (path->elems, GtkPathElement, i);
 237
 238       if (elem->regions)
 239         g_hash_table_destroy (elem->regions);
 240
 241       if (elem->classes)
 242         g_array_free (elem->classes, TRUE);
 243
 244       if (elem->siblings)
 245         gtk_widget_path_unref (elem->siblings);
 246     }
 247
 248   g_array_free (path->elems, TRUE);
 249   g_slice_free (GtkWidgetPath, path);
 250 }
 251
 252 /**
 253  * gtk_widget_path_free:
 254  * @path: a #GtkWidgetPath
 255  *
 256  * Decrements the reference count on @path, freeing the structure
 257  * if the reference count reaches 0.
 258  *
 259  * Since: 3.0
 260  **/
 261 void
 262 gtk_widget_path_free (GtkWidgetPath *path)
 263 {
 264   g_return_if_fail (path != NULL);
 265
 266   gtk_widget_path_unref (path);
 267 }
 268
 269 /**
 270  * gtk_widget_path_length:
 271  * @path: a #GtkWidgetPath
 272  *
 273  * Returns the number of #GtkWidget #GTypes between the represented
 274  * widget and its topmost container.
 275  *
 276  * Returns: the number of elements in the path
 277  *
 278  * Since: 3.0
 279  **/
 280 gint
 281 gtk_widget_path_length (const GtkWidgetPath *path)
 282 {
 283   g_return_val_if_fail (path != NULL, 0);
 284
 285   return path->elems->len;
 286 }
 287
 288 /**
 289  * gtk_widget_path_to_string:
 290  * @path: the path
 291  *
 292  * Dumps the widget path into a string representation. It tries to match
 293  * the CSS style as closely as possible (Note that there might be paths
 294  * that cannot be represented in CSS).
 295  *
 296  * The main use of this code is for debugging purposes, so that you can
 297  * g_print() the path or dump it in a gdb session.
 298  *
 299  * Returns: A new string describing @path.
 300  *
 301  * Since: 3.2
 302  **/
 303 char *
 304 gtk_widget_path_to_string (const GtkWidgetPath *path)
 305 {
 306   GString *string;
 307   guint i, j;
 308
 309   g_return_val_if_fail (path != NULL, NULL);
 310
 311   string = g_string_new ("");
 312
 313   for (i = 0; i < path->elems->len; i++)
 314     {
 315       GtkPathElement *elem;
 316
 317       elem = &g_array_index (path->elems, GtkPathElement, i);
 318
 319       if (i > 0)
 320         g_string_append_c (string, ' ');
 321
 322       g_string_append (string, g_type_name (elem->type));
 323
 324       if (elem->name)
 325         {
 326           g_string_append_c (string, '(');
 327           g_string_append (string, g_quark_to_string (elem->name));
 328           g_string_append_c (string, ')');
 329         }
 330
 331
 332       if (elem->siblings)
 333         g_string_append_printf (string, "[%d/%d]",
 334                                 elem->sibling_index + 1,
 335                                 gtk_widget_path_length (elem->siblings));
 336
 337       if (elem->classes)
 338         {
 339           for (j = 0; j < elem->classes->len; j++)
 340             {
 341               g_string_append_c (string, '.');
 342               g_string_append (string, g_quark_to_string (g_array_index (elem->classes, GQuark, j)));
 343             }
 344         }
 345
 346       if (elem->regions)
 347         {
 348           GHashTableIter iter;
 349           gpointer key, value;
 350
 351           g_hash_table_iter_init (&iter, elem->regions);
 352           while (g_hash_table_iter_next (&iter, &key, &value))
 353             {
 354               GtkRegionFlags flags = GPOINTER_TO_UINT (value);
 355               static const char *flag_names[] = {
 356                 "even",
 357                 "odd",
 358                 "first",
 359                 "last",
 360                 "only",
 361                 "sorted"
 362               };
 363
 364               g_string_append_c (string, ' ');
 365               g_string_append (string, g_quark_to_string (GPOINTER_TO_UINT (key)));
 366               for (j = 0; j < G_N_ELEMENTS(flag_names); j++)
 367                 {
 368                   if (flags & (1 << j))
 369                     {
 370                       g_string_append_c (string, ':');
 371                       g_string_append (string, flag_names[j]);
 372                     }
 373                 }
 374             }
 375         }
 376     }
 377
 378   return g_string_free (string, FALSE);
 379 }
 380
 381 /**
 382  * gtk_widget_path_prepend_type:
 383  * @path: a #GtkWidgetPath
 384  * @type: widget type to prepend
 385  *
 386  * Prepends a widget type to the widget hierachy represented by @path.
 387  *
 388  * Since: 3.0
 389  **/
 390 void
 391 gtk_widget_path_prepend_type (GtkWidgetPath *path,
 392                               GType          type)
 393 {
 394   GtkPathElement new = { 0 };
 395
 396   g_return_if_fail (path != NULL);
 397
 398   new.type = type;
 399   g_array_prepend_val (path->elems, new);
 400 }
 401
 402 /**
 403  * gtk_widget_path_append_type:
 404  * @path: a #GtkWidgetPath
 405  * @type: widget type to append
 406  *
 407  * Appends a widget type to the widget hierarchy represented by @path.
 408  *
 409  * Returns: the position where the element was inserted
 410  *
 411  * Since: 3.0
 412  **/
 413 gint
 414 gtk_widget_path_append_type (GtkWidgetPath *path,
 415                              GType          type)
 416 {
 417   GtkPathElement new = { 0 };
 418
 419   g_return_val_if_fail (path != NULL, 0);
 420
 421   new.type = type;
 422   g_array_append_val (path->elems, new);
 423
 424   return path->elems->len - 1;
 425 }
 426
 427 /**
 428  * gtk_widget_path_append_with_siblings:
 429  * @path: the widget path to append to
 430  * @siblings: a widget path describing a list of siblings. This path
 431  *   may not contain any siblings itself and it must not be modified
 432  *   afterwards.
 433  * @sibling_index: index into @siblings for where the added element is
 434  *   positioned.
 435  *
 436  * Appends a widget type with all its siblings to the widget hierarchy
 437  * represented by @path. Using this function instead of
 438  * gtk_widget_path_append_type() will allow the CSS theming to use
 439  * sibling matches in selectors and apply :nth-child() pseudo classes.
 440  * In turn, it requires a lot more care in widget implementations as
 441  * widgets need to make sure to call gtk_widget_reset_style() on all
 442  * involved widgets when the @siblings path changes.
 443  *
 444  * Returns: the position where the element was inserted.
 445  *
 446  * Since: 3.2
 447  **/
 448 gint
 449 gtk_widget_path_append_with_siblings (GtkWidgetPath *path,
 450                                       GtkWidgetPath *siblings,
 451                                       guint          sibling_index)
 452 {
 453   GtkPathElement new;
 454
 455   g_return_val_if_fail (path != NULL, 0);
 456   g_return_val_if_fail (siblings != NULL, 0);
 457   g_return_val_if_fail (sibling_index < gtk_widget_path_length (siblings), 0);
 458
 459   gtk_path_element_copy (&new, &g_array_index (siblings->elems, GtkPathElement, sibling_index));
 460   new.siblings = gtk_widget_path_ref (siblings);
 461   new.sibling_index = sibling_index;
 462   g_array_append_val (path->elems, new);
 463
 464   return path->elems->len - 1;
 465 }
 466
 467 /**
 468  * gtk_widget_path_iter_get_siblings:
 469  * @path: a #GtkWidgetPath
 470  * @pos: position to get the siblings for, -1 for the path head
 471  *
 472  * Returns the list of siblings for the element at @pos. If the element
 473  * was not added with siblings, %NULL is returned.
 474  *
 475  * Returns: %NULL or the list of siblings for the element at @pos.
 476  **/
 477 const GtkWidgetPath *
 478 gtk_widget_path_iter_get_siblings (const GtkWidgetPath *path,
 479                                    gint                 pos)
 480 {
 481   GtkPathElement *elem;
 482
 483   g_return_val_if_fail (path != NULL, G_TYPE_INVALID);
 484   g_return_val_if_fail (path->elems->len != 0, G_TYPE_INVALID);
 485
 486   if (pos < 0 || pos >= path->elems->len)
 487     pos = path->elems->len - 1;
 488
 489   elem = &g_array_index (path->elems, GtkPathElement, pos);
 490   return elem->siblings;
 491 }
 492
 493 /**
 494  * gtk_widget_path_iter_get_sibling_index:
 495  * @path: a #GtkWidgetPath
 496  * @pos: position to get the sibling index for, -1 for the path head
 497  *
 498  * Returns the index into the list of siblings for the element at @pos as
 499  * returned by gtk_widget_path_iter_get_siblings(). If that function would
 500  * return %NULL because the element at @pos has no siblings, this function
 501  * will return 0.
 502  *
 503  * Returns: 0 or the index into the list of siblings for the element at @pos.
 504  **/
 505 guint
 506 gtk_widget_path_iter_get_sibling_index (const GtkWidgetPath *path,
 507                                         gint                 pos)
 508 {
 509   GtkPathElement *elem;
 510
 511   g_return_val_if_fail (path != NULL, G_TYPE_INVALID);
 512   g_return_val_if_fail (path->elems->len != 0, G_TYPE_INVALID);
 513
 514   if (pos < 0 || pos >= path->elems->len)
 515     pos = path->elems->len - 1;
 516
 517   elem = &g_array_index (path->elems, GtkPathElement, pos);
 518   return elem->sibling_index;
 519 }
 520
 521 /**
 522  * gtk_widget_path_iter_get_object_type:
 523  * @path: a #GtkWidgetPath
 524  * @pos: position to get the object type for, -1 for the path head
 525  *
 526  * Returns the object #GType that is at position @pos in the widget
 527  * hierarchy defined in @path.
 528  *
 529  * Returns: a widget type
 530  *
 531  * Since: 3.0
 532  **/
 533 GType
 534 gtk_widget_path_iter_get_object_type (const GtkWidgetPath *path,
 535                                       gint                 pos)
 536 {
 537   GtkPathElement *elem;
 538
 539   g_return_val_if_fail (path != NULL, G_TYPE_INVALID);
 540   g_return_val_if_fail (path->elems->len != 0, G_TYPE_INVALID);
 541
 542   if (pos < 0 || pos >= path->elems->len)
 543     pos = path->elems->len - 1;
 544
 545   elem = &g_array_index (path->elems, GtkPathElement, pos);
 546   return elem->type;
 547 }
 548
 549 /**
 550  * gtk_widget_path_iter_set_object_type:
 551  * @path: a #GtkWidgetPath
 552  * @pos: position to modify, -1 for the path head
 553  * @type: object type to set
 554  *
 555  * Sets the object type for a given position in the widget hierarchy
 556  * defined by @path.
 557  *
 558  * Since: 3.0
 559  **/
 560 void
 561 gtk_widget_path_iter_set_object_type (GtkWidgetPath *path,
 562                                       gint           pos,
 563                                       GType          type)
 564 {
 565   GtkPathElement *elem;
 566
 567   g_return_if_fail (path != NULL);
 568   g_return_if_fail (path->elems->len != 0);
 569
 570   if (pos < 0 || pos >= path->elems->len)
 571     pos = path->elems->len - 1;
 572
 573   elem = &g_array_index (path->elems, GtkPathElement, pos);
 574   elem->type = type;
 575 }
 576
 577 /**
 578  * gtk_widget_path_iter_get_name:
 579  * @path: a #GtkWidgetPath
 580  * @pos: position to get the widget name for, -1 for the path head
 581  *
 582  * Returns the name corresponding to the widget found at
 583  * the position @pos in the widget hierarchy defined by
 584  * @path
 585  *
 586  * Returns: The widget name, or %NULL if none was set.
 587  **/
 588 const gchar *
 589 gtk_widget_path_iter_get_name (const GtkWidgetPath *path,
 590                                gint                 pos)
 591 {
 592   GtkPathElement *elem;
 593
 594   g_return_val_if_fail (path != NULL, NULL);
 595   g_return_val_if_fail (path->elems->len != 0, NULL);
 596
 597   if (pos < 0 || pos >= path->elems->len)
 598     pos = path->elems->len - 1;
 599
 600   elem = &g_array_index (path->elems, GtkPathElement, pos);
 601   return g_quark_to_string (elem->name);
 602 }
 603
 604 /**
 605  * gtk_widget_path_iter_set_name:
 606  * @path: a #GtkWidgetPath
 607  * @pos: position to modify, -1 for the path head
 608  * @name: widget name
 609  *
 610  * Sets the widget name for the widget found at position @pos
 611  * in the widget hierarchy defined by @path.
 612  *
 613  * Since: 3.0
 614  **/
 615 void
 616 gtk_widget_path_iter_set_name (GtkWidgetPath *path,
 617                                gint           pos,
 618                                const gchar   *name)
 619 {
 620   GtkPathElement *elem;
 621
 622   g_return_if_fail (path != NULL);
 623   g_return_if_fail (path->elems->len != 0);
 624   g_return_if_fail (name != NULL);
 625
 626   if (pos < 0 || pos >= path->elems->len)
 627     pos = path->elems->len - 1;
 628
 629   elem = &g_array_index (path->elems, GtkPathElement, pos);
 630
 631   elem->name = g_quark_from_string (name);
 632 }
 633
 634 /**
 635  * gtk_widget_path_iter_has_qname:
 636  * @path: a #GtkWidgetPath
 637  * @pos: position to query, -1 for the path head
 638  * @qname: widget name as a #GQuark
 639  *
 640  * See gtk_widget_path_iter_has_name(). This is a version
 641  * that operates on #GQuark<!-- -->s.
 642  *
 643  * Returns: %TRUE if the widget at @pos has this name
 644  *
 645  * Since: 3.0
 646  **/
 647 gboolean
 648 gtk_widget_path_iter_has_qname (const GtkWidgetPath *path,
 649                                 gint                 pos,
 650                                 GQuark               qname)
 651 {
 652   GtkPathElement *elem;
 653
 654   g_return_val_if_fail (path != NULL, FALSE);
 655   g_return_val_if_fail (path->elems->len != 0, FALSE);
 656   g_return_val_if_fail (qname != 0, FALSE);
 657
 658   if (pos < 0 || pos >= path->elems->len)
 659     pos = path->elems->len - 1;
 660
 661   elem = &g_array_index (path->elems, GtkPathElement, pos);
 662
 663   return (elem->name == qname);
 664 }
 665
 666 /**
 667  * gtk_widget_path_iter_has_name:
 668  * @path: a #GtkWidgetPath
 669  * @pos: position to query, -1 for the path head
 670  * @name: a widget name
 671  *
 672  * Returns %TRUE if the widget at position @pos has the name @name,
 673  * %FALSE otherwise.
 674  *
 675  * Returns: %TRUE if the widget at @pos has this name
 676  *
 677  * Since: 3.0
 678  **/
 679 gboolean
 680 gtk_widget_path_iter_has_name (const GtkWidgetPath *path,
 681                                gint                 pos,
 682                                const gchar         *name)
 683 {
 684   GQuark qname;
 685
 686   g_return_val_if_fail (path != NULL, FALSE);
 687   g_return_val_if_fail (path->elems->len != 0, FALSE);
 688
 689   if (pos < 0 || pos >= path->elems->len)
 690     pos = path->elems->len - 1;
 691
 692   qname = g_quark_try_string (name);
 693
 694   if (qname == 0)
 695     return FALSE;
 696
 697   return gtk_widget_path_iter_has_qname (path, pos, qname);
 698 }
 699
 700 /**
 701  * gtk_widget_path_iter_add_class:
 702  * @path: a #GtkWidget
 703  * @pos: position to modify, -1 for the path head
 704  * @name: a class name
 705  *
 706  * Adds the class @name to the widget at position @pos in
 707  * the hierarchy defined in @path. See
 708  * gtk_style_context_add_class().
 709  *
 710  * Since: 3.0
 711  **/
 712 void
 713 gtk_widget_path_iter_add_class (GtkWidgetPath *path,
 714                                 gint           pos,
 715                                 const gchar   *name)
 716 {
 717   GtkPathElement *elem;
 718   gboolean added = FALSE;
 719   GQuark qname;
 720   guint i;
 721
 722   g_return_if_fail (path != NULL);
 723   g_return_if_fail (path->elems->len != 0);
 724   g_return_if_fail (name != NULL);
 725
 726   if (pos < 0 || pos >= path->elems->len)
 727     pos = path->elems->len - 1;
 728
 729   elem = &g_array_index (path->elems, GtkPathElement, pos);
 730   qname = g_quark_from_string (name);
 731
 732   if (!elem->classes)
 733     elem->classes = g_array_new (FALSE, FALSE, sizeof (GQuark));
 734
 735   for (i = 0; i < elem->classes->len; i++)
 736     {
 737       GQuark quark;
 738
 739       quark = g_array_index (elem->classes, GQuark, i);
 740
 741       if (qname == quark)
 742         {
 743           /* Already there */
 744           added = TRUE;
 745           break;
 746         }
 747       if (qname < quark)
 748         {
 749           g_array_insert_val (elem->classes, i, qname);
 750           added = TRUE;
 751           break;
 752         }
 753     }
 754
 755   if (!added)
 756     g_array_append_val (elem->classes, qname);
 757 }
 758
 759 /**
 760  * gtk_widget_path_iter_remove_class:
 761  * @path: a #GtkWidgetPath
 762  * @pos: position to modify, -1 for the path head
 763  * @name: class name
 764  *
 765  * Removes the class @name from the widget at position @pos in
 766  * the hierarchy defined in @path.
 767  *
 768  * Since: 3.0
 769  **/
 770 void
 771 gtk_widget_path_iter_remove_class (GtkWidgetPath *path,
 772                                    gint           pos,
 773                                    const gchar   *name)
 774 {
 775   GtkPathElement *elem;
 776   GQuark qname;
 777   guint i;
 778
 779   g_return_if_fail (path != NULL);
 780   g_return_if_fail (path->elems->len != 0);
 781   g_return_if_fail (name != NULL);
 782
 783   if (pos < 0 || pos >= path->elems->len)
 784     pos = path->elems->len - 1;
 785
 786   qname = g_quark_try_string (name);
 787
 788   if (qname == 0)
 789     return;
 790
 791   elem = &g_array_index (path->elems, GtkPathElement, pos);
 792
 793   if (!elem->classes)
 794     return;
 795
 796   for (i = 0; i < elem->classes->len; i++)
 797     {
 798       GQuark quark;
 799
 800       quark = g_array_index (elem->classes, GQuark, i);
 801
 802       if (quark > qname)
 803         break;
 804       else if (quark == qname)
 805         {
 806           g_array_remove_index (elem->classes, i);
 807           break;
 808         }
 809     }
 810 }
 811
 812 /**
 813  * gtk_widget_path_iter_clear_classes:
 814  * @path: a #GtkWidget
 815  * @pos: position to modify, -1 for the path head
 816  *
 817  * Removes all classes from the widget at position @pos in the
 818  * hierarchy defined in @path.
 819  *
 820  * Since: 3.0
 821  **/
 822 void
 823 gtk_widget_path_iter_clear_classes (GtkWidgetPath *path,
 824                                     gint           pos)
 825 {
 826   GtkPathElement *elem;
 827
 828   g_return_if_fail (path != NULL);
 829   g_return_if_fail (path->elems->len != 0);
 830
 831   if (pos < 0 || pos >= path->elems->len)
 832     pos = path->elems->len - 1;
 833
 834   elem = &g_array_index (path->elems, GtkPathElement, pos);
 835
 836   if (!elem->classes)
 837     return;
 838
 839   if (elem->classes->len > 0)
 840     g_array_remove_range (elem->classes, 0, elem->classes->len);
 841 }
 842
 843 /**
 844  * gtk_widget_path_iter_list_classes:
 845  * @path: a #GtkWidgetPath
 846  * @pos: position to query, -1 for the path head
 847  *
 848  * Returns a list with all the class names defined for the widget
 849  * at position @pos in the hierarchy defined in @path.
 850  *
 851  * Returns: (transfer container) (element-type utf8): The list of
 852  *          classes, This is a list of strings, the #GSList contents
 853  *          are owned by GTK+, but you should use g_slist_free() to
 854  *          free the list itself.
 855  *
 856  * Since: 3.0
 857  **/
 858 GSList *
 859 gtk_widget_path_iter_list_classes (const GtkWidgetPath *path,
 860                                    gint                 pos)
 861 {
 862   GtkPathElement *elem;
 863   GSList *list = NULL;
 864   guint i;
 865
 866   g_return_val_if_fail (path != NULL, NULL);
 867   g_return_val_if_fail (path->elems->len != 0, NULL);
 868
 869   if (pos < 0 || pos >= path->elems->len)
 870     pos = path->elems->len - 1;
 871
 872   elem = &g_array_index (path->elems, GtkPathElement, pos);
 873
 874   if (!elem->classes)
 875     return NULL;
 876
 877   for (i = 0; i < elem->classes->len; i++)
 878     {
 879       GQuark quark;
 880
 881       quark = g_array_index (elem->classes, GQuark, i);
 882       list = g_slist_prepend (list, (gchar *) g_quark_to_string (quark));
 883     }
 884
 885   return g_slist_reverse (list);
 886 }
 887
 888 /**
 889  * gtk_widget_path_iter_has_qclass:
 890  * @path: a #GtkWidgetPath
 891  * @pos: position to query, -1 for the path head
 892  * @qname: class name as a #GQuark
 893  *
 894  * See gtk_widget_path_iter_has_class(). This is a version that operates
 895  * with GQuark<!-- -->s.
 896  *
 897  * Returns: %TRUE if the widget at @pos has the class defined.
 898  *
 899  * Since: 3.0
 900  **/
 901 gboolean
 902 gtk_widget_path_iter_has_qclass (const GtkWidgetPath *path,
 903                                  gint                 pos,
 904                                  GQuark               qname)
 905 {
 906   GtkPathElement *elem;
 907   guint i;
 908
 909   g_return_val_if_fail (path != NULL, FALSE);
 910   g_return_val_if_fail (path->elems->len != 0, FALSE);
 911   g_return_val_if_fail (qname != 0, FALSE);
 912
 913   if (pos < 0 || pos >= path->elems->len)
 914     pos = path->elems->len - 1;
 915
 916   elem = &g_array_index (path->elems, GtkPathElement, pos);
 917
 918   if (!elem->classes)
 919     return FALSE;
 920
 921   for (i = 0; i < elem->classes->len; i++)
 922     {
 923       GQuark quark;
 924
 925       quark = g_array_index (elem->classes, GQuark, i);
 926
 927       if (quark == qname)
 928         return TRUE;
 929       else if (quark > qname)
 930         break;
 931     }
 932
 933   return FALSE;
 934 }
 935
 936 /**
 937  * gtk_widget_path_iter_has_class:
 938  * @path: a #GtkWidgetPath
 939  * @pos: position to query, -1 for the path head
 940  * @name: class name
 941  *
 942  * Returns %TRUE if the widget at position @pos has the class @name
 943  * defined, %FALSE otherwise.
 944  *
 945  * Returns: %TRUE if the class @name is defined for the widget at @pos
 946  *
 947  * Since: 3.0
 948  **/
 949 gboolean
 950 gtk_widget_path_iter_has_class (const GtkWidgetPath *path,
 951                                 gint                 pos,
 952                                 const gchar         *name)
 953 {
 954   GQuark qname;
 955
 956   g_return_val_if_fail (path != NULL, FALSE);
 957   g_return_val_if_fail (path->elems->len != 0, FALSE);
 958   g_return_val_if_fail (name != NULL, FALSE);
 959
 960   if (pos < 0 || pos >= path->elems->len)
 961     pos = path->elems->len - 1;
 962
 963   qname = g_quark_try_string (name);
 964
 965   if (qname == 0)
 966     return FALSE;
 967
 968   return gtk_widget_path_iter_has_qclass (path, pos, qname);
 969 }
 970
 971 /**
 972  * gtk_widget_path_iter_add_region:
 973  * @path: a #GtkWidgetPath
 974  * @pos: position to modify, -1 for the path head
 975  * @name: region name
 976  * @flags: flags affecting the region
 977  *
 978  * Adds the region @name to the widget at position @pos in
 979  * the hierarchy defined in @path. See
 980  * gtk_style_context_add_region().
 981  *
 982  * <note><para>Region names must only contain lowercase letters
 983  * and '-', starting always with a lowercase letter.</para></note>
 984  *
 985  * Since: 3.0
 986  **/
 987 void
 988 gtk_widget_path_iter_add_region (GtkWidgetPath  *path,
 989                                  gint            pos,
 990                                  const gchar    *name,
 991                                  GtkRegionFlags  flags)
 992 {
 993   GtkPathElement *elem;
 994   GQuark qname;
 995
 996   g_return_if_fail (path != NULL);
 997   g_return_if_fail (path->elems->len != 0);
 998   g_return_if_fail (name != NULL);
 999   g_return_if_fail (_gtk_style_context_check_region_name (name));
1000
1001   if (pos < 0 || pos >= path->elems->len)
1002     pos = path->elems->len - 1;
1003
1004   elem = &g_array_index (path->elems, GtkPathElement, pos);
1005   qname = g_quark_from_string (name);
1006
1007   if (!elem->regions)
1008     elem->regions = g_hash_table_new (NULL, NULL);
1009
1010   g_hash_table_insert (elem->regions,
1011                        GUINT_TO_POINTER (qname),
1012                        GUINT_TO_POINTER (flags));
1013 }
1014
1015 /**
1016  * gtk_widget_path_iter_remove_region:
1017  * @path: a #GtkWidgetPath
1018  * @pos: position to modify, -1 for the path head
1019  * @name: region name
1020  *
1021  * Removes the region @name from the widget at position @pos in
1022  * the hierarchy defined in @path.
1023  *
1024  * Since: 3.0
1025  **/
1026 void
1027 gtk_widget_path_iter_remove_region (GtkWidgetPath *path,
1028                                     gint           pos,
1029                                     const gchar   *name)
1030 {
1031   GtkPathElement *elem;
1032   GQuark qname;
1033
1034   g_return_if_fail (path != NULL);
1035   g_return_if_fail (path->elems->len != 0);
1036   g_return_if_fail (name != NULL);
1037
1038   if (pos < 0 || pos >= path->elems->len)
1039     pos = path->elems->len - 1;
1040
1041   qname = g_quark_try_string (name);
1042
1043   if (qname == 0)
1044     return;
1045
1046   elem = &g_array_index (path->elems, GtkPathElement, pos);
1047
1048   if (elem->regions)
1049     g_hash_table_remove (elem->regions, GUINT_TO_POINTER (qname));
1050 }
1051
1052 /**
1053  * gtk_widget_path_iter_clear_regions:
1054  * @path: a #GtkWidgetPath
1055  * @pos: position to modify, -1 for the path head
1056  *
1057  * Removes all regions from the widget at position @pos in the
1058  * hierarchy defined in @path.
1059  *
1060  * Since: 3.0
1061  **/
1062 void
1063 gtk_widget_path_iter_clear_regions (GtkWidgetPath *path,
1064                                     gint           pos)
1065 {
1066   GtkPathElement *elem;
1067
1068   g_return_if_fail (path != NULL);
1069   g_return_if_fail (path->elems->len != 0);
1070
1071   if (pos < 0 || pos >= path->elems->len)
1072     pos = path->elems->len - 1;
1073
1074   elem = &g_array_index (path->elems, GtkPathElement, pos);
1075
1076   if (elem->regions)
1077     g_hash_table_remove_all (elem->regions);
1078 }
1079
1080 /**
1081  * gtk_widget_path_iter_list_regions:
1082  * @path: a #GtkWidgetPath
1083  * @pos: position to query, -1 for the path head
1084  *
1085  * Returns a list with all the region names defined for the widget
1086  * at position @pos in the hierarchy defined in @path.
1087  *
1088  * Returns: (transfer container) (element-type utf8): The list of
1089  *          regions, This is a list of strings, the #GSList contents
1090  *          are owned by GTK+, but you should use g_slist_free() to
1091  *          free the list itself.
1092  *
1093  * Since: 3.0
1094  **/
1095 GSList *
1096 gtk_widget_path_iter_list_regions (const GtkWidgetPath *path,
1097                                    gint                 pos)
1098 {
1099   GtkPathElement *elem;
1100   GHashTableIter iter;
1101   GSList *list = NULL;
1102   gpointer key;
1103
1104   g_return_val_if_fail (path != NULL, NULL);
1105   g_return_val_if_fail (path->elems->len != 0, NULL);
1106
1107   if (pos < 0 || pos >= path->elems->len)
1108     pos = path->elems->len - 1;
1109
1110   elem = &g_array_index (path->elems, GtkPathElement, pos);
1111
1112   if (!elem->regions)
1113     return NULL;
1114
1115   g_hash_table_iter_init (&iter, elem->regions);
1116
1117   while (g_hash_table_iter_next (&iter, &key, NULL))
1118     {
1119       GQuark qname;
1120
1121       qname = GPOINTER_TO_UINT (key);
1122       list = g_slist_prepend (list, (gchar *) g_quark_to_string (qname));
1123     }
1124
1125   return list;
1126 }
1127
1128 /**
1129  * gtk_widget_path_iter_has_qregion:
1130  * @path: a #GtkWidgetPath
1131  * @pos: position to query, -1 for the path head
1132  * @qname: region name as a #GQuark
1133  * @flags: (out): return location for the region flags
1134  *
1135  * See gtk_widget_path_iter_has_region(). This is a version that operates
1136  * with GQuark<!-- -->s.
1137  *
1138  * Returns: %TRUE if the widget at @pos has the region defined.
1139  *
1140  * Since: 3.0
1141  **/
1142 gboolean
1143 gtk_widget_path_iter_has_qregion (const GtkWidgetPath *path,
1144                                   gint                 pos,
1145                                   GQuark               qname,
1146                                   GtkRegionFlags      *flags)
1147 {
1148   GtkPathElement *elem;
1149   gpointer value;
1150
1151   g_return_val_if_fail (path != NULL, FALSE);
1152   g_return_val_if_fail (path->elems->len != 0, FALSE);
1153   g_return_val_if_fail (qname != 0, FALSE);
1154
1155   if (pos < 0 || pos >= path->elems->len)
1156     pos = path->elems->len - 1;
1157
1158   elem = &g_array_index (path->elems, GtkPathElement, pos);
1159
1160   if (!elem->regions)
1161     return FALSE;
1162
1163   if (!g_hash_table_lookup_extended (elem->regions,
1164                                      GUINT_TO_POINTER (qname),
1165                                      NULL, &value))
1166     return FALSE;
1167
1168   if (flags)
1169     *flags = GPOINTER_TO_UINT (value);
1170
1171   return TRUE;
1172 }
1173
1174 /**
1175  * gtk_widget_path_iter_has_region:
1176  * @path: a #GtkWidgetPath
1177  * @pos: position to query, -1 for the path head
1178  * @name: region name
1179  * @flags: (out): return location for the region flags
1180  *
1181  * Returns %TRUE if the widget at position @pos has the class @name
1182  * defined, %FALSE otherwise.
1183  *
1184  * Returns: %TRUE if the class @name is defined for the widget at @pos
1185  *
1186  * Since: 3.0
1187  **/
1188 gboolean
1189 gtk_widget_path_iter_has_region (const GtkWidgetPath *path,
1190                                  gint                 pos,
1191                                  const gchar         *name,
1192                                  GtkRegionFlags      *flags)
1193 {
1194   GQuark qname;
1195
1196   g_return_val_if_fail (path != NULL, FALSE);
1197   g_return_val_if_fail (path->elems->len != 0, FALSE);
1198   g_return_val_if_fail (name != NULL, FALSE);
1199
1200   if (pos < 0 || pos >= path->elems->len)
1201     pos = path->elems->len - 1;
1202
1203   qname = g_quark_try_string (name);
1204
1205   if (qname == 0)
1206     return FALSE;
1207
1208   return gtk_widget_path_iter_has_qregion (path, pos, qname, flags);
1209 }
1210
1211 /**
1212  * gtk_widget_path_get_object_type:
1213  * @path: a #GtkWidget
1214  *
1215  * Returns the topmost object type, that is, the object type this path
1216  * is representing.
1217  *
1218  * Returns: The object type
1219  *
1220  * Since: 3.0
1221  **/
1222 GType
1223 gtk_widget_path_get_object_type (const GtkWidgetPath *path)
1224 {
1225   GtkPathElement *elem;
1226
1227   g_return_val_if_fail (path != NULL, G_TYPE_INVALID);
1228
1229   elem = &g_array_index (path->elems, GtkPathElement,
1230                          path->elems->len - 1);
1231   return elem->type;
1232 }
1233
1234 /**
1235  * gtk_widget_path_is_type:
1236  * @path: a #GtkWidgetPath
1237  * @type: widget type to match
1238  *
1239  * Returns %TRUE if the widget type represented by this path
1240  * is @type, or a subtype of it.
1241  *
1242  * Returns: %TRUE if the widget represented by @path is of type @type
1243  *
1244  * Since: 3.0
1245  **/
1246 gboolean
1247 gtk_widget_path_is_type (const GtkWidgetPath *path,
1248                          GType                type)
1249 {
1250   GtkPathElement *elem;
1251
1252   g_return_val_if_fail (path != NULL, FALSE);
1253
1254   elem = &g_array_index (path->elems, GtkPathElement,
1255                          path->elems->len - 1);
1256
1257   if (elem->type == type ||
1258       g_type_is_a (elem->type, type))
1259     return TRUE;
1260
1261   return FALSE;
1262 }
1263
1264 /**
1265  * gtk_widget_path_has_parent:
1266  * @path: a #GtkWidgetPath
1267  * @type: widget type to check in parents
1268  *
1269  * Returns %TRUE if any of the parents of the widget represented
1270  * in @path is of type @type, or any subtype of it.
1271  *
1272  * Returns: %TRUE if any parent is of type @type
1273  *
1274  * Since: 3.0
1275  **/
1276 gboolean
1277 gtk_widget_path_has_parent (const GtkWidgetPath *path,
1278                             GType                type)
1279 {
1280   guint i;
1281
1282   g_return_val_if_fail (path != NULL, FALSE);
1283
1284   for (i = 0; i < path->elems->len - 1; i++)
1285     {
1286       GtkPathElement *elem;
1287
1288       elem = &g_array_index (path->elems, GtkPathElement, i);
1289
1290       if (elem->type == type ||
1291           g_type_is_a (elem->type, type))
1292         return TRUE;
1293     }
1294
1295   return FALSE;
1296 }