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.Clipboard;
26 
27 private import gdk.Display;
28 private import gdk.Event;
29 private import gdkpixbuf.Pixbuf;
30 private import glib.Str;
31 private import gobject.ObjectG;
32 private import gobject.Signals;
33 private import gtk.SelectionData;
34 private import gtk.TargetEntry;
35 private import gtk.TextBuffer;
36 public  import gtkc.gdktypes;
37 private import gtkc.gtk;
38 public  import gtkc.gtktypes;
39 
40 
41 /**
42  * The #GtkClipboard object represents a clipboard of data shared
43  * between different processes or between different widgets in
44  * the same process. Each clipboard is identified by a name encoded as a
45  * #GdkAtom. (Conversion to and from strings can be done with
46  * gdk_atom_intern() and gdk_atom_name().) The default clipboard
47  * corresponds to the “CLIPBOARD” atom; another commonly used clipboard
48  * is the “PRIMARY” clipboard, which, in X, traditionally contains
49  * the currently selected text.
50  * 
51  * To support having a number of different formats on the clipboard
52  * at the same time, the clipboard mechanism allows providing
53  * callbacks instead of the actual data.  When you set the contents
54  * of the clipboard, you can either supply the data directly (via
55  * functions like gtk_clipboard_set_text()), or you can supply a
56  * callback to be called at a later time when the data is needed (via
57  * gtk_clipboard_set_with_data() or gtk_clipboard_set_with_owner().)
58  * Providing a callback also avoids having to make copies of the data
59  * when it is not needed.
60  * 
61  * gtk_clipboard_set_with_data() and gtk_clipboard_set_with_owner()
62  * are quite similar; the choice between the two depends mostly on
63  * which is more convenient in a particular situation.
64  * The former is most useful when you want to have a blob of data
65  * with callbacks to convert it into the various data types that you
66  * advertise. When the @clear_func you provided is called, you
67  * simply free the data blob. The latter is more useful when the
68  * contents of clipboard reflect the internal state of a #GObject
69  * (As an example, for the PRIMARY clipboard, when an entry widget
70  * provides the clipboard’s contents the contents are simply the
71  * text within the selected region.) If the contents change, the
72  * entry widget can call gtk_clipboard_set_with_owner() to update
73  * the timestamp for clipboard ownership, without having to worry
74  * about @clear_func being called.
75  * 
76  * Requesting the data from the clipboard is essentially
77  * asynchronous. If the contents of the clipboard are provided within
78  * the same process, then a direct function call will be made to
79  * retrieve the data, but if they are provided by another process,
80  * then the data needs to be retrieved from the other process, which
81  * may take some time. To avoid blocking the user interface, the call
82  * to request the selection, gtk_clipboard_request_contents() takes a
83  * callback that will be called when the contents are received (or
84  * when the request fails.) If you don’t want to deal with providing
85  * a separate callback, you can also use gtk_clipboard_wait_for_contents().
86  * What this does is run the GLib main loop recursively waiting for
87  * the contents. This can simplify the code flow, but you still have
88  * to be aware that other callbacks in your program can be called
89  * while this recursive mainloop is running.
90  * 
91  * Along with the functions to get the clipboard contents as an
92  * arbitrary data chunk, there are also functions to retrieve
93  * it as text, gtk_clipboard_request_text() and
94  * gtk_clipboard_wait_for_text(). These functions take care of
95  * determining which formats are advertised by the clipboard
96  * provider, asking for the clipboard in the best available format
97  * and converting the results into the UTF-8 encoding. (The standard
98  * form for representing strings in GTK+.)
99  */
100 public class Clipboard : ObjectG
101 {
102 	/** the main Gtk struct */
103 	protected GtkClipboard* gtkClipboard;
104 
105 	/** Get the main Gtk struct */
106 	public GtkClipboard* getClipboardStruct()
107 	{
108 		return gtkClipboard;
109 	}
110 
111 	/** the main Gtk struct as a void* */
112 	protected override void* getStruct()
113 	{
114 		return cast(void*)gtkClipboard;
115 	}
116 
117 	protected override void setStruct(GObject* obj)
118 	{
119 		gtkClipboard = cast(GtkClipboard*)obj;
120 		super.setStruct(obj);
121 	}
122 
123 	/**
124 	 * Sets our main struct and passes it to the parent class.
125 	 */
126 	public this (GtkClipboard* gtkClipboard, bool ownedRef = false)
127 	{
128 		this.gtkClipboard = gtkClipboard;
129 		super(cast(GObject*)gtkClipboard, ownedRef);
130 	}
131 
132 
133 	/** */
134 	public static GType getType()
135 	{
136 		return gtk_clipboard_get_type();
137 	}
138 
139 	/**
140 	 * Returns the clipboard object for the given selection.
141 	 * See gtk_clipboard_get_for_display() for complete details.
142 	 *
143 	 * Params:
144 	 *     selection = a #GdkAtom which identifies the clipboard to use
145 	 *
146 	 * Return: the appropriate clipboard object. If no clipboard
147 	 *     already exists, a new one will be created. Once a clipboard
148 	 *     object has been created, it is persistent and, since it is
149 	 *     owned by GTK+, must not be freed or unreffed.
150 	 */
151 	public static Clipboard get(GdkAtom selection)
152 	{
153 		auto p = gtk_clipboard_get(selection);
154 		
155 		if(p is null)
156 		{
157 			return null;
158 		}
159 		
160 		return ObjectG.getDObject!(Clipboard)(cast(GtkClipboard*) p);
161 	}
162 
163 	/**
164 	 * Returns the default clipboard object for use with cut/copy/paste menu items
165 	 * and keyboard shortcuts.
166 	 *
167 	 * Params:
168 	 *     display = the #GdkDisplay for which the clipboard is to be retrieved.
169 	 *
170 	 * Return: the default clipboard object.
171 	 *
172 	 * Since: 3.16
173 	 */
174 	public static Clipboard getDefault(Display display)
175 	{
176 		auto p = gtk_clipboard_get_default((display is null) ? null : display.getDisplayStruct());
177 		
178 		if(p is null)
179 		{
180 			return null;
181 		}
182 		
183 		return ObjectG.getDObject!(Clipboard)(cast(GtkClipboard*) p);
184 	}
185 
186 	/**
187 	 * Returns the clipboard object for the given selection.
188 	 * Cut/copy/paste menu items and keyboard shortcuts should use
189 	 * the default clipboard, returned by passing %GDK_SELECTION_CLIPBOARD for @selection.
190 	 * (%GDK_NONE is supported as a synonym for GDK_SELECTION_CLIPBOARD
191 	 * for backwards compatibility reasons.)
192 	 * The currently-selected object or text should be provided on the clipboard
193 	 * identified by #GDK_SELECTION_PRIMARY. Cut/copy/paste menu items
194 	 * conceptually copy the contents of the #GDK_SELECTION_PRIMARY clipboard
195 	 * to the default clipboard, i.e. they copy the selection to what the
196 	 * user sees as the clipboard.
197 	 *
198 	 * (Passing #GDK_NONE is the same as using `gdk_atom_intern
199 	 * ("CLIPBOARD", FALSE)`.
200 	 *
201 	 * See the
202 	 * [FreeDesktop Clipboard Specification](http://www.freedesktop.org/Standards/clipboards-spec)
203 	 * for a detailed discussion of the “CLIPBOARD” vs. “PRIMARY”
204 	 * selections under the X window system. On Win32 the
205 	 * #GDK_SELECTION_PRIMARY clipboard is essentially ignored.)
206 	 *
207 	 * It’s possible to have arbitrary named clipboards; if you do invent
208 	 * new clipboards, you should prefix the selection name with an
209 	 * underscore (because the ICCCM requires that nonstandard atoms are
210 	 * underscore-prefixed), and namespace it as well. For example,
211 	 * if your application called “Foo” has a special-purpose
212 	 * clipboard, you might call it “_FOO_SPECIAL_CLIPBOARD”.
213 	 *
214 	 * Params:
215 	 *     display = the #GdkDisplay for which the clipboard is to be retrieved or created.
216 	 *     selection = a #GdkAtom which identifies the clipboard to use.
217 	 *
218 	 * Return: the appropriate clipboard object. If no
219 	 *     clipboard already exists, a new one will be created. Once a clipboard
220 	 *     object has been created, it is persistent and, since it is owned by
221 	 *     GTK+, must not be freed or unrefd.
222 	 *
223 	 * Since: 2.2
224 	 */
225 	public static Clipboard getForDisplay(Display display, GdkAtom selection)
226 	{
227 		auto p = gtk_clipboard_get_for_display((display is null) ? null : display.getDisplayStruct(), selection);
228 		
229 		if(p is null)
230 		{
231 			return null;
232 		}
233 		
234 		return ObjectG.getDObject!(Clipboard)(cast(GtkClipboard*) p);
235 	}
236 
237 	/**
238 	 * Clears the contents of the clipboard. Generally this should only
239 	 * be called between the time you call gtk_clipboard_set_with_owner()
240 	 * or gtk_clipboard_set_with_data(),
241 	 * and when the @clear_func you supplied is called. Otherwise, the
242 	 * clipboard may be owned by someone else.
243 	 */
244 	public void clear()
245 	{
246 		gtk_clipboard_clear(gtkClipboard);
247 	}
248 
249 	/**
250 	 * Gets the #GdkDisplay associated with @clipboard
251 	 *
252 	 * Return: the #GdkDisplay associated with @clipboard
253 	 *
254 	 * Since: 2.2
255 	 */
256 	public Display getDisplay()
257 	{
258 		auto p = gtk_clipboard_get_display(gtkClipboard);
259 		
260 		if(p is null)
261 		{
262 			return null;
263 		}
264 		
265 		return ObjectG.getDObject!(Display)(cast(GdkDisplay*) p);
266 	}
267 
268 	/**
269 	 * If the clipboard contents callbacks were set with
270 	 * gtk_clipboard_set_with_owner(), and the gtk_clipboard_set_with_data() or
271 	 * gtk_clipboard_clear() has not subsequently called, returns the owner set
272 	 * by gtk_clipboard_set_with_owner().
273 	 *
274 	 * Return: the owner of the clipboard, if any;
275 	 *     otherwise %NULL.
276 	 */
277 	public ObjectG getOwner()
278 	{
279 		auto p = gtk_clipboard_get_owner(gtkClipboard);
280 		
281 		if(p is null)
282 		{
283 			return null;
284 		}
285 		
286 		return ObjectG.getDObject!(ObjectG)(cast(GObject*) p);
287 	}
288 
289 	/**
290 	 * Gets the selection that this clipboard is for.
291 	 *
292 	 * Return: the selection
293 	 *
294 	 * Since: 3.22
295 	 */
296 	public GdkAtom getSelection()
297 	{
298 		return gtk_clipboard_get_selection(gtkClipboard);
299 	}
300 
301 	/**
302 	 * Requests the contents of clipboard as the given target.
303 	 * When the results of the result are later received the supplied callback
304 	 * will be called.
305 	 *
306 	 * Params:
307 	 *     target = an atom representing the form into which the clipboard
308 	 *         owner should convert the selection.
309 	 *     callback = A function to call when the results are received
310 	 *         (or the retrieval fails). If the retrieval fails the length field of
311 	 *         @selection_data will be negative.
312 	 *     userData = user data to pass to @callback
313 	 */
314 	public void requestContents(GdkAtom target, GtkClipboardReceivedFunc callback, void* userData)
315 	{
316 		gtk_clipboard_request_contents(gtkClipboard, target, callback, userData);
317 	}
318 
319 	/**
320 	 * Requests the contents of the clipboard as image. When the image is
321 	 * later received, it will be converted to a #GdkPixbuf, and
322 	 * @callback will be called.
323 	 *
324 	 * The @pixbuf parameter to @callback will contain the resulting
325 	 * #GdkPixbuf if the request succeeded, or %NULL if it failed. This
326 	 * could happen for various reasons, in particular if the clipboard
327 	 * was empty or if the contents of the clipboard could not be
328 	 * converted into an image.
329 	 *
330 	 * Params:
331 	 *     callback = a function to call when the image is received,
332 	 *         or the retrieval fails. (It will always be called one way or the other.)
333 	 *     userData = user data to pass to @callback.
334 	 *
335 	 * Since: 2.6
336 	 */
337 	public void requestImage(GtkClipboardImageReceivedFunc callback, void* userData)
338 	{
339 		gtk_clipboard_request_image(gtkClipboard, callback, userData);
340 	}
341 
342 	/**
343 	 * Requests the contents of the clipboard as rich text. When the rich
344 	 * text is later received, @callback will be called.
345 	 *
346 	 * The @text parameter to @callback will contain the resulting rich
347 	 * text if the request succeeded, or %NULL if it failed. The @length
348 	 * parameter will contain @text’s length. This function can fail for
349 	 * various reasons, in particular if the clipboard was empty or if the
350 	 * contents of the clipboard could not be converted into rich text form.
351 	 *
352 	 * Params:
353 	 *     buffer = a #GtkTextBuffer
354 	 *     callback = a function to call when the text is received,
355 	 *         or the retrieval fails. (It will always be called one way or the other.)
356 	 *     userData = user data to pass to @callback.
357 	 *
358 	 * Since: 2.10
359 	 */
360 	public void requestRichText(TextBuffer buffer, GtkClipboardRichTextReceivedFunc callback, void* userData)
361 	{
362 		gtk_clipboard_request_rich_text(gtkClipboard, (buffer is null) ? null : buffer.getTextBufferStruct(), callback, userData);
363 	}
364 
365 	/**
366 	 * Requests the contents of the clipboard as list of supported targets.
367 	 * When the list is later received, @callback will be called.
368 	 *
369 	 * The @targets parameter to @callback will contain the resulting targets if
370 	 * the request succeeded, or %NULL if it failed.
371 	 *
372 	 * Params:
373 	 *     callback = a function to call when the targets are
374 	 *         received, or the retrieval fails. (It will always be called
375 	 *         one way or the other.)
376 	 *     userData = user data to pass to @callback.
377 	 *
378 	 * Since: 2.4
379 	 */
380 	public void requestTargets(GtkClipboardTargetsReceivedFunc callback, void* userData)
381 	{
382 		gtk_clipboard_request_targets(gtkClipboard, callback, userData);
383 	}
384 
385 	/**
386 	 * Requests the contents of the clipboard as text. When the text is
387 	 * later received, it will be converted to UTF-8 if necessary, and
388 	 * @callback will be called.
389 	 *
390 	 * The @text parameter to @callback will contain the resulting text if
391 	 * the request succeeded, or %NULL if it failed. This could happen for
392 	 * various reasons, in particular if the clipboard was empty or if the
393 	 * contents of the clipboard could not be converted into text form.
394 	 *
395 	 * Params:
396 	 *     callback = a function to call when the text is received,
397 	 *         or the retrieval fails. (It will always be called one way or the other.)
398 	 *     userData = user data to pass to @callback.
399 	 */
400 	public void requestText(GtkClipboardTextReceivedFunc callback, void* userData)
401 	{
402 		gtk_clipboard_request_text(gtkClipboard, callback, userData);
403 	}
404 
405 	/**
406 	 * Requests the contents of the clipboard as URIs. When the URIs are
407 	 * later received @callback will be called.
408 	 *
409 	 * The @uris parameter to @callback will contain the resulting array of
410 	 * URIs if the request succeeded, or %NULL if it failed. This could happen
411 	 * for various reasons, in particular if the clipboard was empty or if the
412 	 * contents of the clipboard could not be converted into URI form.
413 	 *
414 	 * Params:
415 	 *     callback = a function to call when the URIs are received,
416 	 *         or the retrieval fails. (It will always be called one way or the other.)
417 	 *     userData = user data to pass to @callback.
418 	 *
419 	 * Since: 2.14
420 	 */
421 	public void requestUris(GtkClipboardURIReceivedFunc callback, void* userData)
422 	{
423 		gtk_clipboard_request_uris(gtkClipboard, callback, userData);
424 	}
425 
426 	/**
427 	 * Hints that the clipboard data should be stored somewhere when the
428 	 * application exits or when gtk_clipboard_store () is called.
429 	 *
430 	 * This value is reset when the clipboard owner changes.
431 	 * Where the clipboard data is stored is platform dependent,
432 	 * see gdk_display_store_clipboard () for more information.
433 	 *
434 	 * Params:
435 	 *     targets = array containing
436 	 *         information about which forms should be stored or %NULL
437 	 *         to indicate that all forms should be stored.
438 	 *     nTargets = number of elements in @targets
439 	 *
440 	 * Since: 2.6
441 	 */
442 	public void setCanStore(TargetEntry[] targets)
443 	{
444 		GtkTargetEntry[] targetsArray = new GtkTargetEntry[targets.length];
445 		for ( int i = 0; i < targets.length; i++ )
446 		{
447 			targetsArray[i] = *(targets[i].getTargetEntryStruct());
448 		}
449 		
450 		gtk_clipboard_set_can_store(gtkClipboard, targetsArray.ptr, cast(int)targets.length);
451 	}
452 
453 	/**
454 	 * Sets the contents of the clipboard to the given #GdkPixbuf.
455 	 * GTK+ will take responsibility for responding for requests
456 	 * for the image, and for converting the image into the
457 	 * requested format.
458 	 *
459 	 * Params:
460 	 *     pixbuf = a #GdkPixbuf
461 	 *
462 	 * Since: 2.6
463 	 */
464 	public void setImage(Pixbuf pixbuf)
465 	{
466 		gtk_clipboard_set_image(gtkClipboard, (pixbuf is null) ? null : pixbuf.getPixbufStruct());
467 	}
468 
469 	/**
470 	 * Sets the contents of the clipboard to the given UTF-8 string. GTK+ will
471 	 * make a copy of the text and take responsibility for responding
472 	 * for requests for the text, and for converting the text into
473 	 * the requested format.
474 	 *
475 	 * Params:
476 	 *     text = a UTF-8 string.
477 	 *     len = length of @text, in bytes, or -1, in which case
478 	 *         the length will be determined with strlen().
479 	 */
480 	public void setText(string text, int len)
481 	{
482 		gtk_clipboard_set_text(gtkClipboard, Str.toStringz(text), len);
483 	}
484 
485 	/**
486 	 * Virtually sets the contents of the specified clipboard by providing
487 	 * a list of supported formats for the clipboard data and a function
488 	 * to call to get the actual data when it is requested.
489 	 *
490 	 * Params:
491 	 *     targets = array containing information
492 	 *         about the available forms for the clipboard data
493 	 *     nTargets = number of elements in @targets
494 	 *     getFunc = function to call to get the actual clipboard data
495 	 *     clearFunc = when the clipboard contents are set again,
496 	 *         this function will be called, and @get_func will not be subsequently
497 	 *         called.
498 	 *     userData = user data to pass to @get_func and @clear_func.
499 	 *
500 	 * Return: %TRUE if setting the clipboard data succeeded.
501 	 *     If setting the clipboard data failed the provided callback
502 	 *     functions will be ignored.
503 	 */
504 	public bool setWithData(TargetEntry[] targets, GtkClipboardGetFunc getFunc, GtkClipboardClearFunc clearFunc, void* userData)
505 	{
506 		GtkTargetEntry[] targetsArray = new GtkTargetEntry[targets.length];
507 		for ( int i = 0; i < targets.length; i++ )
508 		{
509 			targetsArray[i] = *(targets[i].getTargetEntryStruct());
510 		}
511 		
512 		return gtk_clipboard_set_with_data(gtkClipboard, targetsArray.ptr, cast(uint)targets.length, getFunc, clearFunc, userData) != 0;
513 	}
514 
515 	/**
516 	 * Virtually sets the contents of the specified clipboard by providing
517 	 * a list of supported formats for the clipboard data and a function
518 	 * to call to get the actual data when it is requested.
519 	 *
520 	 * The difference between this function and gtk_clipboard_set_with_data()
521 	 * is that instead of an generic @user_data pointer, a #GObject is passed
522 	 * in.
523 	 *
524 	 * Params:
525 	 *     targets = array containing information
526 	 *         about the available forms for the clipboard data
527 	 *     nTargets = number of elements in @targets
528 	 *     getFunc = function to call to get the actual clipboard data
529 	 *     clearFunc = when the clipboard contents are set again,
530 	 *         this function will be called, and @get_func will not be subsequently
531 	 *         called
532 	 *     owner = an object that “owns” the data. This object will be passed
533 	 *         to the callbacks when called
534 	 *
535 	 * Return: %TRUE if setting the clipboard data succeeded.
536 	 *     If setting the clipboard data failed the provided callback
537 	 *     functions will be ignored.
538 	 */
539 	public bool setWithOwner(TargetEntry[] targets, GtkClipboardGetFunc getFunc, GtkClipboardClearFunc clearFunc, ObjectG owner)
540 	{
541 		GtkTargetEntry[] targetsArray = new GtkTargetEntry[targets.length];
542 		for ( int i = 0; i < targets.length; i++ )
543 		{
544 			targetsArray[i] = *(targets[i].getTargetEntryStruct());
545 		}
546 		
547 		return gtk_clipboard_set_with_owner(gtkClipboard, targetsArray.ptr, cast(uint)targets.length, getFunc, clearFunc, (owner is null) ? null : owner.getObjectGStruct()) != 0;
548 	}
549 
550 	/**
551 	 * Stores the current clipboard data somewhere so that it will stay
552 	 * around after the application has quit.
553 	 *
554 	 * Since: 2.6
555 	 */
556 	public void store()
557 	{
558 		gtk_clipboard_store(gtkClipboard);
559 	}
560 
561 	/**
562 	 * Requests the contents of the clipboard using the given target.
563 	 * This function waits for the data to be received using the main
564 	 * loop, so events, timeouts, etc, may be dispatched during the wait.
565 	 *
566 	 * Params:
567 	 *     target = an atom representing the form into which the clipboard
568 	 *         owner should convert the selection.
569 	 *
570 	 * Return: a newly-allocated #GtkSelectionData object or %NULL
571 	 *     if retrieving the given target failed. If non-%NULL,
572 	 *     this value must be freed with gtk_selection_data_free()
573 	 *     when you are finished with it.
574 	 */
575 	public SelectionData waitForContents(GdkAtom target)
576 	{
577 		auto p = gtk_clipboard_wait_for_contents(gtkClipboard, target);
578 		
579 		if(p is null)
580 		{
581 			return null;
582 		}
583 		
584 		return ObjectG.getDObject!(SelectionData)(cast(GtkSelectionData*) p, true);
585 	}
586 
587 	/**
588 	 * Requests the contents of the clipboard as image and converts
589 	 * the result to a #GdkPixbuf. This function waits for
590 	 * the data to be received using the main loop, so events,
591 	 * timeouts, etc, may be dispatched during the wait.
592 	 *
593 	 * Return: a newly-allocated #GdkPixbuf
594 	 *     object which must be disposed with g_object_unref(), or
595 	 *     %NULL if retrieving the selection data failed. (This could
596 	 *     happen for various reasons, in particular if the clipboard
597 	 *     was empty or if the contents of the clipboard could not be
598 	 *     converted into an image.)
599 	 *
600 	 * Since: 2.6
601 	 */
602 	public Pixbuf waitForImage()
603 	{
604 		auto p = gtk_clipboard_wait_for_image(gtkClipboard);
605 		
606 		if(p is null)
607 		{
608 			return null;
609 		}
610 		
611 		return ObjectG.getDObject!(Pixbuf)(cast(GdkPixbuf*) p, true);
612 	}
613 
614 	/**
615 	 * Requests the contents of the clipboard as rich text.  This function
616 	 * waits for the data to be received using the main loop, so events,
617 	 * timeouts, etc, may be dispatched during the wait.
618 	 *
619 	 * Params:
620 	 *     buffer = a #GtkTextBuffer
621 	 *     format = return location for the format of the returned data
622 	 *
623 	 * Return: a
624 	 *     newly-allocated binary block of data which must be
625 	 *     freed with g_free(), or %NULL if retrieving the
626 	 *     selection data failed. (This could happen for various
627 	 *     reasons, in particular if the clipboard was empty or
628 	 *     if the contents of the clipboard could not be
629 	 *     converted into text form.)
630 	 *
631 	 * Since: 2.10
632 	 */
633 	public ubyte[] waitForRichText(TextBuffer buffer, out GdkAtom format)
634 	{
635 		size_t length;
636 		
637 		auto p = gtk_clipboard_wait_for_rich_text(gtkClipboard, (buffer is null) ? null : buffer.getTextBufferStruct(), &format, &length);
638 		
639 		return p[0 .. length];
640 	}
641 
642 	/**
643 	 * Returns a list of targets that are present on the clipboard, or %NULL
644 	 * if there aren’t any targets available. The returned list must be
645 	 * freed with g_free().
646 	 * This function waits for the data to be received using the main
647 	 * loop, so events, timeouts, etc, may be dispatched during the wait.
648 	 *
649 	 * Params:
650 	 *     targets = location
651 	 *         to store an array of targets. The result stored here must
652 	 *         be freed with g_free().
653 	 *     nTargets = location to store number of items in @targets.
654 	 *
655 	 * Return: %TRUE if any targets are present on the clipboard,
656 	 *     otherwise %FALSE.
657 	 *
658 	 * Since: 2.4
659 	 */
660 	public bool waitForTargets(out GdkAtom[] targets)
661 	{
662 		GdkAtom* outtargets = null;
663 		int nTargets;
664 		
665 		auto p = gtk_clipboard_wait_for_targets(gtkClipboard, &outtargets, &nTargets) != 0;
666 		
667 		targets = outtargets[0 .. nTargets];
668 		
669 		return p;
670 	}
671 
672 	/**
673 	 * Requests the contents of the clipboard as text and converts
674 	 * the result to UTF-8 if necessary. This function waits for
675 	 * the data to be received using the main loop, so events,
676 	 * timeouts, etc, may be dispatched during the wait.
677 	 *
678 	 * Return: a newly-allocated UTF-8 string which must
679 	 *     be freed with g_free(), or %NULL if retrieving
680 	 *     the selection data failed. (This could happen
681 	 *     for various reasons, in particular if the
682 	 *     clipboard was empty or if the contents of the
683 	 *     clipboard could not be converted into text form.)
684 	 */
685 	public string waitForText()
686 	{
687 		auto retStr = gtk_clipboard_wait_for_text(gtkClipboard);
688 		
689 		scope(exit) Str.freeString(retStr);
690 		return Str.toString(retStr);
691 	}
692 
693 	/**
694 	 * Requests the contents of the clipboard as URIs. This function waits
695 	 * for the data to be received using the main loop, so events,
696 	 * timeouts, etc, may be dispatched during the wait.
697 	 *
698 	 * Return: a newly-allocated %NULL-terminated array of strings which must
699 	 *     be freed with g_strfreev(), or %NULL if retrieving the
700 	 *     selection data failed. (This could happen for various reasons,
701 	 *     in particular if the clipboard was empty or if the contents of
702 	 *     the clipboard could not be converted into URI form.)
703 	 *
704 	 * Since: 2.14
705 	 */
706 	public string[] waitForUris()
707 	{
708 		auto retStr = gtk_clipboard_wait_for_uris(gtkClipboard);
709 		
710 		scope(exit) Str.freeStringArray(retStr);
711 		return Str.toStringArray(retStr);
712 	}
713 
714 	/**
715 	 * Test to see if there is an image available to be pasted
716 	 * This is done by requesting the TARGETS atom and checking
717 	 * if it contains any of the supported image targets. This function
718 	 * waits for the data to be received using the main loop, so events,
719 	 * timeouts, etc, may be dispatched during the wait.
720 	 *
721 	 * This function is a little faster than calling
722 	 * gtk_clipboard_wait_for_image() since it doesn’t need to retrieve
723 	 * the actual image data.
724 	 *
725 	 * Return: %TRUE is there is an image available, %FALSE otherwise.
726 	 *
727 	 * Since: 2.6
728 	 */
729 	public bool waitIsImageAvailable()
730 	{
731 		return gtk_clipboard_wait_is_image_available(gtkClipboard) != 0;
732 	}
733 
734 	/**
735 	 * Test to see if there is rich text available to be pasted
736 	 * This is done by requesting the TARGETS atom and checking
737 	 * if it contains any of the supported rich text targets. This function
738 	 * waits for the data to be received using the main loop, so events,
739 	 * timeouts, etc, may be dispatched during the wait.
740 	 *
741 	 * This function is a little faster than calling
742 	 * gtk_clipboard_wait_for_rich_text() since it doesn’t need to retrieve
743 	 * the actual text.
744 	 *
745 	 * Params:
746 	 *     buffer = a #GtkTextBuffer
747 	 *
748 	 * Return: %TRUE is there is rich text available, %FALSE otherwise.
749 	 *
750 	 * Since: 2.10
751 	 */
752 	public bool waitIsRichTextAvailable(TextBuffer buffer)
753 	{
754 		return gtk_clipboard_wait_is_rich_text_available(gtkClipboard, (buffer is null) ? null : buffer.getTextBufferStruct()) != 0;
755 	}
756 
757 	/**
758 	 * Checks if a clipboard supports pasting data of a given type. This
759 	 * function can be used to determine if a “Paste” menu item should be
760 	 * insensitive or not.
761 	 *
762 	 * If you want to see if there’s text available on the clipboard, use
763 	 * gtk_clipboard_wait_is_text_available () instead.
764 	 *
765 	 * Params:
766 	 *     target = A #GdkAtom indicating which target to look for.
767 	 *
768 	 * Return: %TRUE if the target is available, %FALSE otherwise.
769 	 *
770 	 * Since: 2.6
771 	 */
772 	public bool waitIsTargetAvailable(GdkAtom target)
773 	{
774 		return gtk_clipboard_wait_is_target_available(gtkClipboard, target) != 0;
775 	}
776 
777 	/**
778 	 * Test to see if there is text available to be pasted
779 	 * This is done by requesting the TARGETS atom and checking
780 	 * if it contains any of the supported text targets. This function
781 	 * waits for the data to be received using the main loop, so events,
782 	 * timeouts, etc, may be dispatched during the wait.
783 	 *
784 	 * This function is a little faster than calling
785 	 * gtk_clipboard_wait_for_text() since it doesn’t need to retrieve
786 	 * the actual text.
787 	 *
788 	 * Return: %TRUE is there is text available, %FALSE otherwise.
789 	 */
790 	public bool waitIsTextAvailable()
791 	{
792 		return gtk_clipboard_wait_is_text_available(gtkClipboard) != 0;
793 	}
794 
795 	/**
796 	 * Test to see if there is a list of URIs available to be pasted
797 	 * This is done by requesting the TARGETS atom and checking
798 	 * if it contains the URI targets. This function
799 	 * waits for the data to be received using the main loop, so events,
800 	 * timeouts, etc, may be dispatched during the wait.
801 	 *
802 	 * This function is a little faster than calling
803 	 * gtk_clipboard_wait_for_uris() since it doesn’t need to retrieve
804 	 * the actual URI data.
805 	 *
806 	 * Return: %TRUE is there is an URI list available, %FALSE otherwise.
807 	 *
808 	 * Since: 2.14
809 	 */
810 	public bool waitIsUrisAvailable()
811 	{
812 		return gtk_clipboard_wait_is_uris_available(gtkClipboard) != 0;
813 	}
814 
815 	int[string] connectedSignals;
816 
817 	void delegate(GdkEventOwnerChange*, Clipboard)[] onOwnerChangeListeners;
818 	/**
819 	 * The ::owner-change signal is emitted when GTK+ receives an
820 	 * event that indicates that the ownership of the selection
821 	 * associated with @clipboard has changed.
822 	 *
823 	 * Params:
824 	 *     event = the @GdkEventOwnerChange event
825 	 *
826 	 * Since: 2.6
827 	 */
828 	void addOnOwnerChange(void delegate(GdkEventOwnerChange*, Clipboard) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
829 	{
830 		if ( "owner-change" !in connectedSignals )
831 		{
832 			Signals.connectData(
833 				this,
834 				"owner-change",
835 				cast(GCallback)&callBackOwnerChange,
836 				cast(void*)this,
837 				null,
838 				connectFlags);
839 			connectedSignals["owner-change"] = 1;
840 		}
841 		onOwnerChangeListeners ~= dlg;
842 	}
843 	extern(C) static void callBackOwnerChange(GtkClipboard* clipboardStruct, GdkEventOwnerChange* event, Clipboard _clipboard)
844 	{
845 		foreach ( void delegate(GdkEventOwnerChange*, Clipboard) dlg; _clipboard.onOwnerChangeListeners )
846 		{
847 			dlg(event, _clipboard);
848 		}
849 	}
850 
851 	void delegate(Event, Clipboard)[] onOwnerChangeGenericListeners;
852 	/**
853 	 * The ::owner-change signal is emitted when GTK+ receives an
854 	 * event that indicates that the ownership of the selection
855 	 * associated with @clipboard has changed.
856 	 *
857 	 * Params:
858 	 *     event = the @GdkEventOwnerChange event
859 	 *
860 	 * Since: 2.6
861 	 */
862 	void addOnOwnerChange(void delegate(Event, Clipboard) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
863 	{
864 		if ( "owner-change-generic-event" !in connectedSignals )
865 		{
866 			Signals.connectData(
867 				this,
868 				"owner-change",
869 				cast(GCallback)&callBackOwnerChangeGeneric,
870 				cast(void*)this,
871 				null,
872 				connectFlags);
873 			connectedSignals["owner-change-generic-event"] = 1;
874 		}
875 		onOwnerChangeGenericListeners ~= dlg;
876 	}
877 	extern(C) static void callBackOwnerChangeGeneric(GtkClipboard* clipboardStruct, GdkEvent* event, Clipboard _clipboard)
878 	{
879 		foreach ( void delegate(Event, Clipboard) dlg; _clipboard.onOwnerChangeGenericListeners )
880 		{
881 			dlg(ObjectG.getDObject!(Event)(event), _clipboard);
882 		}
883 	}
884 }