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.Loader;
33 private import gtkc.gtk;
34 public  import gtkc.gtktypes;
35 private import gtkc.paths;
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 
92 	/** Get the main Gtk struct */
93 	public GtkWidgetPath* getWidgetPathStruct()
94 	{
95 		return gtkWidgetPath;
96 	}
97 
98 	/** the main Gtk struct as a void* */
99 	protected void* getStruct()
100 	{
101 		return cast(void*)gtkWidgetPath;
102 	}
103 
104 	/**
105 	 * Sets our main struct and passes it to the parent class.
106 	 */
107 	public this (GtkWidgetPath* gtkWidgetPath)
108 	{
109 		this.gtkWidgetPath = gtkWidgetPath;
110 	}
111 
112 	~this ()
113 	{
114 		if (  Linker.isLoaded(LIBRARY.GTK) && gtkWidgetPath !is null )
115 		{
116 			gtk_widget_path_free(gtkWidgetPath);
117 		}
118 	}
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 	 * Return: 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 	 * Return: 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 	 * Return: 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 	 * Return: 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 	 * Return: 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);
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 	}
236 
237 	/**
238 	 * Returns the topmost object type, that is, the object type this path
239 	 * is representing.
240 	 *
241 	 * Return: The object type
242 	 *
243 	 * Since: 3.0
244 	 */
245 	public GType getObjectType()
246 	{
247 		return gtk_widget_path_get_object_type(gtkWidgetPath);
248 	}
249 
250 	/**
251 	 * Returns %TRUE if any of the parents of the widget represented
252 	 * in @path is of type @type, or any subtype of it.
253 	 *
254 	 * Params:
255 	 *     type = widget type to check in parents
256 	 *
257 	 * Return: %TRUE if any parent is of type @type
258 	 *
259 	 * Since: 3.0
260 	 */
261 	public bool hasParent(GType type)
262 	{
263 		return gtk_widget_path_has_parent(gtkWidgetPath, type) != 0;
264 	}
265 
266 	/**
267 	 * Returns %TRUE if the widget type represented by this path
268 	 * is @type, or a subtype of it.
269 	 *
270 	 * Params:
271 	 *     type = widget type to match
272 	 *
273 	 * Return: %TRUE if the widget represented by @path is of type @type
274 	 *
275 	 * Since: 3.0
276 	 */
277 	public bool isType(GType type)
278 	{
279 		return gtk_widget_path_is_type(gtkWidgetPath, type) != 0;
280 	}
281 
282 	/**
283 	 * Adds the class @name to the widget at position @pos in
284 	 * the hierarchy defined in @path. See
285 	 * gtk_style_context_add_class().
286 	 *
287 	 * Params:
288 	 *     pos = position to modify, -1 for the path head
289 	 *     name = a class name
290 	 *
291 	 * Since: 3.0
292 	 */
293 	public void iterAddClass(int pos, string name)
294 	{
295 		gtk_widget_path_iter_add_class(gtkWidgetPath, pos, Str.toStringz(name));
296 	}
297 
298 	/**
299 	 * Adds the region @name to the widget at position @pos in
300 	 * the hierarchy defined in @path. See
301 	 * gtk_style_context_add_region().
302 	 *
303 	 * Region names must only contain lowercase letters
304 	 * and “-”, starting always with a lowercase letter.
305 	 *
306 	 * Deprecated: The use of regions is deprecated.
307 	 *
308 	 * Params:
309 	 *     pos = position to modify, -1 for the path head
310 	 *     name = region name
311 	 *     flags = flags affecting the region
312 	 *
313 	 * Since: 3.0
314 	 */
315 	public void iterAddRegion(int pos, string name, GtkRegionFlags flags)
316 	{
317 		gtk_widget_path_iter_add_region(gtkWidgetPath, pos, Str.toStringz(name), flags);
318 	}
319 
320 	/**
321 	 * Removes all classes from the widget at position @pos in the
322 	 * hierarchy defined in @path.
323 	 *
324 	 * Params:
325 	 *     pos = position to modify, -1 for the path head
326 	 *
327 	 * Since: 3.0
328 	 */
329 	public void iterClearClasses(int pos)
330 	{
331 		gtk_widget_path_iter_clear_classes(gtkWidgetPath, pos);
332 	}
333 
334 	/**
335 	 * Removes all regions from the widget at position @pos in the
336 	 * hierarchy defined in @path.
337 	 *
338 	 * Deprecated: The use of regions is deprecated.
339 	 *
340 	 * Params:
341 	 *     pos = position to modify, -1 for the path head
342 	 *
343 	 * Since: 3.0
344 	 */
345 	public void iterClearRegions(int pos)
346 	{
347 		gtk_widget_path_iter_clear_regions(gtkWidgetPath, pos);
348 	}
349 
350 	/**
351 	 * Returns the name corresponding to the widget found at
352 	 * the position @pos in the widget hierarchy defined by
353 	 * @path
354 	 *
355 	 * Params:
356 	 *     pos = position to get the widget name for, -1 for the path head
357 	 *
358 	 * Return: The widget name, or %NULL if none was set.
359 	 */
360 	public string iterGetName(int pos)
361 	{
362 		return Str.toString(gtk_widget_path_iter_get_name(gtkWidgetPath, pos));
363 	}
364 
365 	/**
366 	 * Returns the object #GType that is at position @pos in the widget
367 	 * hierarchy defined in @path.
368 	 *
369 	 * Params:
370 	 *     pos = position to get the object type for, -1 for the path head
371 	 *
372 	 * Return: a widget type
373 	 *
374 	 * Since: 3.0
375 	 */
376 	public GType iterGetObjectType(int pos)
377 	{
378 		return gtk_widget_path_iter_get_object_type(gtkWidgetPath, pos);
379 	}
380 
381 	/**
382 	 * Returns the index into the list of siblings for the element at @pos as
383 	 * returned by gtk_widget_path_iter_get_siblings(). If that function would
384 	 * return %NULL because the element at @pos has no siblings, this function
385 	 * will return 0.
386 	 *
387 	 * Params:
388 	 *     pos = position to get the sibling index for, -1 for the path head
389 	 *
390 	 * Return: 0 or the index into the list of siblings for the element at @pos.
391 	 */
392 	public uint iterGetSiblingIndex(int pos)
393 	{
394 		return gtk_widget_path_iter_get_sibling_index(gtkWidgetPath, pos);
395 	}
396 
397 	/**
398 	 * Returns the list of siblings for the element at @pos. If the element
399 	 * was not added with siblings, %NULL is returned.
400 	 *
401 	 * Params:
402 	 *     pos = position to get the siblings for, -1 for the path head
403 	 *
404 	 * Return: %NULL or the list of siblings for the element at @pos.
405 	 */
406 	public WidgetPath iterGetSiblings(int pos)
407 	{
408 		auto p = gtk_widget_path_iter_get_siblings(gtkWidgetPath, pos);
409 		
410 		if(p is null)
411 		{
412 			return null;
413 		}
414 		
415 		return ObjectG.getDObject!(WidgetPath)(cast(GtkWidgetPath*) p);
416 	}
417 
418 	/**
419 	 * Returns the state flags corresponding to the widget found at
420 	 * the position @pos in the widget hierarchy defined by
421 	 * @path
422 	 *
423 	 * Params:
424 	 *     pos = position to get the state for, -1 for the path head
425 	 *
426 	 * Return: The state flags
427 	 *
428 	 * Since: 3.14
429 	 */
430 	public GtkStateFlags iterGetState(int pos)
431 	{
432 		return gtk_widget_path_iter_get_state(gtkWidgetPath, pos);
433 	}
434 
435 	/**
436 	 * Returns %TRUE if the widget at position @pos has the class @name
437 	 * defined, %FALSE otherwise.
438 	 *
439 	 * Params:
440 	 *     pos = position to query, -1 for the path head
441 	 *     name = class name
442 	 *
443 	 * Return: %TRUE if the class @name is defined for the widget at @pos
444 	 *
445 	 * Since: 3.0
446 	 */
447 	public bool iterHasClass(int pos, string name)
448 	{
449 		return gtk_widget_path_iter_has_class(gtkWidgetPath, pos, Str.toStringz(name)) != 0;
450 	}
451 
452 	/**
453 	 * Returns %TRUE if the widget at position @pos has the name @name,
454 	 * %FALSE otherwise.
455 	 *
456 	 * Params:
457 	 *     pos = position to query, -1 for the path head
458 	 *     name = a widget name
459 	 *
460 	 * Return: %TRUE if the widget at @pos has this name
461 	 *
462 	 * Since: 3.0
463 	 */
464 	public bool iterHasName(int pos, string name)
465 	{
466 		return gtk_widget_path_iter_has_name(gtkWidgetPath, pos, Str.toStringz(name)) != 0;
467 	}
468 
469 	/**
470 	 * See gtk_widget_path_iter_has_class(). This is a version that operates
471 	 * with GQuarks.
472 	 *
473 	 * Params:
474 	 *     pos = position to query, -1 for the path head
475 	 *     qname = class name as a #GQuark
476 	 *
477 	 * Return: %TRUE if the widget at @pos has the class defined.
478 	 *
479 	 * Since: 3.0
480 	 */
481 	public bool iterHasQclass(int pos, GQuark qname)
482 	{
483 		return gtk_widget_path_iter_has_qclass(gtkWidgetPath, pos, qname) != 0;
484 	}
485 
486 	/**
487 	 * See gtk_widget_path_iter_has_name(). This is a version
488 	 * that operates on #GQuarks.
489 	 *
490 	 * Params:
491 	 *     pos = position to query, -1 for the path head
492 	 *     qname = widget name as a #GQuark
493 	 *
494 	 * Return: %TRUE if the widget at @pos has this name
495 	 *
496 	 * Since: 3.0
497 	 */
498 	public bool iterHasQname(int pos, GQuark qname)
499 	{
500 		return gtk_widget_path_iter_has_qname(gtkWidgetPath, pos, qname) != 0;
501 	}
502 
503 	/**
504 	 * See gtk_widget_path_iter_has_region(). This is a version that operates
505 	 * with GQuarks.
506 	 *
507 	 * Deprecated: The use of regions is deprecated.
508 	 *
509 	 * Params:
510 	 *     pos = position to query, -1 for the path head
511 	 *     qname = region name as a #GQuark
512 	 *     flags = return location for the region flags
513 	 *
514 	 * Return: %TRUE if the widget at @pos has the region defined.
515 	 *
516 	 * Since: 3.0
517 	 */
518 	public bool iterHasQregion(int pos, GQuark qname, out GtkRegionFlags flags)
519 	{
520 		return gtk_widget_path_iter_has_qregion(gtkWidgetPath, pos, qname, &flags) != 0;
521 	}
522 
523 	/**
524 	 * Returns %TRUE if the widget at position @pos has the class @name
525 	 * defined, %FALSE otherwise.
526 	 *
527 	 * Deprecated: The use of regions is deprecated.
528 	 *
529 	 * Params:
530 	 *     pos = position to query, -1 for the path head
531 	 *     name = region name
532 	 *     flags = return location for the region flags
533 	 *
534 	 * Return: %TRUE if the class @name is defined for the widget at @pos
535 	 *
536 	 * Since: 3.0
537 	 */
538 	public bool iterHasRegion(int pos, string name, out GtkRegionFlags flags)
539 	{
540 		return gtk_widget_path_iter_has_region(gtkWidgetPath, pos, Str.toStringz(name), &flags) != 0;
541 	}
542 
543 	/**
544 	 * Returns a list with all the class names defined for the widget
545 	 * at position @pos in the hierarchy defined in @path.
546 	 *
547 	 * Params:
548 	 *     pos = position to query, -1 for the path head
549 	 *
550 	 * Return: The list of
551 	 *     classes, This is a list of strings, the #GSList contents
552 	 *     are owned by GTK+, but you should use g_slist_free() to
553 	 *     free the list itself.
554 	 *
555 	 * Since: 3.0
556 	 */
557 	public ListSG iterListClasses(int pos)
558 	{
559 		auto p = gtk_widget_path_iter_list_classes(gtkWidgetPath, pos);
560 		
561 		if(p is null)
562 		{
563 			return null;
564 		}
565 		
566 		return new ListSG(cast(GSList*) p);
567 	}
568 
569 	/**
570 	 * Returns a list with all the region names defined for the widget
571 	 * at position @pos in the hierarchy defined in @path.
572 	 *
573 	 * Deprecated: The use of regions is deprecated.
574 	 *
575 	 * Params:
576 	 *     pos = position to query, -1 for the path head
577 	 *
578 	 * Return: The list of
579 	 *     regions, This is a list of strings, the #GSList contents
580 	 *     are owned by GTK+, but you should use g_slist_free() to
581 	 *     free the list itself.
582 	 *
583 	 * Since: 3.0
584 	 */
585 	public ListSG iterListRegions(int pos)
586 	{
587 		auto p = gtk_widget_path_iter_list_regions(gtkWidgetPath, pos);
588 		
589 		if(p is null)
590 		{
591 			return null;
592 		}
593 		
594 		return new ListSG(cast(GSList*) p);
595 	}
596 
597 	/**
598 	 * Removes the class @name from the widget at position @pos in
599 	 * the hierarchy defined in @path.
600 	 *
601 	 * Params:
602 	 *     pos = position to modify, -1 for the path head
603 	 *     name = class name
604 	 *
605 	 * Since: 3.0
606 	 */
607 	public void iterRemoveClass(int pos, string name)
608 	{
609 		gtk_widget_path_iter_remove_class(gtkWidgetPath, pos, Str.toStringz(name));
610 	}
611 
612 	/**
613 	 * Removes the region @name from the widget at position @pos in
614 	 * the hierarchy defined in @path.
615 	 *
616 	 * Deprecated: The use of regions is deprecated.
617 	 *
618 	 * Params:
619 	 *     pos = position to modify, -1 for the path head
620 	 *     name = region name
621 	 *
622 	 * Since: 3.0
623 	 */
624 	public void iterRemoveRegion(int pos, string name)
625 	{
626 		gtk_widget_path_iter_remove_region(gtkWidgetPath, pos, Str.toStringz(name));
627 	}
628 
629 	/**
630 	 * Sets the widget name for the widget found at position @pos
631 	 * in the widget hierarchy defined by @path.
632 	 *
633 	 * Params:
634 	 *     pos = position to modify, -1 for the path head
635 	 *     name = widget name
636 	 *
637 	 * Since: 3.0
638 	 */
639 	public void iterSetName(int pos, string name)
640 	{
641 		gtk_widget_path_iter_set_name(gtkWidgetPath, pos, Str.toStringz(name));
642 	}
643 
644 	/**
645 	 * Sets the object type for a given position in the widget hierarchy
646 	 * defined by @path.
647 	 *
648 	 * Params:
649 	 *     pos = position to modify, -1 for the path head
650 	 *     type = object type to set
651 	 *
652 	 * Since: 3.0
653 	 */
654 	public void iterSetObjectType(int pos, GType type)
655 	{
656 		gtk_widget_path_iter_set_object_type(gtkWidgetPath, pos, type);
657 	}
658 
659 	/**
660 	 * Sets the widget name for the widget found at position @pos
661 	 * in the widget hierarchy defined by @path.
662 	 *
663 	 * If you want to update just a single state flag, you need to do
664 	 * this manually, as this function updates all state flags.
665 	 *
666 	 * ## Setting a flag
667 	 *
668 	 * |[<!-- language="C" -->
669 	 * gtk_widget_path_iter_set_state (path, pos, gtk_widget_path_iter_get_state (path, pos) | flag);
670 	 * ]|
671 	 *
672 	 * ## Unsetting a flag
673 	 *
674 	 * |[<!-- language="C" -->
675 	 * gtk_widget_path_iter_set_state (path, pos, gtk_widget_path_iter_get_state (path, pos) & ~flag);
676 	 * ]|
677 	 *
678 	 * Params:
679 	 *     pos = position to modify, -1 for the path head
680 	 *     state = state flags
681 	 *
682 	 * Since: 3.14
683 	 */
684 	public void iterSetState(int pos, GtkStateFlags state)
685 	{
686 		gtk_widget_path_iter_set_state(gtkWidgetPath, pos, state);
687 	}
688 
689 	/**
690 	 * Returns the number of #GtkWidget #GTypes between the represented
691 	 * widget and its topmost container.
692 	 *
693 	 * Return: the number of elements in the path
694 	 *
695 	 * Since: 3.0
696 	 */
697 	public int length()
698 	{
699 		return gtk_widget_path_length(gtkWidgetPath);
700 	}
701 
702 	/**
703 	 * Prepends a widget type to the widget hierachy represented by @path.
704 	 *
705 	 * Params:
706 	 *     type = widget type to prepend
707 	 *
708 	 * Since: 3.0
709 	 */
710 	public void prependType(GType type)
711 	{
712 		gtk_widget_path_prepend_type(gtkWidgetPath, type);
713 	}
714 
715 	/**
716 	 * Increments the reference count on @path.
717 	 *
718 	 * Return: @path itself.
719 	 *
720 	 * Since: 3.2
721 	 */
722 	public WidgetPath doref()
723 	{
724 		auto p = gtk_widget_path_ref(gtkWidgetPath);
725 		
726 		if(p is null)
727 		{
728 			return null;
729 		}
730 		
731 		return ObjectG.getDObject!(WidgetPath)(cast(GtkWidgetPath*) p);
732 	}
733 
734 	/**
735 	 * Dumps the widget path into a string representation. It tries to match
736 	 * the CSS style as closely as possible (Note that there might be paths
737 	 * that cannot be represented in CSS).
738 	 *
739 	 * The main use of this code is for debugging purposes, so that you can
740 	 * g_print() the path or dump it in a gdb session.
741 	 *
742 	 * Return: A new string describing @path.
743 	 *
744 	 * Since: 3.2
745 	 */
746 	public override string toString()
747 	{
748 		return Str.toString(gtk_widget_path_to_string(gtkWidgetPath));
749 	}
750 
751 	/**
752 	 * Decrements the reference count on @path, freeing the structure
753 	 * if the reference count reaches 0.
754 	 *
755 	 * Since: 3.2
756 	 */
757 	public void unref()
758 	{
759 		gtk_widget_path_unref(gtkWidgetPath);
760 	}
761 }