1 /* 2 * This file is part of gtkD. 3 * 4 * gtkD is free software; you can redistribute it and/or modify 5 * it under the terms of the GNU Lesser General Public License 6 * as published by the Free Software Foundation; either version 3 7 * of the License, or (at your option) any later version, with 8 * some exceptions, please read the COPYING file. 9 * 10 * gtkD is distributed in the hope that it will be useful, 11 * but WITHOUT ANY WARRANTY; without even the implied warranty of 12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 * GNU Lesser General Public License for more details. 14 * 15 * You should have received a copy of the GNU Lesser General Public License 16 * along with gtkD; if not, write to the Free Software 17 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA 18 */ 19 20 // generated automatically - do not change 21 // find conversion definition on APILookup.txt 22 // implement new conversion functionalities on the wrap.utils pakage 23 24 25 module gtk.WidgetPath; 26 27 private import glib.ConstructionException; 28 private import glib.ListSG; 29 private import glib.Str; 30 private import gobject.ObjectG; 31 private import gtk.Widget; 32 private import gtk.c.functions; 33 public import gtk.c.types; 34 public import gtkc.gtktypes; 35 private import gtkd.Loader; 36 37 38 /** 39 * GtkWidgetPath is a boxed type that represents a widget hierarchy from 40 * the topmost widget, typically a toplevel, to any child. This widget 41 * path abstraction is used in #GtkStyleContext on behalf of the real 42 * widget in order to query style information. 43 * 44 * If you are using GTK+ widgets, you probably will not need to use 45 * this API directly, as there is gtk_widget_get_path(), and the style 46 * context returned by gtk_widget_get_style_context() will be automatically 47 * updated on widget hierarchy changes. 48 * 49 * The widget path generation is generally simple: 50 * 51 * ## Defining a button within a window 52 * 53 * |[<!-- language="C" --> 54 * { 55 * GtkWidgetPath *path; 56 * 57 * path = gtk_widget_path_new (); 58 * gtk_widget_path_append_type (path, GTK_TYPE_WINDOW); 59 * gtk_widget_path_append_type (path, GTK_TYPE_BUTTON); 60 * } 61 * ]| 62 * 63 * Although more complex information, such as widget names, or 64 * different classes (property that may be used by other widget 65 * types) and intermediate regions may be included: 66 * 67 * ## Defining the first tab widget in a notebook 68 * 69 * |[<!-- language="C" --> 70 * { 71 * GtkWidgetPath *path; 72 * guint pos; 73 * 74 * path = gtk_widget_path_new (); 75 * 76 * pos = gtk_widget_path_append_type (path, GTK_TYPE_NOTEBOOK); 77 * gtk_widget_path_iter_add_region (path, pos, "tab", GTK_REGION_EVEN | GTK_REGION_FIRST); 78 * 79 * pos = gtk_widget_path_append_type (path, GTK_TYPE_LABEL); 80 * gtk_widget_path_iter_set_name (path, pos, "first tab label"); 81 * } 82 * ]| 83 * 84 * All this information will be used to match the style information 85 * that applies to the described widget. 86 */ 87 public class WidgetPath 88 { 89 /** the main Gtk struct */ 90 protected GtkWidgetPath* gtkWidgetPath; 91 protected bool ownedRef; 92 93 /** Get the main Gtk struct */ 94 public GtkWidgetPath* getWidgetPathStruct(bool transferOwnership = false) 95 { 96 if (transferOwnership) 97 ownedRef = false; 98 return gtkWidgetPath; 99 } 100 101 /** the main Gtk struct as a void* */ 102 protected void* getStruct() 103 { 104 return cast(void*)gtkWidgetPath; 105 } 106 107 /** 108 * Sets our main struct and passes it to the parent class. 109 */ 110 public this (GtkWidgetPath* gtkWidgetPath, bool ownedRef = false) 111 { 112 this.gtkWidgetPath = gtkWidgetPath; 113 this.ownedRef = ownedRef; 114 } 115 116 ~this () 117 { 118 if ( Linker.isLoaded(LIBRARY_GTK) && ownedRef ) 119 gtk_widget_path_unref(gtkWidgetPath); 120 } 121 122 123 /** */ 124 public static GType getType() 125 { 126 return gtk_widget_path_get_type(); 127 } 128 129 /** 130 * Returns an empty widget path. 131 * 132 * Returns: A newly created, empty, #GtkWidgetPath 133 * 134 * Since: 3.0 135 * 136 * Throws: ConstructionException GTK+ fails to create the object. 137 */ 138 public this() 139 { 140 auto p = gtk_widget_path_new(); 141 142 if(p is null) 143 { 144 throw new ConstructionException("null returned by new"); 145 } 146 147 this(cast(GtkWidgetPath*) p); 148 } 149 150 /** 151 * Appends the data from @widget to the widget hierarchy represented 152 * by @path. This function is a shortcut for adding information from 153 * @widget to the given @path. This includes setting the name or 154 * adding the style classes from @widget. 155 * 156 * Params: 157 * widget = the widget to append to the widget path 158 * 159 * Returns: the position where the data was inserted 160 * 161 * Since: 3.2 162 */ 163 public int appendForWidget(Widget widget) 164 { 165 return gtk_widget_path_append_for_widget(gtkWidgetPath, (widget is null) ? null : widget.getWidgetStruct()); 166 } 167 168 /** 169 * Appends a widget type to the widget hierarchy represented by @path. 170 * 171 * Params: 172 * type = widget type to append 173 * 174 * Returns: the position where the element was inserted 175 * 176 * Since: 3.0 177 */ 178 public int appendType(GType type) 179 { 180 return gtk_widget_path_append_type(gtkWidgetPath, type); 181 } 182 183 /** 184 * Appends a widget type with all its siblings to the widget hierarchy 185 * represented by @path. Using this function instead of 186 * gtk_widget_path_append_type() will allow the CSS theming to use 187 * sibling matches in selectors and apply :nth-child() pseudo classes. 188 * In turn, it requires a lot more care in widget implementations as 189 * widgets need to make sure to call gtk_widget_reset_style() on all 190 * involved widgets when the @siblings path changes. 191 * 192 * Params: 193 * siblings = a widget path describing a list of siblings. This path 194 * may not contain any siblings itself and it must not be modified 195 * afterwards. 196 * siblingIndex = index into @siblings for where the added element is 197 * positioned. 198 * 199 * Returns: the position where the element was inserted. 200 * 201 * Since: 3.2 202 */ 203 public int appendWithSiblings(WidgetPath siblings, uint siblingIndex) 204 { 205 return gtk_widget_path_append_with_siblings(gtkWidgetPath, (siblings is null) ? null : siblings.getWidgetPathStruct(), siblingIndex); 206 } 207 208 /** 209 * Returns a copy of @path 210 * 211 * Returns: a copy of @path 212 * 213 * Since: 3.0 214 */ 215 public WidgetPath copy() 216 { 217 auto p = gtk_widget_path_copy(gtkWidgetPath); 218 219 if(p is null) 220 { 221 return null; 222 } 223 224 return ObjectG.getDObject!(WidgetPath)(cast(GtkWidgetPath*) p, true); 225 } 226 227 /** 228 * Decrements the reference count on @path, freeing the structure 229 * if the reference count reaches 0. 230 * 231 * Since: 3.0 232 */ 233 public void free() 234 { 235 gtk_widget_path_free(gtkWidgetPath); 236 ownedRef = false; 237 } 238 239 /** 240 * Returns the topmost object type, that is, the object type this path 241 * is representing. 242 * 243 * Returns: The object type 244 * 245 * Since: 3.0 246 */ 247 public GType getObjectType() 248 { 249 return gtk_widget_path_get_object_type(gtkWidgetPath); 250 } 251 252 /** 253 * Returns %TRUE if any of the parents of the widget represented 254 * in @path is of type @type, or any subtype of it. 255 * 256 * Params: 257 * type = widget type to check in parents 258 * 259 * Returns: %TRUE if any parent is of type @type 260 * 261 * Since: 3.0 262 */ 263 public bool hasParent(GType type) 264 { 265 return gtk_widget_path_has_parent(gtkWidgetPath, type) != 0; 266 } 267 268 /** 269 * Returns %TRUE if the widget type represented by this path 270 * is @type, or a subtype of it. 271 * 272 * Params: 273 * type = widget type to match 274 * 275 * Returns: %TRUE if the widget represented by @path is of type @type 276 * 277 * Since: 3.0 278 */ 279 public bool isType(GType type) 280 { 281 return gtk_widget_path_is_type(gtkWidgetPath, type) != 0; 282 } 283 284 /** 285 * Adds the class @name to the widget at position @pos in 286 * the hierarchy defined in @path. See 287 * gtk_style_context_add_class(). 288 * 289 * Params: 290 * pos = position to modify, -1 for the path head 291 * name = a class name 292 * 293 * Since: 3.0 294 */ 295 public void iterAddClass(int pos, string name) 296 { 297 gtk_widget_path_iter_add_class(gtkWidgetPath, pos, Str.toStringz(name)); 298 } 299 300 /** 301 * Adds the region @name to the widget at position @pos in 302 * the hierarchy defined in @path. See 303 * gtk_style_context_add_region(). 304 * 305 * Region names must only contain lowercase letters 306 * and “-”, starting always with a lowercase letter. 307 * 308 * Deprecated: The use of regions is deprecated. 309 * 310 * Params: 311 * pos = position to modify, -1 for the path head 312 * name = region name 313 * flags = flags affecting the region 314 * 315 * Since: 3.0 316 */ 317 public void iterAddRegion(int pos, string name, GtkRegionFlags flags) 318 { 319 gtk_widget_path_iter_add_region(gtkWidgetPath, pos, Str.toStringz(name), flags); 320 } 321 322 /** 323 * Removes all classes from the widget at position @pos in the 324 * hierarchy defined in @path. 325 * 326 * Params: 327 * pos = position to modify, -1 for the path head 328 * 329 * Since: 3.0 330 */ 331 public void iterClearClasses(int pos) 332 { 333 gtk_widget_path_iter_clear_classes(gtkWidgetPath, pos); 334 } 335 336 /** 337 * Removes all regions from the widget at position @pos in the 338 * hierarchy defined in @path. 339 * 340 * Deprecated: The use of regions is deprecated. 341 * 342 * Params: 343 * pos = position to modify, -1 for the path head 344 * 345 * Since: 3.0 346 */ 347 public void iterClearRegions(int pos) 348 { 349 gtk_widget_path_iter_clear_regions(gtkWidgetPath, pos); 350 } 351 352 /** 353 * Returns the name corresponding to the widget found at 354 * the position @pos in the widget hierarchy defined by 355 * @path 356 * 357 * Params: 358 * pos = position to get the widget name for, -1 for the path head 359 * 360 * Returns: The widget name, or %NULL if none was set. 361 */ 362 public string iterGetName(int pos) 363 { 364 return Str.toString(gtk_widget_path_iter_get_name(gtkWidgetPath, pos)); 365 } 366 367 /** 368 * Returns the object name that is at position @pos in the widget 369 * hierarchy defined in @path. 370 * 371 * Params: 372 * pos = position to get the object name for, -1 for the path head 373 * 374 * Returns: the name or %NULL 375 * 376 * Since: 3.20 377 */ 378 public string iterGetObjectName(int pos) 379 { 380 return Str.toString(gtk_widget_path_iter_get_object_name(gtkWidgetPath, pos)); 381 } 382 383 /** 384 * Returns the object #GType that is at position @pos in the widget 385 * hierarchy defined in @path. 386 * 387 * Params: 388 * pos = position to get the object type for, -1 for the path head 389 * 390 * Returns: a widget type 391 * 392 * Since: 3.0 393 */ 394 public GType iterGetObjectType(int pos) 395 { 396 return gtk_widget_path_iter_get_object_type(gtkWidgetPath, pos); 397 } 398 399 /** 400 * Returns the index into the list of siblings for the element at @pos as 401 * returned by gtk_widget_path_iter_get_siblings(). If that function would 402 * return %NULL because the element at @pos has no siblings, this function 403 * will return 0. 404 * 405 * Params: 406 * pos = position to get the sibling index for, -1 for the path head 407 * 408 * Returns: 0 or the index into the list of siblings for the element at @pos. 409 */ 410 public uint iterGetSiblingIndex(int pos) 411 { 412 return gtk_widget_path_iter_get_sibling_index(gtkWidgetPath, pos); 413 } 414 415 /** 416 * Returns the list of siblings for the element at @pos. If the element 417 * was not added with siblings, %NULL is returned. 418 * 419 * Params: 420 * pos = position to get the siblings for, -1 for the path head 421 * 422 * Returns: %NULL or the list of siblings for the element at @pos. 423 */ 424 public WidgetPath iterGetSiblings(int pos) 425 { 426 auto p = gtk_widget_path_iter_get_siblings(gtkWidgetPath, pos); 427 428 if(p is null) 429 { 430 return null; 431 } 432 433 return ObjectG.getDObject!(WidgetPath)(cast(GtkWidgetPath*) p); 434 } 435 436 /** 437 * Returns the state flags corresponding to the widget found at 438 * the position @pos in the widget hierarchy defined by 439 * @path 440 * 441 * Params: 442 * pos = position to get the state for, -1 for the path head 443 * 444 * Returns: The state flags 445 * 446 * Since: 3.14 447 */ 448 public GtkStateFlags iterGetState(int pos) 449 { 450 return gtk_widget_path_iter_get_state(gtkWidgetPath, pos); 451 } 452 453 /** 454 * Returns %TRUE if the widget at position @pos has the class @name 455 * defined, %FALSE otherwise. 456 * 457 * Params: 458 * pos = position to query, -1 for the path head 459 * name = class name 460 * 461 * Returns: %TRUE if the class @name is defined for the widget at @pos 462 * 463 * Since: 3.0 464 */ 465 public bool iterHasClass(int pos, string name) 466 { 467 return gtk_widget_path_iter_has_class(gtkWidgetPath, pos, Str.toStringz(name)) != 0; 468 } 469 470 /** 471 * Returns %TRUE if the widget at position @pos has the name @name, 472 * %FALSE otherwise. 473 * 474 * Params: 475 * pos = position to query, -1 for the path head 476 * name = a widget name 477 * 478 * Returns: %TRUE if the widget at @pos has this name 479 * 480 * Since: 3.0 481 */ 482 public bool iterHasName(int pos, string name) 483 { 484 return gtk_widget_path_iter_has_name(gtkWidgetPath, pos, Str.toStringz(name)) != 0; 485 } 486 487 /** 488 * See gtk_widget_path_iter_has_class(). This is a version that operates 489 * with GQuarks. 490 * 491 * Params: 492 * pos = position to query, -1 for the path head 493 * qname = class name as a #GQuark 494 * 495 * Returns: %TRUE if the widget at @pos has the class defined. 496 * 497 * Since: 3.0 498 */ 499 public bool iterHasQclass(int pos, GQuark qname) 500 { 501 return gtk_widget_path_iter_has_qclass(gtkWidgetPath, pos, qname) != 0; 502 } 503 504 /** 505 * See gtk_widget_path_iter_has_name(). This is a version 506 * that operates on #GQuarks. 507 * 508 * Params: 509 * pos = position to query, -1 for the path head 510 * qname = widget name as a #GQuark 511 * 512 * Returns: %TRUE if the widget at @pos has this name 513 * 514 * Since: 3.0 515 */ 516 public bool iterHasQname(int pos, GQuark qname) 517 { 518 return gtk_widget_path_iter_has_qname(gtkWidgetPath, pos, qname) != 0; 519 } 520 521 /** 522 * See gtk_widget_path_iter_has_region(). This is a version that operates 523 * with GQuarks. 524 * 525 * Deprecated: The use of regions is deprecated. 526 * 527 * Params: 528 * pos = position to query, -1 for the path head 529 * qname = region name as a #GQuark 530 * flags = return location for the region flags 531 * 532 * Returns: %TRUE if the widget at @pos has the region defined. 533 * 534 * Since: 3.0 535 */ 536 public bool iterHasQregion(int pos, GQuark qname, out GtkRegionFlags flags) 537 { 538 return gtk_widget_path_iter_has_qregion(gtkWidgetPath, pos, qname, &flags) != 0; 539 } 540 541 /** 542 * Returns %TRUE if the widget at position @pos has the class @name 543 * defined, %FALSE otherwise. 544 * 545 * Deprecated: The use of regions is deprecated. 546 * 547 * Params: 548 * pos = position to query, -1 for the path head 549 * name = region name 550 * flags = return location for the region flags 551 * 552 * Returns: %TRUE if the class @name is defined for the widget at @pos 553 * 554 * Since: 3.0 555 */ 556 public bool iterHasRegion(int pos, string name, out GtkRegionFlags flags) 557 { 558 return gtk_widget_path_iter_has_region(gtkWidgetPath, pos, Str.toStringz(name), &flags) != 0; 559 } 560 561 /** 562 * Returns a list with all the class names defined for the widget 563 * at position @pos in the hierarchy defined in @path. 564 * 565 * Params: 566 * pos = position to query, -1 for the path head 567 * 568 * Returns: The list of 569 * classes, This is a list of strings, the #GSList contents 570 * are owned by GTK+, but you should use g_slist_free() to 571 * free the list itself. 572 * 573 * Since: 3.0 574 */ 575 public ListSG iterListClasses(int pos) 576 { 577 auto p = gtk_widget_path_iter_list_classes(gtkWidgetPath, pos); 578 579 if(p is null) 580 { 581 return null; 582 } 583 584 return new ListSG(cast(GSList*) p); 585 } 586 587 /** 588 * Returns a list with all the region names defined for the widget 589 * at position @pos in the hierarchy defined in @path. 590 * 591 * Deprecated: The use of regions is deprecated. 592 * 593 * Params: 594 * pos = position to query, -1 for the path head 595 * 596 * Returns: The list of 597 * regions, This is a list of strings, the #GSList contents 598 * are owned by GTK+, but you should use g_slist_free() to 599 * free the list itself. 600 * 601 * Since: 3.0 602 */ 603 public ListSG iterListRegions(int pos) 604 { 605 auto p = gtk_widget_path_iter_list_regions(gtkWidgetPath, pos); 606 607 if(p is null) 608 { 609 return null; 610 } 611 612 return new ListSG(cast(GSList*) p); 613 } 614 615 /** 616 * Removes the class @name from the widget at position @pos in 617 * the hierarchy defined in @path. 618 * 619 * Params: 620 * pos = position to modify, -1 for the path head 621 * name = class name 622 * 623 * Since: 3.0 624 */ 625 public void iterRemoveClass(int pos, string name) 626 { 627 gtk_widget_path_iter_remove_class(gtkWidgetPath, pos, Str.toStringz(name)); 628 } 629 630 /** 631 * Removes the region @name from the widget at position @pos in 632 * the hierarchy defined in @path. 633 * 634 * Deprecated: The use of regions is deprecated. 635 * 636 * Params: 637 * pos = position to modify, -1 for the path head 638 * name = region name 639 * 640 * Since: 3.0 641 */ 642 public void iterRemoveRegion(int pos, string name) 643 { 644 gtk_widget_path_iter_remove_region(gtkWidgetPath, pos, Str.toStringz(name)); 645 } 646 647 /** 648 * Sets the widget name for the widget found at position @pos 649 * in the widget hierarchy defined by @path. 650 * 651 * Params: 652 * pos = position to modify, -1 for the path head 653 * name = widget name 654 * 655 * Since: 3.0 656 */ 657 public void iterSetName(int pos, string name) 658 { 659 gtk_widget_path_iter_set_name(gtkWidgetPath, pos, Str.toStringz(name)); 660 } 661 662 /** 663 * Sets the object name for a given position in the widget hierarchy 664 * defined by @path. 665 * 666 * When set, the object name overrides the object type when matching 667 * CSS. 668 * 669 * Params: 670 * pos = position to modify, -1 for the path head 671 * name = object name to set or %NULL to unset 672 * 673 * Since: 3.20 674 */ 675 public void iterSetObjectName(int pos, string name) 676 { 677 gtk_widget_path_iter_set_object_name(gtkWidgetPath, pos, Str.toStringz(name)); 678 } 679 680 /** 681 * Sets the object type for a given position in the widget hierarchy 682 * defined by @path. 683 * 684 * Params: 685 * pos = position to modify, -1 for the path head 686 * type = object type to set 687 * 688 * Since: 3.0 689 */ 690 public void iterSetObjectType(int pos, GType type) 691 { 692 gtk_widget_path_iter_set_object_type(gtkWidgetPath, pos, type); 693 } 694 695 /** 696 * Sets the widget name for the widget found at position @pos 697 * in the widget hierarchy defined by @path. 698 * 699 * If you want to update just a single state flag, you need to do 700 * this manually, as this function updates all state flags. 701 * 702 * ## Setting a flag 703 * 704 * |[<!-- language="C" --> 705 * gtk_widget_path_iter_set_state (path, pos, gtk_widget_path_iter_get_state (path, pos) | flag); 706 * ]| 707 * 708 * ## Unsetting a flag 709 * 710 * |[<!-- language="C" --> 711 * gtk_widget_path_iter_set_state (path, pos, gtk_widget_path_iter_get_state (path, pos) & ~flag); 712 * ]| 713 * 714 * Params: 715 * pos = position to modify, -1 for the path head 716 * state = state flags 717 * 718 * Since: 3.14 719 */ 720 public void iterSetState(int pos, GtkStateFlags state) 721 { 722 gtk_widget_path_iter_set_state(gtkWidgetPath, pos, state); 723 } 724 725 /** 726 * Returns the number of #GtkWidget #GTypes between the represented 727 * widget and its topmost container. 728 * 729 * Returns: the number of elements in the path 730 * 731 * Since: 3.0 732 */ 733 public int length() 734 { 735 return gtk_widget_path_length(gtkWidgetPath); 736 } 737 738 /** 739 * Prepends a widget type to the widget hierachy represented by @path. 740 * 741 * Params: 742 * type = widget type to prepend 743 * 744 * Since: 3.0 745 */ 746 public void prependType(GType type) 747 { 748 gtk_widget_path_prepend_type(gtkWidgetPath, type); 749 } 750 751 /** 752 * Increments the reference count on @path. 753 * 754 * Returns: @path itself. 755 * 756 * Since: 3.2 757 */ 758 public WidgetPath doref() 759 { 760 auto p = gtk_widget_path_ref(gtkWidgetPath); 761 762 if(p is null) 763 { 764 return null; 765 } 766 767 return ObjectG.getDObject!(WidgetPath)(cast(GtkWidgetPath*) p, true); 768 } 769 770 /** 771 * Dumps the widget path into a string representation. It tries to match 772 * the CSS style as closely as possible (Note that there might be paths 773 * that cannot be represented in CSS). 774 * 775 * The main use of this code is for debugging purposes, so that you can 776 * g_print() the path or dump it in a gdb session. 777 * 778 * Returns: A new string describing @path. 779 * 780 * Since: 3.2 781 */ 782 public override string toString() 783 { 784 auto retStr = gtk_widget_path_to_string(gtkWidgetPath); 785 786 scope(exit) Str.freeString(retStr); 787 return Str.toString(retStr); 788 } 789 790 /** 791 * Decrements the reference count on @path, freeing the structure 792 * if the reference count reaches 0. 793 * 794 * Since: 3.2 795 */ 796 public void unref() 797 { 798 gtk_widget_path_unref(gtkWidgetPath); 799 } 800 }