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.IconTheme;
26 
27 private import cairo.Surface;
28 private import gdk.Screen;
29 private import gdk.Window;
30 private import gdkpixbuf.Pixbuf;
31 private import gio.IconIF;
32 private import glib.ConstructionException;
33 private import glib.ErrorG;
34 private import glib.GException;
35 private import glib.ListG;
36 private import glib.Str;
37 private import gobject.ObjectG;
38 private import gobject.Signals;
39 private import gtk.IconInfo;
40 public  import gtkc.gdktypes;
41 private import gtkc.gtk;
42 public  import gtkc.gtktypes;
43 
44 
45 /**
46  * #GtkIconTheme provides a facility for looking up icons by name
47  * and size. The main reason for using a name rather than simply
48  * providing a filename is to allow different icons to be used
49  * depending on what “icon theme” is selected
50  * by the user. The operation of icon themes on Linux and Unix
51  * follows the [Icon Theme Specification](http://www.freedesktop.org/Standards/icon-theme-spec)
52  * There is a fallback icon theme, named `hicolor`, where applications
53  * should install their icons, but additional icon themes can be installed
54  * as operating system vendors and users choose.
55  * 
56  * Named icons are similar to the deprecated [Stock Items][gtkstock],
57  * and the distinction between the two may be a bit confusing.
58  * A few things to keep in mind:
59  * 
60  * - Stock images usually are used in conjunction with
61  * [Stock Items][gtkstock], such as %GTK_STOCK_OK or
62  * %GTK_STOCK_OPEN. Named icons are easier to set up and therefore
63  * are more useful for new icons that an application wants to
64  * add, such as application icons or window icons.
65  * 
66  * - Stock images can only be loaded at the symbolic sizes defined
67  * by the #GtkIconSize enumeration, or by custom sizes defined
68  * by gtk_icon_size_register(), while named icons are more flexible
69  * and any pixel size can be specified.
70  * 
71  * - Because stock images are closely tied to stock items, and thus
72  * to actions in the user interface, stock images may come in
73  * multiple variants for different widget states or writing
74  * directions.
75  * 
76  * A good rule of thumb is that if there is a stock image for what
77  * you want to use, use it, otherwise use a named icon. It turns
78  * out that internally stock images are generally defined in
79  * terms of one or more named icons. (An example of the
80  * more than one case is icons that depend on writing direction;
81  * %GTK_STOCK_GO_FORWARD uses the two themed icons
82  * “gtk-stock-go-forward-ltr” and “gtk-stock-go-forward-rtl”.)
83  * 
84  * In many cases, named themes are used indirectly, via #GtkImage
85  * or stock items, rather than directly, but looking up icons
86  * directly is also simple. The #GtkIconTheme object acts
87  * as a database of all the icons in the current theme. You
88  * can create new #GtkIconTheme objects, but it’s much more
89  * efficient to use the standard icon theme for the #GdkScreen
90  * so that the icon information is shared with other people
91  * looking up icons.
92  * |[<!-- language="C" -->
93  * GError *error = NULL;
94  * GtkIconTheme *icon_theme;
95  * GdkPixbuf *pixbuf;
96  * 
97  * icon_theme = gtk_icon_theme_get_default ();
98  * pixbuf = gtk_icon_theme_load_icon (icon_theme,
99  * "my-icon-name", // icon name
100  * 48, // icon size
101  * 0,  // flags
102  * &error);
103  * if (!pixbuf)
104  * {
105  * g_warning ("Couldn’t load icon: %s", error->message);
106  * g_error_free (error);
107  * }
108  * else
109  * {
110  * // Use the pixbuf
111  * g_object_unref (pixbuf);
112  * }
113  * ]|
114  */
115 public class IconTheme : ObjectG
116 {
117 	/** the main Gtk struct */
118 	protected GtkIconTheme* gtkIconTheme;
119 
120 	/** Get the main Gtk struct */
121 	public GtkIconTheme* getIconThemeStruct()
122 	{
123 		return gtkIconTheme;
124 	}
125 
126 	/** the main Gtk struct as a void* */
127 	protected override void* getStruct()
128 	{
129 		return cast(void*)gtkIconTheme;
130 	}
131 
132 	protected override void setStruct(GObject* obj)
133 	{
134 		gtkIconTheme = cast(GtkIconTheme*)obj;
135 		super.setStruct(obj);
136 	}
137 
138 	/**
139 	 * Sets our main struct and passes it to the parent class.
140 	 */
141 	public this (GtkIconTheme* gtkIconTheme, bool ownedRef = false)
142 	{
143 		this.gtkIconTheme = gtkIconTheme;
144 		super(cast(GObject*)gtkIconTheme, ownedRef);
145 	}
146 
147 
148 	/** */
149 	public static GType getType()
150 	{
151 		return gtk_icon_theme_get_type();
152 	}
153 
154 	/**
155 	 * Creates a new icon theme object. Icon theme objects are used
156 	 * to lookup up an icon by name in a particular icon theme.
157 	 * Usually, you’ll want to use gtk_icon_theme_get_default()
158 	 * or gtk_icon_theme_get_for_screen() rather than creating
159 	 * a new icon theme object for scratch.
160 	 *
161 	 * Return: the newly created #GtkIconTheme object.
162 	 *
163 	 * Since: 2.4
164 	 *
165 	 * Throws: ConstructionException GTK+ fails to create the object.
166 	 */
167 	public this()
168 	{
169 		auto p = gtk_icon_theme_new();
170 		
171 		if(p is null)
172 		{
173 			throw new ConstructionException("null returned by new");
174 		}
175 		
176 		this(cast(GtkIconTheme*) p, true);
177 	}
178 
179 	/**
180 	 * Registers a built-in icon for icon theme lookups. The idea
181 	 * of built-in icons is to allow an application or library
182 	 * that uses themed icons to function requiring files to
183 	 * be present in the file system. For instance, the default
184 	 * images for all of GTK+’s stock icons are registered
185 	 * as built-icons.
186 	 *
187 	 * In general, if you use gtk_icon_theme_add_builtin_icon()
188 	 * you should also install the icon in the icon theme, so
189 	 * that the icon is generally available.
190 	 *
191 	 * This function will generally be used with pixbufs loaded
192 	 * via gdk_pixbuf_new_from_inline().
193 	 *
194 	 * Deprecated: Use gtk_icon_theme_add_resource_path()
195 	 * to add application-specific icons to the icon theme.
196 	 *
197 	 * Params:
198 	 *     iconName = the name of the icon to register
199 	 *     size = the size in pixels at which to register the icon (different
200 	 *         images can be registered for the same icon name at different sizes.)
201 	 *     pixbuf = #GdkPixbuf that contains the image to use for @icon_name
202 	 *
203 	 * Since: 2.4
204 	 */
205 	public static void addBuiltinIcon(string iconName, int size, Pixbuf pixbuf)
206 	{
207 		gtk_icon_theme_add_builtin_icon(Str.toStringz(iconName), size, (pixbuf is null) ? null : pixbuf.getPixbufStruct());
208 	}
209 
210 	/**
211 	 * Gets the icon theme for the default screen. See
212 	 * gtk_icon_theme_get_for_screen().
213 	 *
214 	 * Return: A unique #GtkIconTheme associated with
215 	 *     the default screen. This icon theme is associated with
216 	 *     the screen and can be used as long as the screen
217 	 *     is open. Do not ref or unref it.
218 	 *
219 	 * Since: 2.4
220 	 */
221 	public static IconTheme getDefault()
222 	{
223 		auto p = gtk_icon_theme_get_default();
224 		
225 		if(p is null)
226 		{
227 			return null;
228 		}
229 		
230 		return ObjectG.getDObject!(IconTheme)(cast(GtkIconTheme*) p);
231 	}
232 
233 	/**
234 	 * Gets the icon theme object associated with @screen; if this
235 	 * function has not previously been called for the given
236 	 * screen, a new icon theme object will be created and
237 	 * associated with the screen. Icon theme objects are
238 	 * fairly expensive to create, so using this function
239 	 * is usually a better choice than calling than gtk_icon_theme_new()
240 	 * and setting the screen yourself; by using this function
241 	 * a single icon theme object will be shared between users.
242 	 *
243 	 * Params:
244 	 *     screen = a #GdkScreen
245 	 *
246 	 * Return: A unique #GtkIconTheme associated with
247 	 *     the given screen. This icon theme is associated with
248 	 *     the screen and can be used as long as the screen
249 	 *     is open. Do not ref or unref it.
250 	 *
251 	 * Since: 2.4
252 	 */
253 	public static IconTheme getForScreen(Screen screen)
254 	{
255 		auto p = gtk_icon_theme_get_for_screen((screen is null) ? null : screen.getScreenStruct());
256 		
257 		if(p is null)
258 		{
259 			return null;
260 		}
261 		
262 		return ObjectG.getDObject!(IconTheme)(cast(GtkIconTheme*) p);
263 	}
264 
265 	/**
266 	 * Adds a resource path that will be looked at when looking
267 	 * for icons, similar to search paths.
268 	 *
269 	 * This function should be used to make application-specific icons
270 	 * available as part of the icon theme.
271 	 *
272 	 * The resources are considered as part of the hicolor icon theme
273 	 * and must be located in subdirectories that are defined in the
274 	 * hicolor icon theme, such as `@path/16x16/actions/run.png`.
275 	 * Icons that are directly placed in the resource path instead
276 	 * of a subdirectory are also considered as ultimate fallback.
277 	 *
278 	 * Params:
279 	 *     path = a resource path
280 	 *
281 	 * Since: 3.14
282 	 */
283 	public void addResourcePath(string path)
284 	{
285 		gtk_icon_theme_add_resource_path(gtkIconTheme, Str.toStringz(path));
286 	}
287 
288 	/**
289 	 * Appends a directory to the search path.
290 	 * See gtk_icon_theme_set_search_path().
291 	 *
292 	 * Params:
293 	 *     path = directory name to append to the icon path
294 	 *
295 	 * Since: 2.4
296 	 */
297 	public void appendSearchPath(string path)
298 	{
299 		gtk_icon_theme_append_search_path(gtkIconTheme, Str.toStringz(path));
300 	}
301 
302 	/**
303 	 * Looks up a named icon and returns a #GtkIconInfo containing
304 	 * information such as the filename of the icon. The icon
305 	 * can then be rendered into a pixbuf using
306 	 * gtk_icon_info_load_icon(). (gtk_icon_theme_load_icon()
307 	 * combines these two steps if all you need is the pixbuf.)
308 	 *
309 	 * If @icon_names contains more than one name, this function
310 	 * tries them all in the given order before falling back to
311 	 * inherited icon themes.
312 	 *
313 	 * Params:
314 	 *     iconNames = %NULL-terminated array of
315 	 *         icon names to lookup
316 	 *     size = desired icon size
317 	 *     flags = flags modifying the behavior of the icon lookup
318 	 *
319 	 * Return: a #GtkIconInfo object
320 	 *     containing information about the icon, or %NULL if the icon wasn’t
321 	 *     found.
322 	 *
323 	 * Since: 2.12
324 	 */
325 	public IconInfo chooseIcon(string iconNames, int size, GtkIconLookupFlags flags)
326 	{
327 		auto p = gtk_icon_theme_choose_icon(gtkIconTheme, Str.toStringz(iconNames), size, flags);
328 		
329 		if(p is null)
330 		{
331 			return null;
332 		}
333 		
334 		return ObjectG.getDObject!(IconInfo)(cast(GtkIconInfo*) p, true);
335 	}
336 
337 	/**
338 	 * Looks up a named icon for a particular window scale and returns
339 	 * a #GtkIconInfo containing information such as the filename of the
340 	 * icon. The icon can then be rendered into a pixbuf using
341 	 * gtk_icon_info_load_icon(). (gtk_icon_theme_load_icon()
342 	 * combines these two steps if all you need is the pixbuf.)
343 	 *
344 	 * If @icon_names contains more than one name, this function
345 	 * tries them all in the given order before falling back to
346 	 * inherited icon themes.
347 	 *
348 	 * Params:
349 	 *     iconNames = %NULL-terminated
350 	 *         array of icon names to lookup
351 	 *     size = desired icon size
352 	 *     scale = desired scale
353 	 *     flags = flags modifying the behavior of the icon lookup
354 	 *
355 	 * Return: a #GtkIconInfo object
356 	 *     containing information about the icon, or %NULL if the
357 	 *     icon wasn’t found.
358 	 *
359 	 * Since: 3.10
360 	 */
361 	public IconInfo chooseIconForScale(string iconNames, int size, int scale, GtkIconLookupFlags flags)
362 	{
363 		auto p = gtk_icon_theme_choose_icon_for_scale(gtkIconTheme, Str.toStringz(iconNames), size, scale, flags);
364 		
365 		if(p is null)
366 		{
367 			return null;
368 		}
369 		
370 		return ObjectG.getDObject!(IconInfo)(cast(GtkIconInfo*) p, true);
371 	}
372 
373 	/**
374 	 * Gets the name of an icon that is representative of the
375 	 * current theme (for instance, to use when presenting
376 	 * a list of themes to the user.)
377 	 *
378 	 * Return: the name of an example icon or %NULL.
379 	 *     Free with g_free().
380 	 *
381 	 * Since: 2.4
382 	 */
383 	public string getExampleIconName()
384 	{
385 		auto retStr = gtk_icon_theme_get_example_icon_name(gtkIconTheme);
386 		
387 		scope(exit) Str.freeString(retStr);
388 		return Str.toString(retStr);
389 	}
390 
391 	/**
392 	 * Returns an array of integers describing the sizes at which
393 	 * the icon is available without scaling. A size of -1 means
394 	 * that the icon is available in a scalable format. The array
395 	 * is zero-terminated.
396 	 *
397 	 * Params:
398 	 *     iconName = the name of an icon
399 	 *
400 	 * Return: An newly
401 	 *     allocated array describing the sizes at which the icon is
402 	 *     available. The array should be freed with g_free() when it is no
403 	 *     longer needed.
404 	 *
405 	 * Since: 2.6
406 	 */
407 	public int[] getIconSizes(string iconName)
408 	{
409 		auto p = gtk_icon_theme_get_icon_sizes(gtkIconTheme, Str.toStringz(iconName));
410 		
411 		return p[0 .. getArrayLength(p)];
412 	}
413 
414 	/**
415 	 * Gets the current search path. See gtk_icon_theme_set_search_path().
416 	 *
417 	 * Params:
418 	 *     path = location to store a list of icon theme path directories or %NULL.
419 	 *         The stored value should be freed with g_strfreev().
420 	 *     nElements = location to store number of elements in @path, or %NULL
421 	 *
422 	 * Since: 2.4
423 	 */
424 	public void getSearchPath(out string path)
425 	{
426 		char* outpath = null;
427 		int nElements;
428 		
429 		gtk_icon_theme_get_search_path(gtkIconTheme, &outpath, &nElements);
430 		
431 		path = Str.toString(outpath, nElements);
432 	}
433 
434 	/**
435 	 * Checks whether an icon theme includes an icon
436 	 * for a particular name.
437 	 *
438 	 * Params:
439 	 *     iconName = the name of an icon
440 	 *
441 	 * Return: %TRUE if @icon_theme includes an
442 	 *     icon for @icon_name.
443 	 *
444 	 * Since: 2.4
445 	 */
446 	public bool hasIcon(string iconName)
447 	{
448 		return gtk_icon_theme_has_icon(gtkIconTheme, Str.toStringz(iconName)) != 0;
449 	}
450 
451 	/**
452 	 * Gets the list of contexts available within the current
453 	 * hierarchy of icon themes.
454 	 * See gtk_icon_theme_list_icons() for details about contexts.
455 	 *
456 	 * Return: a #GList list
457 	 *     holding the names of all the contexts in the theme. You must first
458 	 *     free each element in the list with g_free(), then free the list
459 	 *     itself with g_list_free().
460 	 *
461 	 * Since: 2.12
462 	 */
463 	public ListG listContexts()
464 	{
465 		auto p = gtk_icon_theme_list_contexts(gtkIconTheme);
466 		
467 		if(p is null)
468 		{
469 			return null;
470 		}
471 		
472 		return new ListG(cast(GList*) p, true);
473 	}
474 
475 	/**
476 	 * Lists the icons in the current icon theme. Only a subset
477 	 * of the icons can be listed by providing a context string.
478 	 * The set of values for the context string is system dependent,
479 	 * but will typically include such values as “Applications” and
480 	 * “MimeTypes”. Contexts are explained in the
481 	 * [Icon Theme Specification](http://www.freedesktop.org/wiki/Specifications/icon-theme-spec).
482 	 * The standard contexts are listed in the
483 	 * [Icon Naming Specification](http://www.freedesktop.org/wiki/Specifications/icon-naming-spec).
484 	 * Also see gtk_icon_theme_list_contexts().
485 	 *
486 	 * Params:
487 	 *     context = a string identifying a particular type of
488 	 *         icon, or %NULL to list all icons.
489 	 *
490 	 * Return: a #GList list
491 	 *     holding the names of all the icons in the theme. You must
492 	 *     first free each element in the list with g_free(), then
493 	 *     free the list itself with g_list_free().
494 	 *
495 	 * Since: 2.4
496 	 */
497 	public ListG listIcons(string context)
498 	{
499 		auto p = gtk_icon_theme_list_icons(gtkIconTheme, Str.toStringz(context));
500 		
501 		if(p is null)
502 		{
503 			return null;
504 		}
505 		
506 		return new ListG(cast(GList*) p, true);
507 	}
508 
509 	/**
510 	 * Looks up an icon in an icon theme, scales it to the given size
511 	 * and renders it into a pixbuf. This is a convenience function;
512 	 * if more details about the icon are needed, use
513 	 * gtk_icon_theme_lookup_icon() followed by gtk_icon_info_load_icon().
514 	 *
515 	 * Note that you probably want to listen for icon theme changes and
516 	 * update the icon. This is usually done by connecting to the
517 	 * GtkWidget::style-set signal. If for some reason you do not want to
518 	 * update the icon when the icon theme changes, you should consider
519 	 * using gdk_pixbuf_copy() to make a private copy of the pixbuf
520 	 * returned by this function. Otherwise GTK+ may need to keep the old
521 	 * icon theme loaded, which would be a waste of memory.
522 	 *
523 	 * Params:
524 	 *     iconName = the name of the icon to lookup
525 	 *     size = the desired icon size. The resulting icon may not be
526 	 *         exactly this size; see gtk_icon_info_load_icon().
527 	 *     flags = flags modifying the behavior of the icon lookup
528 	 *
529 	 * Return: the rendered icon; this may be
530 	 *     a newly created icon or a new reference to an internal icon, so
531 	 *     you must not modify the icon. Use g_object_unref() to release
532 	 *     your reference to the icon. %NULL if the icon isn’t found.
533 	 *
534 	 * Since: 2.4
535 	 *
536 	 * Throws: GException on failure.
537 	 */
538 	public Pixbuf loadIcon(string iconName, int size, GtkIconLookupFlags flags)
539 	{
540 		GError* err = null;
541 		
542 		auto p = gtk_icon_theme_load_icon(gtkIconTheme, Str.toStringz(iconName), size, flags, &err);
543 		
544 		if (err !is null)
545 		{
546 			throw new GException( new ErrorG(err) );
547 		}
548 		
549 		if(p is null)
550 		{
551 			return null;
552 		}
553 		
554 		return ObjectG.getDObject!(Pixbuf)(cast(GdkPixbuf*) p, true);
555 	}
556 
557 	/**
558 	 * Looks up an icon in an icon theme for a particular window scale,
559 	 * scales it to the given size and renders it into a pixbuf. This is a
560 	 * convenience function; if more details about the icon are needed,
561 	 * use gtk_icon_theme_lookup_icon() followed by
562 	 * gtk_icon_info_load_icon().
563 	 *
564 	 * Note that you probably want to listen for icon theme changes and
565 	 * update the icon. This is usually done by connecting to the
566 	 * GtkWidget::style-set signal. If for some reason you do not want to
567 	 * update the icon when the icon theme changes, you should consider
568 	 * using gdk_pixbuf_copy() to make a private copy of the pixbuf
569 	 * returned by this function. Otherwise GTK+ may need to keep the old
570 	 * icon theme loaded, which would be a waste of memory.
571 	 *
572 	 * Params:
573 	 *     iconName = the name of the icon to lookup
574 	 *     size = the desired icon size. The resulting icon may not be
575 	 *         exactly this size; see gtk_icon_info_load_icon().
576 	 *     scale = desired scale
577 	 *     flags = flags modifying the behavior of the icon lookup
578 	 *
579 	 * Return: the rendered icon; this may be
580 	 *     a newly created icon or a new reference to an internal icon, so
581 	 *     you must not modify the icon. Use g_object_unref() to release
582 	 *     your reference to the icon. %NULL if the icon isn’t found.
583 	 *
584 	 * Since: 3.10
585 	 *
586 	 * Throws: GException on failure.
587 	 */
588 	public Pixbuf loadIconForScale(string iconName, int size, int scale, GtkIconLookupFlags flags)
589 	{
590 		GError* err = null;
591 		
592 		auto p = gtk_icon_theme_load_icon_for_scale(gtkIconTheme, Str.toStringz(iconName), size, scale, flags, &err);
593 		
594 		if (err !is null)
595 		{
596 			throw new GException( new ErrorG(err) );
597 		}
598 		
599 		if(p is null)
600 		{
601 			return null;
602 		}
603 		
604 		return ObjectG.getDObject!(Pixbuf)(cast(GdkPixbuf*) p, true);
605 	}
606 
607 	/**
608 	 * Looks up an icon in an icon theme for a particular window scale,
609 	 * scales it to the given size and renders it into a cairo surface. This is a
610 	 * convenience function; if more details about the icon are needed,
611 	 * use gtk_icon_theme_lookup_icon() followed by
612 	 * gtk_icon_info_load_surface().
613 	 *
614 	 * Note that you probably want to listen for icon theme changes and
615 	 * update the icon. This is usually done by connecting to the
616 	 * GtkWidget::style-set signal.
617 	 *
618 	 * Params:
619 	 *     iconName = the name of the icon to lookup
620 	 *     size = the desired icon size. The resulting icon may not be
621 	 *         exactly this size; see gtk_icon_info_load_icon().
622 	 *     scale = desired scale
623 	 *     forWindow = #GdkWindow to optimize drawing for, or %NULL
624 	 *     flags = flags modifying the behavior of the icon lookup
625 	 *
626 	 * Return: the rendered icon; this may be
627 	 *     a newly created icon or a new reference to an internal icon, so
628 	 *     you must not modify the icon. Use cairo_surface_destroy() to
629 	 *     release your reference to the icon. %NULL if the icon isn’t
630 	 *     found.
631 	 *
632 	 * Since: 3.10
633 	 *
634 	 * Throws: GException on failure.
635 	 */
636 	public Surface loadSurface(string iconName, int size, int scale, Window forWindow, GtkIconLookupFlags flags)
637 	{
638 		GError* err = null;
639 		
640 		auto p = gtk_icon_theme_load_surface(gtkIconTheme, Str.toStringz(iconName), size, scale, (forWindow is null) ? null : forWindow.getWindowStruct(), flags, &err);
641 		
642 		if (err !is null)
643 		{
644 			throw new GException( new ErrorG(err) );
645 		}
646 		
647 		if(p is null)
648 		{
649 			return null;
650 		}
651 		
652 		return new Surface(cast(cairo_surface_t*) p);
653 	}
654 
655 	/**
656 	 * Looks up an icon and returns a #GtkIconInfo containing information
657 	 * such as the filename of the icon. The icon can then be rendered
658 	 * into a pixbuf using gtk_icon_info_load_icon().
659 	 *
660 	 * When rendering on displays with high pixel densities you should not
661 	 * use a @size multiplied by the scaling factor returned by functions
662 	 * like gdk_window_get_scale_factor(). Instead, you should use
663 	 * gtk_icon_theme_lookup_by_gicon_for_scale(), as the assets loaded
664 	 * for a given scaling factor may be different.
665 	 *
666 	 * Params:
667 	 *     icon = the #GIcon to look up
668 	 *     size = desired icon size
669 	 *     flags = flags modifying the behavior of the icon lookup
670 	 *
671 	 * Return: a #GtkIconInfo containing
672 	 *     information about the icon, or %NULL if the icon wasn’t
673 	 *     found. Unref with g_object_unref()
674 	 *
675 	 * Since: 2.14
676 	 */
677 	public IconInfo lookupByGicon(IconIF icon, int size, GtkIconLookupFlags flags)
678 	{
679 		auto p = gtk_icon_theme_lookup_by_gicon(gtkIconTheme, (icon is null) ? null : icon.getIconStruct(), size, flags);
680 		
681 		if(p is null)
682 		{
683 			return null;
684 		}
685 		
686 		return ObjectG.getDObject!(IconInfo)(cast(GtkIconInfo*) p, true);
687 	}
688 
689 	/**
690 	 * Looks up an icon and returns a #GtkIconInfo containing information
691 	 * such as the filename of the icon. The icon can then be rendered into
692 	 * a pixbuf using gtk_icon_info_load_icon().
693 	 *
694 	 * Params:
695 	 *     icon = the #GIcon to look up
696 	 *     size = desired icon size
697 	 *     scale = the desired scale
698 	 *     flags = flags modifying the behavior of the icon lookup
699 	 *
700 	 * Return: a #GtkIconInfo containing
701 	 *     information about the icon, or %NULL if the icon wasn’t
702 	 *     found. Unref with g_object_unref()
703 	 *
704 	 * Since: 3.10
705 	 */
706 	public IconInfo lookupByGiconForScale(IconIF icon, int size, int scale, GtkIconLookupFlags flags)
707 	{
708 		auto p = gtk_icon_theme_lookup_by_gicon_for_scale(gtkIconTheme, (icon is null) ? null : icon.getIconStruct(), size, scale, flags);
709 		
710 		if(p is null)
711 		{
712 			return null;
713 		}
714 		
715 		return ObjectG.getDObject!(IconInfo)(cast(GtkIconInfo*) p, true);
716 	}
717 
718 	/**
719 	 * Looks up a named icon and returns a #GtkIconInfo containing
720 	 * information such as the filename of the icon. The icon
721 	 * can then be rendered into a pixbuf using
722 	 * gtk_icon_info_load_icon(). (gtk_icon_theme_load_icon()
723 	 * combines these two steps if all you need is the pixbuf.)
724 	 *
725 	 * When rendering on displays with high pixel densities you should not
726 	 * use a @size multiplied by the scaling factor returned by functions
727 	 * like gdk_window_get_scale_factor(). Instead, you should use
728 	 * gtk_icon_theme_lookup_icon_for_scale(), as the assets loaded
729 	 * for a given scaling factor may be different.
730 	 *
731 	 * Params:
732 	 *     iconName = the name of the icon to lookup
733 	 *     size = desired icon size
734 	 *     flags = flags modifying the behavior of the icon lookup
735 	 *
736 	 * Return: a #GtkIconInfo object
737 	 *     containing information about the icon, or %NULL if the
738 	 *     icon wasn’t found.
739 	 *
740 	 * Since: 2.4
741 	 */
742 	public IconInfo lookupIcon(string iconName, int size, GtkIconLookupFlags flags)
743 	{
744 		auto p = gtk_icon_theme_lookup_icon(gtkIconTheme, Str.toStringz(iconName), size, flags);
745 		
746 		if(p is null)
747 		{
748 			return null;
749 		}
750 		
751 		return ObjectG.getDObject!(IconInfo)(cast(GtkIconInfo*) p, true);
752 	}
753 
754 	/**
755 	 * Looks up a named icon for a particular window scale and returns a
756 	 * #GtkIconInfo containing information such as the filename of the
757 	 * icon. The icon can then be rendered into a pixbuf using
758 	 * gtk_icon_info_load_icon(). (gtk_icon_theme_load_icon() combines
759 	 * these two steps if all you need is the pixbuf.)
760 	 *
761 	 * Params:
762 	 *     iconName = the name of the icon to lookup
763 	 *     size = desired icon size
764 	 *     scale = the desired scale
765 	 *     flags = flags modifying the behavior of the icon lookup
766 	 *
767 	 * Return: a #GtkIconInfo object
768 	 *     containing information about the icon, or %NULL if the
769 	 *     icon wasn’t found.
770 	 *
771 	 * Since: 3.10
772 	 */
773 	public IconInfo lookupIconForScale(string iconName, int size, int scale, GtkIconLookupFlags flags)
774 	{
775 		auto p = gtk_icon_theme_lookup_icon_for_scale(gtkIconTheme, Str.toStringz(iconName), size, scale, flags);
776 		
777 		if(p is null)
778 		{
779 			return null;
780 		}
781 		
782 		return ObjectG.getDObject!(IconInfo)(cast(GtkIconInfo*) p, true);
783 	}
784 
785 	/**
786 	 * Prepends a directory to the search path.
787 	 * See gtk_icon_theme_set_search_path().
788 	 *
789 	 * Params:
790 	 *     path = directory name to prepend to the icon path
791 	 *
792 	 * Since: 2.4
793 	 */
794 	public void prependSearchPath(string path)
795 	{
796 		gtk_icon_theme_prepend_search_path(gtkIconTheme, Str.toStringz(path));
797 	}
798 
799 	/**
800 	 * Checks to see if the icon theme has changed; if it has, any
801 	 * currently cached information is discarded and will be reloaded
802 	 * next time @icon_theme is accessed.
803 	 *
804 	 * Return: %TRUE if the icon theme has changed and needed
805 	 *     to be reloaded.
806 	 *
807 	 * Since: 2.4
808 	 */
809 	public bool rescanIfNeeded()
810 	{
811 		return gtk_icon_theme_rescan_if_needed(gtkIconTheme) != 0;
812 	}
813 
814 	/**
815 	 * Sets the name of the icon theme that the #GtkIconTheme object uses
816 	 * overriding system configuration. This function cannot be called
817 	 * on the icon theme objects returned from gtk_icon_theme_get_default()
818 	 * and gtk_icon_theme_get_for_screen().
819 	 *
820 	 * Params:
821 	 *     themeName = name of icon theme to use instead of
822 	 *         configured theme, or %NULL to unset a previously set custom theme
823 	 *
824 	 * Since: 2.4
825 	 */
826 	public void setCustomTheme(string themeName)
827 	{
828 		gtk_icon_theme_set_custom_theme(gtkIconTheme, Str.toStringz(themeName));
829 	}
830 
831 	/**
832 	 * Sets the screen for an icon theme; the screen is used
833 	 * to track the user’s currently configured icon theme,
834 	 * which might be different for different screens.
835 	 *
836 	 * Params:
837 	 *     screen = a #GdkScreen
838 	 *
839 	 * Since: 2.4
840 	 */
841 	public void setScreen(Screen screen)
842 	{
843 		gtk_icon_theme_set_screen(gtkIconTheme, (screen is null) ? null : screen.getScreenStruct());
844 	}
845 
846 	/**
847 	 * Sets the search path for the icon theme object. When looking
848 	 * for an icon theme, GTK+ will search for a subdirectory of
849 	 * one or more of the directories in @path with the same name
850 	 * as the icon theme containing an index.theme file. (Themes from
851 	 * multiple of the path elements are combined to allow themes to be
852 	 * extended by adding icons in the user’s home directory.)
853 	 *
854 	 * In addition if an icon found isn’t found either in the current
855 	 * icon theme or the default icon theme, and an image file with
856 	 * the right name is found directly in one of the elements of
857 	 * @path, then that image will be used for the icon name.
858 	 * (This is legacy feature, and new icons should be put
859 	 * into the fallback icon theme, which is called hicolor,
860 	 * rather than directly on the icon path.)
861 	 *
862 	 * Params:
863 	 *     path = array of
864 	 *         directories that are searched for icon themes
865 	 *     nElements = number of elements in @path.
866 	 *
867 	 * Since: 2.4
868 	 */
869 	public void setSearchPath(string[] path)
870 	{
871 		gtk_icon_theme_set_search_path(gtkIconTheme, Str.toStringzArray(path), cast(int)path.length);
872 	}
873 
874 	int[string] connectedSignals;
875 
876 	void delegate(IconTheme)[] onChangedListeners;
877 	/**
878 	 * Emitted when the current icon theme is switched or GTK+ detects
879 	 * that a change has occurred in the contents of the current
880 	 * icon theme.
881 	 */
882 	void addOnChanged(void delegate(IconTheme) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
883 	{
884 		if ( "changed" !in connectedSignals )
885 		{
886 			Signals.connectData(
887 				this,
888 				"changed",
889 				cast(GCallback)&callBackChanged,
890 				cast(void*)this,
891 				null,
892 				connectFlags);
893 			connectedSignals["changed"] = 1;
894 		}
895 		onChangedListeners ~= dlg;
896 	}
897 	extern(C) static void callBackChanged(GtkIconTheme* iconthemeStruct, IconTheme _icontheme)
898 	{
899 		foreach ( void delegate(IconTheme) dlg; _icontheme.onChangedListeners )
900 		{
901 			dlg(_icontheme);
902 		}
903 	}
904 }