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.Picture;
26 
27 private import gdk.PaintableIF;
28 private import gdkpixbuf.Pixbuf;
29 private import gio.FileIF;
30 private import glib.ConstructionException;
31 private import glib.Str;
32 private import glib.c.functions;
33 private import gobject.ObjectG;
34 private import gtk.Widget;
35 private import gtk.c.functions;
36 public  import gtk.c.types;
37 
38 
39 /**
40  * The `GtkPicture` widget displays a `GdkPaintable`.
41  * 
42  * ![An example GtkPicture](picture.png)
43  * 
44  * Many convenience functions are provided to make pictures simple to use.
45  * For example, if you want to load an image from a file, and then display
46  * it, there’s a convenience function to do this:
47  * 
48  * ```c
49  * GtkWidget *widget = gtk_picture_new_for_filename ("myfile.png");
50  * ```
51  * 
52  * If the file isn’t loaded successfully, the picture will contain a
53  * “broken image” icon similar to that used in many web browsers.
54  * If you want to handle errors in loading the file yourself,
55  * for example by displaying an error message, then load the image with
56  * [ctor@Gdk.Texture.new_from_file], then create the `GtkPicture` with
57  * [ctor@Gtk.Picture.new_for_paintable].
58  * 
59  * Sometimes an application will want to avoid depending on external data
60  * files, such as image files. See the documentation of `GResource` for details.
61  * In this case, [ctor@Gtk.Picture.new_for_resource] and
62  * [method@Gtk.Picture.set_resource] should be used.
63  * 
64  * `GtkPicture` displays an image at its natural size. See [class@Gtk.Image]
65  * if you want to display a fixed-size image, such as an icon.
66  * 
67  * ## Sizing the paintable
68  * 
69  * You can influence how the paintable is displayed inside the `GtkPicture`.
70  * By turning off [property@Gtk.Picture:keep-aspect-ratio] you can allow the
71  * paintable to get stretched. [property@Gtk.Picture:can-shrink] can be unset
72  * to make sure that paintables are never made smaller than their ideal size -
73  * but be careful if you do not know the size of the paintable in use (like
74  * when displaying user-loaded images). This can easily cause the picture to
75  * grow larger than the screen. And [property@GtkWidget:halign] and
76  * [property@GtkWidget:valign] can be used to make sure the paintable doesn't
77  * fill all available space but is instead displayed at its original size.
78  * 
79  * ## CSS nodes
80  * 
81  * `GtkPicture` has a single CSS node with the name `picture`.
82  * 
83  * ## Accessibility
84  * 
85  * `GtkPicture` uses the `GTK_ACCESSIBLE_ROLE_IMG` role.
86  */
87 public class Picture : Widget
88 {
89 	/** the main Gtk struct */
90 	protected GtkPicture* gtkPicture;
91 
92 	/** Get the main Gtk struct */
93 	public GtkPicture* getPictureStruct(bool transferOwnership = false)
94 	{
95 		if (transferOwnership)
96 			ownedRef = false;
97 		return gtkPicture;
98 	}
99 
100 	/** the main Gtk struct as a void* */
101 	protected override void* getStruct()
102 	{
103 		return cast(void*)gtkPicture;
104 	}
105 
106 	/**
107 	 * Sets our main struct and passes it to the parent class.
108 	 */
109 	public this (GtkPicture* gtkPicture, bool ownedRef = false)
110 	{
111 		this.gtkPicture = gtkPicture;
112 		super(cast(GtkWidget*)gtkPicture, ownedRef);
113 	}
114 
115 
116 	/** */
117 	public static GType getType()
118 	{
119 		return gtk_picture_get_type();
120 	}
121 
122 	/**
123 	 * Creates a new empty `GtkPicture` widget.
124 	 *
125 	 * Returns: a newly created `GtkPicture` widget.
126 	 *
127 	 * Throws: ConstructionException GTK+ fails to create the object.
128 	 */
129 	public this()
130 	{
131 		auto __p = gtk_picture_new();
132 
133 		if(__p is null)
134 		{
135 			throw new ConstructionException("null returned by new");
136 		}
137 
138 		this(cast(GtkPicture*) __p);
139 	}
140 
141 	/**
142 	 * Creates a new `GtkPicture` displaying the given @file.
143 	 *
144 	 * If the file isn’t found or can’t be loaded, the resulting
145 	 * `GtkPicture` is empty.
146 	 *
147 	 * If you need to detect failures to load the file, use
148 	 * [ctor@Gdk.Texture.new_from_file] to load the file yourself,
149 	 * then create the `GtkPicture` from the texture.
150 	 *
151 	 * Params:
152 	 *     file = a `GFile`
153 	 *
154 	 * Returns: a new `GtkPicture`
155 	 *
156 	 * Throws: ConstructionException GTK+ fails to create the object.
157 	 */
158 	public this(FileIF file)
159 	{
160 		auto __p = gtk_picture_new_for_file((file is null) ? null : file.getFileStruct());
161 
162 		if(__p is null)
163 		{
164 			throw new ConstructionException("null returned by new_for_file");
165 		}
166 
167 		this(cast(GtkPicture*) __p);
168 	}
169 
170 	/**
171 	 * Creates a new `GtkPicture` displaying the file @filename.
172 	 *
173 	 * This is a utility function that calls [ctor@Gtk.Picture.new_for_file].
174 	 * See that function for details.
175 	 *
176 	 * Params:
177 	 *     filename = a filename
178 	 *
179 	 * Returns: a new `GtkPicture`
180 	 *
181 	 * Throws: ConstructionException GTK+ fails to create the object.
182 	 */
183 	public this(string filename)
184 	{
185 		auto __p = gtk_picture_new_for_filename(Str.toStringz(filename));
186 
187 		if(__p is null)
188 		{
189 			throw new ConstructionException("null returned by new_for_filename");
190 		}
191 
192 		this(cast(GtkPicture*) __p);
193 	}
194 
195 	/**
196 	 * Creates a new `GtkPicture` displaying @paintable.
197 	 *
198 	 * The `GtkPicture` will track changes to the @paintable and update
199 	 * its size and contents in response to it.
200 	 *
201 	 * Params:
202 	 *     paintable = a `GdkPaintable`, or %NULL
203 	 *
204 	 * Returns: a new `GtkPicture`
205 	 *
206 	 * Throws: ConstructionException GTK+ fails to create the object.
207 	 */
208 	public this(PaintableIF paintable)
209 	{
210 		auto __p = gtk_picture_new_for_paintable((paintable is null) ? null : paintable.getPaintableStruct());
211 
212 		if(__p is null)
213 		{
214 			throw new ConstructionException("null returned by new_for_paintable");
215 		}
216 
217 		this(cast(GtkPicture*) __p);
218 	}
219 
220 	/**
221 	 * Creates a new `GtkPicture` displaying @pixbuf.
222 	 *
223 	 * This is a utility function that calls [ctor@Gtk.Picture.new_for_paintable],
224 	 * See that function for details.
225 	 *
226 	 * The pixbuf must not be modified after passing it to this function.
227 	 *
228 	 * Params:
229 	 *     pixbuf = a `GdkPixbuf`, or %NULL
230 	 *
231 	 * Returns: a new `GtkPicture`
232 	 *
233 	 * Throws: ConstructionException GTK+ fails to create the object.
234 	 */
235 	public this(Pixbuf pixbuf)
236 	{
237 		auto __p = gtk_picture_new_for_pixbuf((pixbuf is null) ? null : pixbuf.getPixbufStruct());
238 
239 		if(__p is null)
240 		{
241 			throw new ConstructionException("null returned by new_for_pixbuf");
242 		}
243 
244 		this(cast(GtkPicture*) __p);
245 	}
246 
247 	/**
248 	 * Gets the alternative textual description of the picture.
249 	 *
250 	 * The returned string will be %NULL if the picture cannot be described textually.
251 	 *
252 	 * Returns: the alternative textual description of @self.
253 	 */
254 	public string getAlternativeText()
255 	{
256 		return Str.toString(gtk_picture_get_alternative_text(gtkPicture));
257 	}
258 
259 	/**
260 	 * Returns whether the `GtkPicture` respects its contents size.
261 	 *
262 	 * Returns: %TRUE if the picture can be made smaller than its contents
263 	 */
264 	public bool getCanShrink()
265 	{
266 		return gtk_picture_get_can_shrink(gtkPicture) != 0;
267 	}
268 
269 	/**
270 	 * Gets the `GFile` currently displayed if @self is displaying a file.
271 	 *
272 	 * If @self is not displaying a file, for example when
273 	 * [method@Gtk.Picture.set_paintable] was used, then %NULL is returned.
274 	 *
275 	 * Returns: The `GFile` displayed by @self.
276 	 */
277 	public FileIF getFile()
278 	{
279 		auto __p = gtk_picture_get_file(gtkPicture);
280 
281 		if(__p is null)
282 		{
283 			return null;
284 		}
285 
286 		return ObjectG.getDObject!(FileIF)(cast(GFile*) __p);
287 	}
288 
289 	/**
290 	 * Returns whether the `GtkPicture` preserves its contents aspect ratio.
291 	 *
292 	 * Returns: %TRUE if the self tries to keep the contents' aspect ratio
293 	 */
294 	public bool getKeepAspectRatio()
295 	{
296 		return gtk_picture_get_keep_aspect_ratio(gtkPicture) != 0;
297 	}
298 
299 	/**
300 	 * Gets the `GdkPaintable` being displayed by the `GtkPicture`.
301 	 *
302 	 * Returns: the displayed paintable, or %NULL if
303 	 *     the picture is empty
304 	 */
305 	public PaintableIF getPaintable()
306 	{
307 		auto __p = gtk_picture_get_paintable(gtkPicture);
308 
309 		if(__p is null)
310 		{
311 			return null;
312 		}
313 
314 		return ObjectG.getDObject!(PaintableIF)(cast(GdkPaintable*) __p);
315 	}
316 
317 	/**
318 	 * Sets an alternative textual description for the picture contents.
319 	 *
320 	 * It is equivalent to the "alt" attribute for images on websites.
321 	 *
322 	 * This text will be made available to accessibility tools.
323 	 *
324 	 * If the picture cannot be described textually, set this property to %NULL.
325 	 *
326 	 * Params:
327 	 *     alternativeText = a textual description of the contents
328 	 */
329 	public void setAlternativeText(string alternativeText)
330 	{
331 		gtk_picture_set_alternative_text(gtkPicture, Str.toStringz(alternativeText));
332 	}
333 
334 	/**
335 	 * If set to %TRUE, the @self can be made smaller than its contents.
336 	 *
337 	 * The contents will then be scaled down when rendering.
338 	 *
339 	 * If you want to still force a minimum size manually, consider using
340 	 * [method@Gtk.Widget.set_size_request].
341 	 *
342 	 * Also of note is that a similar function for growing does not exist
343 	 * because the grow behavior can be controlled via
344 	 * [method@Gtk.Widget.set_halign] and [method@Gtk.Widget.set_valign].
345 	 *
346 	 * Params:
347 	 *     canShrink = if @self can be made smaller than its contents
348 	 */
349 	public void setCanShrink(bool canShrink)
350 	{
351 		gtk_picture_set_can_shrink(gtkPicture, canShrink);
352 	}
353 
354 	/**
355 	 * Makes @self load and display @file.
356 	 *
357 	 * See [ctor@Gtk.Picture.new_for_file] for details.
358 	 *
359 	 * Params:
360 	 *     file = a `GFile` or %NULL
361 	 */
362 	public void setFile(FileIF file)
363 	{
364 		gtk_picture_set_file(gtkPicture, (file is null) ? null : file.getFileStruct());
365 	}
366 
367 	/**
368 	 * Makes @self load and display the given @filename.
369 	 *
370 	 * This is a utility function that calls [method@Gtk.Picture.set_file].
371 	 *
372 	 * Params:
373 	 *     filename = the filename to play
374 	 */
375 	public void setFilename(string filename)
376 	{
377 		gtk_picture_set_filename(gtkPicture, Str.toStringz(filename));
378 	}
379 
380 	/**
381 	 * If set to %TRUE, the @self will render its contents according to
382 	 * their aspect ratio.
383 	 *
384 	 * That means that empty space may show up at the top/bottom or
385 	 * left/right of @self.
386 	 *
387 	 * If set to %FALSE or if the contents provide no aspect ratio,
388 	 * the contents will be stretched over the picture's whole area.
389 	 *
390 	 * Params:
391 	 *     keepAspectRatio = whether to keep aspect ratio
392 	 */
393 	public void setKeepAspectRatio(bool keepAspectRatio)
394 	{
395 		gtk_picture_set_keep_aspect_ratio(gtkPicture, keepAspectRatio);
396 	}
397 
398 	/**
399 	 * Makes @self display the given @paintable.
400 	 *
401 	 * If @paintable is %NULL, nothing will be displayed.
402 	 *
403 	 * See [ctor@Gtk.Picture.new_for_paintable] for details.
404 	 *
405 	 * Params:
406 	 *     paintable = a `GdkPaintable` or %NULL
407 	 */
408 	public void setPaintable(PaintableIF paintable)
409 	{
410 		gtk_picture_set_paintable(gtkPicture, (paintable is null) ? null : paintable.getPaintableStruct());
411 	}
412 
413 	/**
414 	 * Sets a `GtkPicture` to show a `GdkPixbuf`.
415 	 *
416 	 * See [ctor@Gtk.Picture.new_for_pixbuf] for details.
417 	 *
418 	 * This is a utility function that calls [method@Gtk.Picture.set_paintable].
419 	 *
420 	 * Params:
421 	 *     pixbuf = a `GdkPixbuf` or %NULL
422 	 */
423 	public void setPixbuf(Pixbuf pixbuf)
424 	{
425 		gtk_picture_set_pixbuf(gtkPicture, (pixbuf is null) ? null : pixbuf.getPixbufStruct());
426 	}
427 
428 	/**
429 	 * Makes @self load and display the resource at the given
430 	 * @resource_path.
431 	 *
432 	 * This is a utility function that calls [method@Gtk.Picture.set_file].
433 	 *
434 	 * Params:
435 	 *     resourcePath = the resource to set
436 	 */
437 	public void setResource(string resourcePath)
438 	{
439 		gtk_picture_set_resource(gtkPicture, Str.toStringz(resourcePath));
440 	}
441 }