1 /* GTK - The GIMP Toolkit
2 * Copyright (C) 2000 Red Hat, Inc.
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2 of the License, or (at your option) any later version.
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with this library; if not, write to the
16 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
17 * Boston, MA 02111-1307, USA.
19 * Global clipboard abstraction.
24 #include "gtkclipboard.h"
25 #include "gtkinvisible.h"
27 #include "gtksignal.h"
29 #ifdef GDK_WINDOWING_X11
33 #ifdef GDK_WINDOWING_WIN32
34 #include "win32/gdkwin32.h"
37 typedef struct _RequestContentsInfo RequestContentsInfo;
38 typedef struct _RequestTextInfo RequestTextInfo;
44 GtkClipboardGetFunc get_func;
45 GtkClipboardClearFunc clear_func;
51 gboolean have_selection;
54 struct _RequestContentsInfo
56 GtkClipboardReceivedFunc callback;
60 struct _RequestTextInfo
62 GtkClipboardTextReceivedFunc callback;
66 static void clipboard_unset (GtkClipboard *clipboard);
67 static void selection_received (GtkWidget *widget,
68 GtkSelectionData *selection_data,
71 static GSList *clipboards;
72 static GtkWidget *clipboard_widget;
81 static const gchar *request_contents_key = "gtk-request-contents";
82 static GQuark request_contents_key_id = 0;
84 static const gchar *clipboards_owned_key = "gtk-clipboards-owned";
85 static GQuark clipboards_owned_key_id = 0;
90 * @selection: a #GdkAtom which identifies the clipboard
91 * to use. A value of %GDK_NONE here is the
92 * same as <literal>gdk_atom_intern ("CLIPBOARD", FALSE)</literal>,
93 * and provides the default clipboard. Another
94 * common value is %GDK_SELECTION_PRIMARY, which
95 * identifies the primary X selection.
97 * Returns the clipboard object for the given selection.
99 * Return value: the appropriate clipboard object. If no
100 * clipboard already exists, a new one will
101 * be created. Once a clipboard object has
102 * been created, it is persistent for all time.
105 gtk_clipboard_get (GdkAtom selection)
107 GtkClipboard *clipboard = NULL;
110 if (selection == GDK_NONE)
111 selection = gdk_atom_intern ("CLIPBOARD", FALSE);
113 tmp_list = clipboards;
116 clipboard = tmp_list->data;
117 if (clipboard->selection == selection)
120 tmp_list = tmp_list->next;
125 clipboard = g_new0 (GtkClipboard, 1);
126 clipboard->selection = selection;
127 clipboards = g_slist_prepend (clipboards, clipboard);
134 selection_get_cb (GtkWidget *widget,
135 GtkSelectionData *selection_data,
139 GtkClipboard *clipboard = gtk_clipboard_get (selection_data->selection);
141 if (clipboard && clipboard->get_func)
142 clipboard->get_func (clipboard, selection_data, info, clipboard->user_data);
146 selection_clear_event_cb (GtkWidget *widget,
147 GdkEventSelection *event)
149 GtkClipboard *clipboard = gtk_clipboard_get (event->selection);
153 clipboard_unset (clipboard);
161 make_clipboard_widget (gboolean provider)
163 GtkWidget *widget = gtk_invisible_new ();
165 gtk_signal_connect (GTK_OBJECT (widget), "selection_received",
166 GTK_SIGNAL_FUNC (selection_received), NULL);
170 /* We need this for gdk_x11_get_server_time() */
171 gtk_widget_add_events (widget, GDK_PROPERTY_CHANGE_MASK);
173 gtk_signal_connect (GTK_OBJECT (widget), "selection_get",
174 GTK_SIGNAL_FUNC (selection_get_cb), NULL);
175 gtk_signal_connect (GTK_OBJECT (widget), "selection_clear_event",
176 GTK_SIGNAL_FUNC (selection_clear_event_cb), NULL);
184 ensure_clipboard_widget ()
186 if (!clipboard_widget)
187 clipboard_widget = make_clipboard_widget (TRUE);
190 /* This function makes a very good guess at what the correct
191 * timestamp for a selection request should be. If there is
192 * a currently processed event, it uses the timestamp for that
193 * event, otherwise it uses the current server time. However,
194 * if the time resulting from that is older than the time used
195 * last time, it uses the time used last time instead.
197 * In order implement this correctly, we never use CurrentTime,
198 * but actually retrieve the actual timestamp from the server.
199 * This is a little slower but allows us to make the guarantee
200 * that the times used by this application will always ascend
201 * and we won't get selections being rejected just because
202 * we are using a correct timestamp from an event, but used
203 * CurrentTime previously.
206 clipboard_get_timestamp (GtkClipboard *clipboard)
208 guint32 timestamp = gtk_get_current_event_time ();
210 ensure_clipboard_widget ();
212 if (timestamp == GDK_CURRENT_TIME)
214 #ifdef GDK_WINDOWING_X11
215 timestamp = gdk_x11_get_server_time (clipboard_widget->window);
216 #elif defined GDK_WINDOWING_WIN32
217 timestamp = GetMessageTime ();
222 if (clipboard->timestamp != GDK_CURRENT_TIME)
224 /* Check to see if clipboard->timestamp is newer than
225 * timestamp, accounting for wraparound.
228 guint32 max = timestamp + 0x80000000;
230 if ((max > timestamp &&
231 (clipboard->timestamp > timestamp &&
232 clipboard->timestamp <= max)) ||
234 (clipboard->timestamp > timestamp ||
235 clipboard->timestamp <= max)))
237 timestamp = clipboard->timestamp;
242 clipboard->timestamp = timestamp;
248 clipboard_owner_destroyed (gpointer data)
250 GSList *clipboards = data;
253 tmp_list = clipboards;
256 GtkClipboard *clipboard = tmp_list->data;
258 clipboard->get_func = NULL;
259 clipboard->clear_func = NULL;
260 clipboard->user_data = NULL;
261 clipboard->have_owner = FALSE;
263 gtk_clipboard_clear (clipboard);
265 tmp_list = tmp_list->next;
268 g_slist_free (clipboards);
272 clipboard_add_owner_notify (GtkClipboard *clipboard)
274 if (!clipboards_owned_key_id)
275 clipboards_owned_key_id = g_quark_from_static_string (clipboards_owned_key);
277 if (clipboard->have_owner)
278 g_object_set_qdata_full (clipboard->user_data, clipboards_owned_key_id,
279 g_slist_prepend (g_object_steal_qdata (clipboard->user_data,
280 clipboards_owned_key_id),
282 clipboard_owner_destroyed);
286 clipboard_remove_owner_notify (GtkClipboard *clipboard)
288 if (clipboard->have_owner)
289 g_object_set_qdata_full (clipboard->user_data, clipboards_owned_key_id,
290 g_slist_remove (g_object_steal_qdata (clipboard->user_data,
291 clipboards_owned_key_id),
293 clipboard_owner_destroyed);
297 gtk_clipboard_set_contents (GtkClipboard *clipboard,
298 const GtkTargetEntry *targets,
300 GtkClipboardGetFunc get_func,
301 GtkClipboardClearFunc clear_func,
305 ensure_clipboard_widget ();
307 if (gtk_selection_owner_set (clipboard_widget, clipboard->selection,
308 clipboard_get_timestamp (clipboard)))
310 clipboard->have_selection = TRUE;
312 if (!(clipboard->have_owner && have_owner) ||
313 clipboard->user_data != user_data)
315 clipboard_unset (clipboard);
317 if (clipboard->get_func)
319 /* Calling unset() caused the clipboard contents to be reset!
320 * Avoid leaking and return
322 if (!(clipboard->have_owner && have_owner) ||
323 clipboard->user_data != user_data)
325 (*clear_func) (clipboard, user_data);
333 clipboard->user_data = user_data;
334 clipboard->have_owner = have_owner;
336 clipboard_add_owner_notify (clipboard);
341 clipboard->get_func = get_func;
342 clipboard->clear_func = clear_func;
344 gtk_selection_clear_targets (clipboard_widget, clipboard->selection);
345 gtk_selection_add_targets (clipboard_widget, clipboard->selection,
355 * gtk_clipboard_set_with_data:
356 * @clipboard: a #GtkClipboard
357 * @targets: array containing information about the available forms for the
359 * @n_targets: number of elements in @targets
360 * @get_func: function to call to get the actual clipboard data
361 * @clear_func: when the clipboard contents are set again, this function will
362 * be called, and @get_func will not be subsequently called.
363 * @user_data: user data to pass to @get_func and @clear_func.
365 * Virtually sets the contents of the specified clipboard by providing
366 * a list of supported formats for the clipboard data and a function
367 * to call to get the actual data when it is requested.
369 * Return value: %TRUE if setting the clipboard data succeeded. If setting
370 * the clipboard data failed the provided callback functions
374 gtk_clipboard_set_with_data (GtkClipboard *clipboard,
375 const GtkTargetEntry *targets,
377 GtkClipboardGetFunc get_func,
378 GtkClipboardClearFunc clear_func,
381 g_return_val_if_fail (clipboard != NULL, FALSE);
382 g_return_val_if_fail (targets != NULL, FALSE);
383 g_return_val_if_fail (get_func != NULL, FALSE);
385 return gtk_clipboard_set_contents (clipboard, targets, n_targets,
386 get_func, clear_func, user_data,
391 * gtk_clipboard_set_with_owner:
392 * @clipboard: a #GtkClipboard
393 * @targets: array containing information about the available forms for the
395 * @n_targets: number of elements in @targets
396 * @get_func: function to call to get the actual clipboard data
397 * @clear_func: when the clipboard contents are set again, this function will
398 * be called, and @get_func will not be subsequently called.
399 * @owner: an object that "owns" the data. This object will be passed
400 * to the callbacks when called.
402 * Virtually sets the contents of the specified clipboard by providing
403 * a list of supported formats for the clipboard data and a function
404 * to call to get the actual data when it is requested.
406 * The difference between this function and gtk_clipboard_set_with_data()
407 * is that instead of an generic @user_data pointer, a #GObject is passed
410 * Return value: %TRUE if setting the clipboard data succeeded. If setting
411 * the clipboard data failed the provided callback functions
415 gtk_clipboard_set_with_owner (GtkClipboard *clipboard,
416 const GtkTargetEntry *targets,
418 GtkClipboardGetFunc get_func,
419 GtkClipboardClearFunc clear_func,
422 g_return_val_if_fail (clipboard != NULL, FALSE);
423 g_return_val_if_fail (targets != NULL, FALSE);
424 g_return_val_if_fail (get_func != NULL, FALSE);
425 g_return_val_if_fail (G_IS_OBJECT (owner), FALSE);
427 return gtk_clipboard_set_contents (clipboard, targets, n_targets,
428 get_func, clear_func, owner,
433 * gtk_clipboard_get_owner:
434 * @clipboard: a #GtkClipboard
436 * If the clipboard contents callbacks were set with
437 * gtk_clipboard_set_with_owner(), and the gtk_clipboard_set_with_data() or
438 * gtk_clipboard_clear() has not subsequently called, returns the @owner set
439 * by gtk_clipboard_set_with_owner().
441 * Return value: the owner of the clipboard, if any; otherwise %NULL.
444 gtk_clipboard_get_owner (GtkClipboard *clipboard)
446 g_return_val_if_fail (clipboard != NULL, NULL);
448 if (clipboard->have_owner)
449 return clipboard->user_data;
455 clipboard_unset (GtkClipboard *clipboard)
457 GtkClipboardClearFunc old_clear_func;
460 old_clear_func = clipboard->clear_func;
461 old_data = clipboard->user_data;
463 if (clipboard->have_owner)
465 clipboard_remove_owner_notify (clipboard);
466 clipboard->have_owner = FALSE;
469 clipboard->get_func = NULL;
470 clipboard->clear_func = NULL;
471 clipboard->user_data = NULL;
474 old_clear_func (clipboard, old_data);
478 * gtk_clipboard_clear:
479 * @clipboard: a #GtkClipboard
481 * Clears the contents of the clipboard. Generally this should only
482 * be called between the time you call gtk_clipboard_set_contents(),
483 * and when the @clear_func you supplied is called. Otherwise, the
484 * clipboard may be owned by someone else.
487 gtk_clipboard_clear (GtkClipboard *clipboard)
489 g_return_if_fail (clipboard != NULL);
491 if (clipboard->have_selection)
492 gtk_selection_owner_set (NULL, clipboard->selection,
493 clipboard_get_timestamp (clipboard));
497 text_get_func (GtkClipboard *clipboard,
498 GtkSelectionData *selection_data,
502 gtk_selection_data_set_text (selection_data, data, -1);
506 text_clear_func (GtkClipboard *clipboard,
513 * gtk_clipboard_set_text:
514 * @clipboard: a #GtkClipboard object
515 * @text: a UTF-8 string.
516 * @len: length of @text, in bytes, or -1, in which case
517 * the length will be determined with <function>strlen()</function>.
519 * Sets the contents of the clipboard to the given UTF-8 string. GTK+ will
520 * make a copy of the text and take responsibility for responding
521 * for requests for the text, and for converting the text into
522 * the requested format.
525 gtk_clipboard_set_text (GtkClipboard *clipboard,
529 static const GtkTargetEntry targets[] = {
530 { "STRING", 0, TARGET_STRING },
531 { "TEXT", 0, TARGET_TEXT },
532 { "COMPOUND_TEXT", 0, TARGET_COMPOUND_TEXT },
533 { "UTF8_STRING", 0, TARGET_UTF8_STRING }
536 g_return_if_fail (clipboard != NULL);
537 g_return_if_fail (text != NULL);
542 gtk_clipboard_set_with_data (clipboard,
543 targets, G_N_ELEMENTS (targets),
544 text_get_func, text_clear_func,
545 g_strndup (text, len));
549 set_request_contents_info (GtkWidget *widget,
550 RequestContentsInfo *info)
552 if (!request_contents_key_id)
553 request_contents_key_id = g_quark_from_static_string (request_contents_key);
555 gtk_object_set_data_by_id (GTK_OBJECT (widget),
556 request_contents_key_id,
560 static RequestContentsInfo *
561 get_request_contents_info (GtkWidget *widget)
563 if (!request_contents_key_id)
566 return gtk_object_get_data_by_id (GTK_OBJECT (widget),
567 request_contents_key_id);
571 selection_received (GtkWidget *widget,
572 GtkSelectionData *selection_data,
575 RequestContentsInfo *request_info = get_request_contents_info (widget);
576 set_request_contents_info (widget, NULL);
578 request_info->callback (gtk_clipboard_get (selection_data->selection),
580 request_info->user_data);
582 g_free (request_info);
584 if (widget != clipboard_widget)
585 gtk_widget_destroy (widget);
589 * gtk_clipboard_request_contents:
590 * @clipboard: a #GtkClipboard
591 * @target: an atom representing the form into which the clipboard
592 * owner should convert the selection.
593 * @callback: A function to call when the results are received
594 * (or the retrieval fails). If the retrieval fails
595 * the length field of @selection_data will be
597 * @user_data: user data to pass to @callback
599 * Requests the contents of clipboard as the given target.
600 * When the results of the result are later received the supplied callback
604 gtk_clipboard_request_contents (GtkClipboard *clipboard,
606 GtkClipboardReceivedFunc callback,
609 RequestContentsInfo *info;
612 g_return_if_fail (clipboard != NULL);
613 g_return_if_fail (target != GDK_NONE);
614 g_return_if_fail (callback != NULL);
616 ensure_clipboard_widget ();
618 if (get_request_contents_info (clipboard_widget))
619 widget = make_clipboard_widget (FALSE);
621 widget = clipboard_widget;
623 info = g_new (RequestContentsInfo, 1);
624 info->callback = callback;
625 info->user_data = user_data;
627 set_request_contents_info (widget, info);
629 gtk_selection_convert (widget, clipboard->selection, target,
630 clipboard_get_timestamp (clipboard));
634 request_text_received_func (GtkClipboard *clipboard,
635 GtkSelectionData *selection_data,
638 RequestTextInfo *info = data;
639 gchar *result = NULL;
641 result = gtk_selection_data_get_text (selection_data);
645 /* If we asked for UTF8 and didn't get it, try compound_text;
646 * if we asked for compound_text and didn't get it, try string;
647 * If we asked for anything else and didn't get it, give up.
649 if (selection_data->target == gdk_atom_intern ("UTF8_STRING", FALSE))
651 gtk_clipboard_request_contents (clipboard,
652 gdk_atom_intern ("COMPOUND_TEXT", FALSE),
653 request_text_received_func, info);
656 else if (selection_data->target == gdk_atom_intern ("COMPOUND_TEXT", FALSE))
658 gtk_clipboard_request_contents (clipboard,
660 request_text_received_func, info);
665 info->callback (clipboard, result, info->user_data);
671 * gtk_clipboard_request_text:
672 * @clipboard: a #GtkClipboard
673 * @callback: a function to call when the text is received,
674 * or the retrieval fails. (It will always be called
675 * one way or the other.)
676 * @user_data: user data to pass to @callback.
678 * Requests the contents of the clipboard as text. When the text is
679 * later received, it will be converted to UTF-8 if necessary, and
680 * @callback will be called.
682 * The @text parameter to @callback will contain the resulting text if
683 * the request succeeded, or %NULL if it failed. This could happen for
684 * various reasons, in particular if the clipboard was empty or if the
685 * contents of the clipboard could not be converted into text form.
688 gtk_clipboard_request_text (GtkClipboard *clipboard,
689 GtkClipboardTextReceivedFunc callback,
692 RequestTextInfo *info;
694 g_return_if_fail (clipboard != NULL);
695 g_return_if_fail (callback != NULL);
697 info = g_new (RequestTextInfo, 1);
698 info->callback = callback;
699 info->user_data = user_data;
701 gtk_clipboard_request_contents (clipboard, gdk_atom_intern ("UTF8_STRING", FALSE),
702 request_text_received_func,
714 clipboard_received_func (GtkClipboard *clipboard,
715 GtkSelectionData *selection_data,
718 WaitResults *results = data;
720 if (selection_data->length >= 0)
721 results->data = gtk_selection_data_copy (selection_data);
723 g_main_quit (results->loop);
727 * gtk_clipboard_wait_for_contents:
728 * @clipboard: a #GtkClipboard
729 * @target: an atom representing the form into which the clipboard
730 * owner should convert the selection.
732 * Requests the contents of the clipboard using the given target.
733 * This function waits for the data to be received using the main
734 * loop, so events, timeouts, etc, may be dispatched during the wait.
736 * Return value: a newly-allocated #GtkSelectionData object or %NULL
737 * if retrieving the given target failed. If non-%NULL,
738 * this value must be freed with gtk_selection_data_free()
739 * when you are finished with it.
742 gtk_clipboard_wait_for_contents (GtkClipboard *clipboard,
747 g_return_val_if_fail (clipboard != NULL, NULL);
748 g_return_val_if_fail (target != GDK_NONE, NULL);
751 results.loop = g_main_new (TRUE);
753 gtk_clipboard_request_contents (clipboard, target,
754 clipboard_received_func,
757 if (g_main_is_running (results.loop))
759 GDK_THREADS_LEAVE ();
760 g_main_run (results.loop);
761 GDK_THREADS_ENTER ();
764 g_main_destroy (results.loop);
770 clipboard_text_received_func (GtkClipboard *clipboard,
774 WaitResults *results = data;
776 results->data = g_strdup (text);
777 g_main_quit (results->loop);
782 * gtk_clipboard_wait_for_text:
783 * @clipboard: a #GtkClipboard
785 * Requests the contents of the clipboard as text and converts
786 * the result to UTF-8 if necessary. This function waits for
787 * the data to be received using the main loop, so events,
788 * timeouts, etc, may be dispatched during the wait.
790 * Return value: a newly-allocated UTF-8 string which must
791 * be freed with g_free(), or %NULL if retrieving
792 * the selection data failed. (This could happen
793 * for various reasons, in particular if the
794 * clipboard was empty or if the contents of the
795 * clipboard could not be converted into text form.)
798 gtk_clipboard_wait_for_text (GtkClipboard *clipboard)
802 g_return_val_if_fail (clipboard != NULL, NULL);
803 g_return_val_if_fail (clipboard != NULL, NULL);
806 results.loop = g_main_new (TRUE);
808 gtk_clipboard_request_text (clipboard,
809 clipboard_text_received_func,
812 if (g_main_is_running (results.loop))
814 GDK_THREADS_LEAVE ();
815 g_main_run (results.loop);
816 GDK_THREADS_ENTER ();
819 g_main_destroy (results.loop);
825 * gtk_clipboard_wait_is_text_available:
826 * @clipboard: a #GtkClipboard
828 * Test to see if there is text available to be pasted
829 * This is done by requesting the TARGETS atom and checking
830 * if it contains any of the names: STRING, TEXT, COMPOUND_TEXT,
831 * UTF8_STRING. This function waits for the data to be received
832 * using the main loop, so events, timeouts, etc, may be dispatched
835 * This function is a little faster than calling
836 * gtk_clipboard_wait_for_text() since it doesn't need to retrieve
839 * Return value: %TRUE is there is text available, %FALSE otherwise.
842 gtk_clipboard_wait_is_text_available (GtkClipboard *clipboard)
844 GtkSelectionData *data;
845 gboolean result = FALSE;
847 data = gtk_clipboard_wait_for_contents (clipboard, gdk_atom_intern ("TARGETS", FALSE));
850 result = gtk_selection_data_targets_include_text (data);
851 gtk_selection_data_free (data);