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