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