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
93 * Returns the clipboard object for the given selection.
94 * Cut/copy/paste menu items and keyboard shortcuts should use
95 * the default clipboard, returned by passing #GDK_NONE for @selection.
96 * The currently-selected object or text should be provided on the clipboard
97 * identified by #GDK_SELECTION_PRIMARY. Cut/copy/paste menu items
98 * conceptually copy the contents of the #GDK_SELECTION_PRIMARY clipboard
99 * to the default clipboard, i.e. they copy the selection to what the
100 * user sees as the clipboard.
102 * (Passing #GDK_NONE is the same as using <literal>gdk_atom_intern
103 * ("CLIPBOARD", FALSE)</literal>. See
104 * <ulink url="http://www.freedesktop.org/standards/clipboards.txt">
105 * http://www.freedesktop.org/standards/clipboards.txt</ulink>
106 * for a detailed discussion of the "CLIPBOARD" vs. "PRIMARY" selections
107 * under the X window system. On Win32 the #GDK_SELECTION_PRIMARY
108 * clipboard is essentially ignored.)
110 * It's possible to have arbitrary named clipboards; if you do invent
111 * new clipboards, you should prefix the selection name with an
112 * underscore (because the ICCCM requires that nonstandard atoms are
113 * underscore-prefixed), and namespace it as well. For example,
114 * if your application called "Foo" has a special-purpose
115 * clipboard, you might call it "_FOO_SPECIAL_CLIPBOARD".
117 * Return value: the appropriate clipboard object. If no
118 * clipboard already exists, a new one will
119 * be created. Once a clipboard object has
120 * been created, it is persistent for all time and
124 gtk_clipboard_get (GdkAtom selection)
126 GtkClipboard *clipboard = NULL;
129 if (selection == GDK_NONE)
130 selection = gdk_atom_intern ("CLIPBOARD", FALSE);
132 tmp_list = clipboards;
135 clipboard = tmp_list->data;
136 if (clipboard->selection == selection)
139 tmp_list = tmp_list->next;
144 clipboard = g_new0 (GtkClipboard, 1);
145 clipboard->selection = selection;
146 clipboards = g_slist_prepend (clipboards, clipboard);
153 selection_get_cb (GtkWidget *widget,
154 GtkSelectionData *selection_data,
158 GtkClipboard *clipboard = gtk_clipboard_get (selection_data->selection);
160 if (clipboard && clipboard->get_func)
161 clipboard->get_func (clipboard, selection_data, info, clipboard->user_data);
165 selection_clear_event_cb (GtkWidget *widget,
166 GdkEventSelection *event)
168 GtkClipboard *clipboard = gtk_clipboard_get (event->selection);
172 clipboard_unset (clipboard);
180 make_clipboard_widget (gboolean provider)
182 GtkWidget *widget = gtk_invisible_new ();
184 gtk_signal_connect (GTK_OBJECT (widget), "selection_received",
185 GTK_SIGNAL_FUNC (selection_received), NULL);
189 /* We need this for gdk_x11_get_server_time() */
190 gtk_widget_add_events (widget, GDK_PROPERTY_CHANGE_MASK);
192 gtk_signal_connect (GTK_OBJECT (widget), "selection_get",
193 GTK_SIGNAL_FUNC (selection_get_cb), NULL);
194 gtk_signal_connect (GTK_OBJECT (widget), "selection_clear_event",
195 GTK_SIGNAL_FUNC (selection_clear_event_cb), NULL);
203 ensure_clipboard_widget ()
205 if (!clipboard_widget)
206 clipboard_widget = make_clipboard_widget (TRUE);
209 /* This function makes a very good guess at what the correct
210 * timestamp for a selection request should be. If there is
211 * a currently processed event, it uses the timestamp for that
212 * event, otherwise it uses the current server time. However,
213 * if the time resulting from that is older than the time used
214 * last time, it uses the time used last time instead.
216 * In order implement this correctly, we never use CurrentTime,
217 * but actually retrieve the actual timestamp from the server.
218 * This is a little slower but allows us to make the guarantee
219 * that the times used by this application will always ascend
220 * and we won't get selections being rejected just because
221 * we are using a correct timestamp from an event, but used
222 * CurrentTime previously.
225 clipboard_get_timestamp (GtkClipboard *clipboard)
227 guint32 timestamp = gtk_get_current_event_time ();
229 ensure_clipboard_widget ();
231 if (timestamp == GDK_CURRENT_TIME)
233 #ifdef GDK_WINDOWING_X11
234 timestamp = gdk_x11_get_server_time (clipboard_widget->window);
235 #elif defined GDK_WINDOWING_WIN32
236 timestamp = GetMessageTime ();
241 if (clipboard->timestamp != GDK_CURRENT_TIME)
243 /* Check to see if clipboard->timestamp is newer than
244 * timestamp, accounting for wraparound.
247 guint32 max = timestamp + 0x80000000;
249 if ((max > timestamp &&
250 (clipboard->timestamp > timestamp &&
251 clipboard->timestamp <= max)) ||
253 (clipboard->timestamp > timestamp ||
254 clipboard->timestamp <= max)))
256 timestamp = clipboard->timestamp;
261 clipboard->timestamp = timestamp;
267 clipboard_owner_destroyed (gpointer data)
269 GSList *clipboards = data;
272 tmp_list = clipboards;
275 GtkClipboard *clipboard = tmp_list->data;
277 clipboard->get_func = NULL;
278 clipboard->clear_func = NULL;
279 clipboard->user_data = NULL;
280 clipboard->have_owner = FALSE;
282 gtk_clipboard_clear (clipboard);
284 tmp_list = tmp_list->next;
287 g_slist_free (clipboards);
291 clipboard_add_owner_notify (GtkClipboard *clipboard)
293 if (!clipboards_owned_key_id)
294 clipboards_owned_key_id = g_quark_from_static_string (clipboards_owned_key);
296 if (clipboard->have_owner)
297 g_object_set_qdata_full (clipboard->user_data, clipboards_owned_key_id,
298 g_slist_prepend (g_object_steal_qdata (clipboard->user_data,
299 clipboards_owned_key_id),
301 clipboard_owner_destroyed);
305 clipboard_remove_owner_notify (GtkClipboard *clipboard)
307 if (clipboard->have_owner)
308 g_object_set_qdata_full (clipboard->user_data, clipboards_owned_key_id,
309 g_slist_remove (g_object_steal_qdata (clipboard->user_data,
310 clipboards_owned_key_id),
312 clipboard_owner_destroyed);
316 gtk_clipboard_set_contents (GtkClipboard *clipboard,
317 const GtkTargetEntry *targets,
319 GtkClipboardGetFunc get_func,
320 GtkClipboardClearFunc clear_func,
324 ensure_clipboard_widget ();
326 if (gtk_selection_owner_set (clipboard_widget, clipboard->selection,
327 clipboard_get_timestamp (clipboard)))
329 clipboard->have_selection = TRUE;
331 if (!(clipboard->have_owner && have_owner) ||
332 clipboard->user_data != user_data)
334 clipboard_unset (clipboard);
336 if (clipboard->get_func)
338 /* Calling unset() caused the clipboard contents to be reset!
339 * Avoid leaking and return
341 if (!(clipboard->have_owner && have_owner) ||
342 clipboard->user_data != user_data)
344 (*clear_func) (clipboard, user_data);
352 clipboard->user_data = user_data;
353 clipboard->have_owner = have_owner;
355 clipboard_add_owner_notify (clipboard);
360 clipboard->get_func = get_func;
361 clipboard->clear_func = clear_func;
363 gtk_selection_clear_targets (clipboard_widget, clipboard->selection);
364 gtk_selection_add_targets (clipboard_widget, clipboard->selection,
374 * gtk_clipboard_set_with_data:
375 * @clipboard: a #GtkClipboard
376 * @targets: array containing information about the available forms for the
378 * @n_targets: number of elements in @targets
379 * @get_func: function to call to get the actual clipboard data
380 * @clear_func: when the clipboard contents are set again, this function will
381 * be called, and @get_func will not be subsequently called.
382 * @user_data: user data to pass to @get_func and @clear_func.
384 * Virtually sets the contents of the specified clipboard by providing
385 * a list of supported formats for the clipboard data and a function
386 * to call to get the actual data when it is requested.
388 * Return value: %TRUE if setting the clipboard data succeeded. If setting
389 * the clipboard data failed the provided callback functions
393 gtk_clipboard_set_with_data (GtkClipboard *clipboard,
394 const GtkTargetEntry *targets,
396 GtkClipboardGetFunc get_func,
397 GtkClipboardClearFunc clear_func,
400 g_return_val_if_fail (clipboard != NULL, FALSE);
401 g_return_val_if_fail (targets != NULL, FALSE);
402 g_return_val_if_fail (get_func != NULL, FALSE);
404 return gtk_clipboard_set_contents (clipboard, targets, n_targets,
405 get_func, clear_func, user_data,
410 * gtk_clipboard_set_with_owner:
411 * @clipboard: a #GtkClipboard
412 * @targets: array containing information about the available forms for the
414 * @n_targets: number of elements in @targets
415 * @get_func: function to call to get the actual clipboard data
416 * @clear_func: when the clipboard contents are set again, this function will
417 * be called, and @get_func will not be subsequently called.
418 * @owner: an object that "owns" the data. This object will be passed
419 * to the callbacks when called.
421 * Virtually sets the contents of the specified clipboard by providing
422 * a list of supported formats for the clipboard data and a function
423 * to call to get the actual data when it is requested.
425 * The difference between this function and gtk_clipboard_set_with_data()
426 * is that instead of an generic @user_data pointer, a #GObject is passed
429 * Return value: %TRUE if setting the clipboard data succeeded. If setting
430 * the clipboard data failed the provided callback functions
434 gtk_clipboard_set_with_owner (GtkClipboard *clipboard,
435 const GtkTargetEntry *targets,
437 GtkClipboardGetFunc get_func,
438 GtkClipboardClearFunc clear_func,
441 g_return_val_if_fail (clipboard != NULL, FALSE);
442 g_return_val_if_fail (targets != NULL, FALSE);
443 g_return_val_if_fail (get_func != NULL, FALSE);
444 g_return_val_if_fail (G_IS_OBJECT (owner), FALSE);
446 return gtk_clipboard_set_contents (clipboard, targets, n_targets,
447 get_func, clear_func, owner,
452 * gtk_clipboard_get_owner:
453 * @clipboard: a #GtkClipboard
455 * If the clipboard contents callbacks were set with
456 * gtk_clipboard_set_with_owner(), and the gtk_clipboard_set_with_data() or
457 * gtk_clipboard_clear() has not subsequently called, returns the owner set
458 * by gtk_clipboard_set_with_owner().
460 * Return value: the owner of the clipboard, if any; otherwise %NULL.
463 gtk_clipboard_get_owner (GtkClipboard *clipboard)
465 g_return_val_if_fail (clipboard != NULL, NULL);
467 if (clipboard->have_owner)
468 return clipboard->user_data;
474 clipboard_unset (GtkClipboard *clipboard)
476 GtkClipboardClearFunc old_clear_func;
479 old_clear_func = clipboard->clear_func;
480 old_data = clipboard->user_data;
482 if (clipboard->have_owner)
484 clipboard_remove_owner_notify (clipboard);
485 clipboard->have_owner = FALSE;
488 clipboard->get_func = NULL;
489 clipboard->clear_func = NULL;
490 clipboard->user_data = NULL;
493 old_clear_func (clipboard, old_data);
497 * gtk_clipboard_clear:
498 * @clipboard: a #GtkClipboard
500 * Clears the contents of the clipboard. Generally this should only
501 * be called between the time you call gtk_clipboard_set_contents(),
502 * and when the @clear_func you supplied is called. Otherwise, the
503 * clipboard may be owned by someone else.
506 gtk_clipboard_clear (GtkClipboard *clipboard)
508 g_return_if_fail (clipboard != NULL);
510 if (clipboard->have_selection)
511 gtk_selection_owner_set (NULL, clipboard->selection,
512 clipboard_get_timestamp (clipboard));
516 text_get_func (GtkClipboard *clipboard,
517 GtkSelectionData *selection_data,
521 gtk_selection_data_set_text (selection_data, data, -1);
525 text_clear_func (GtkClipboard *clipboard,
532 * gtk_clipboard_set_text:
533 * @clipboard: a #GtkClipboard object
534 * @text: a UTF-8 string.
535 * @len: length of @text, in bytes, or -1, in which case
536 * the length will be determined with <function>strlen()</function>.
538 * Sets the contents of the clipboard to the given UTF-8 string. GTK+ will
539 * make a copy of the text and take responsibility for responding
540 * for requests for the text, and for converting the text into
541 * the requested format.
544 gtk_clipboard_set_text (GtkClipboard *clipboard,
548 static const GtkTargetEntry targets[] = {
549 { "STRING", 0, TARGET_STRING },
550 { "TEXT", 0, TARGET_TEXT },
551 { "COMPOUND_TEXT", 0, TARGET_COMPOUND_TEXT },
552 { "UTF8_STRING", 0, TARGET_UTF8_STRING }
555 g_return_if_fail (clipboard != NULL);
556 g_return_if_fail (text != NULL);
561 gtk_clipboard_set_with_data (clipboard,
562 targets, G_N_ELEMENTS (targets),
563 text_get_func, text_clear_func,
564 g_strndup (text, len));
568 set_request_contents_info (GtkWidget *widget,
569 RequestContentsInfo *info)
571 if (!request_contents_key_id)
572 request_contents_key_id = g_quark_from_static_string (request_contents_key);
574 gtk_object_set_data_by_id (GTK_OBJECT (widget),
575 request_contents_key_id,
579 static RequestContentsInfo *
580 get_request_contents_info (GtkWidget *widget)
582 if (!request_contents_key_id)
585 return gtk_object_get_data_by_id (GTK_OBJECT (widget),
586 request_contents_key_id);
590 selection_received (GtkWidget *widget,
591 GtkSelectionData *selection_data,
594 RequestContentsInfo *request_info = get_request_contents_info (widget);
595 set_request_contents_info (widget, NULL);
597 request_info->callback (gtk_clipboard_get (selection_data->selection),
599 request_info->user_data);
601 g_free (request_info);
603 if (widget != clipboard_widget)
604 gtk_widget_destroy (widget);
608 * gtk_clipboard_request_contents:
609 * @clipboard: a #GtkClipboard
610 * @target: an atom representing the form into which the clipboard
611 * owner should convert the selection.
612 * @callback: A function to call when the results are received
613 * (or the retrieval fails). If the retrieval fails
614 * the length field of @selection_data will be
616 * @user_data: user data to pass to @callback
618 * Requests the contents of clipboard as the given target.
619 * When the results of the result are later received the supplied callback
623 gtk_clipboard_request_contents (GtkClipboard *clipboard,
625 GtkClipboardReceivedFunc callback,
628 RequestContentsInfo *info;
631 g_return_if_fail (clipboard != NULL);
632 g_return_if_fail (target != GDK_NONE);
633 g_return_if_fail (callback != NULL);
635 ensure_clipboard_widget ();
637 if (get_request_contents_info (clipboard_widget))
638 widget = make_clipboard_widget (FALSE);
640 widget = clipboard_widget;
642 info = g_new (RequestContentsInfo, 1);
643 info->callback = callback;
644 info->user_data = user_data;
646 set_request_contents_info (widget, info);
648 gtk_selection_convert (widget, clipboard->selection, target,
649 clipboard_get_timestamp (clipboard));
653 request_text_received_func (GtkClipboard *clipboard,
654 GtkSelectionData *selection_data,
657 RequestTextInfo *info = data;
658 gchar *result = NULL;
660 result = gtk_selection_data_get_text (selection_data);
664 /* If we asked for UTF8 and didn't get it, try compound_text;
665 * if we asked for compound_text and didn't get it, try string;
666 * If we asked for anything else and didn't get it, give up.
668 if (selection_data->target == gdk_atom_intern ("UTF8_STRING", FALSE))
670 gtk_clipboard_request_contents (clipboard,
671 gdk_atom_intern ("COMPOUND_TEXT", FALSE),
672 request_text_received_func, info);
675 else if (selection_data->target == gdk_atom_intern ("COMPOUND_TEXT", FALSE))
677 gtk_clipboard_request_contents (clipboard,
679 request_text_received_func, info);
684 info->callback (clipboard, result, info->user_data);
690 * gtk_clipboard_request_text:
691 * @clipboard: a #GtkClipboard
692 * @callback: a function to call when the text is received,
693 * or the retrieval fails. (It will always be called
694 * one way or the other.)
695 * @user_data: user data to pass to @callback.
697 * Requests the contents of the clipboard as text. When the text is
698 * later received, it will be converted to UTF-8 if necessary, and
699 * @callback will be called.
701 * The @text parameter to @callback will contain the resulting text if
702 * the request succeeded, or %NULL if it failed. This could happen for
703 * various reasons, in particular if the clipboard was empty or if the
704 * contents of the clipboard could not be converted into text form.
707 gtk_clipboard_request_text (GtkClipboard *clipboard,
708 GtkClipboardTextReceivedFunc callback,
711 RequestTextInfo *info;
713 g_return_if_fail (clipboard != NULL);
714 g_return_if_fail (callback != NULL);
716 info = g_new (RequestTextInfo, 1);
717 info->callback = callback;
718 info->user_data = user_data;
720 gtk_clipboard_request_contents (clipboard, gdk_atom_intern ("UTF8_STRING", FALSE),
721 request_text_received_func,
733 clipboard_received_func (GtkClipboard *clipboard,
734 GtkSelectionData *selection_data,
737 WaitResults *results = data;
739 if (selection_data->length >= 0)
740 results->data = gtk_selection_data_copy (selection_data);
742 g_main_quit (results->loop);
746 * gtk_clipboard_wait_for_contents:
747 * @clipboard: a #GtkClipboard
748 * @target: an atom representing the form into which the clipboard
749 * owner should convert the selection.
751 * Requests the contents of the clipboard using the given target.
752 * This function waits for the data to be received using the main
753 * loop, so events, timeouts, etc, may be dispatched during the wait.
755 * Return value: a newly-allocated #GtkSelectionData object or %NULL
756 * if retrieving the given target failed. If non-%NULL,
757 * this value must be freed with gtk_selection_data_free()
758 * when you are finished with it.
761 gtk_clipboard_wait_for_contents (GtkClipboard *clipboard,
766 g_return_val_if_fail (clipboard != NULL, NULL);
767 g_return_val_if_fail (target != GDK_NONE, NULL);
770 results.loop = g_main_new (TRUE);
772 gtk_clipboard_request_contents (clipboard, target,
773 clipboard_received_func,
776 if (g_main_is_running (results.loop))
778 GDK_THREADS_LEAVE ();
779 g_main_run (results.loop);
780 GDK_THREADS_ENTER ();
783 g_main_destroy (results.loop);
789 clipboard_text_received_func (GtkClipboard *clipboard,
793 WaitResults *results = data;
795 results->data = g_strdup (text);
796 g_main_quit (results->loop);
801 * gtk_clipboard_wait_for_text:
802 * @clipboard: a #GtkClipboard
804 * Requests the contents of the clipboard as text and converts
805 * the result to UTF-8 if necessary. This function waits for
806 * the data to be received using the main loop, so events,
807 * timeouts, etc, may be dispatched during the wait.
809 * Return value: a newly-allocated UTF-8 string which must
810 * be freed with g_free(), or %NULL if retrieving
811 * the selection data failed. (This could happen
812 * for various reasons, in particular if the
813 * clipboard was empty or if the contents of the
814 * clipboard could not be converted into text form.)
817 gtk_clipboard_wait_for_text (GtkClipboard *clipboard)
821 g_return_val_if_fail (clipboard != NULL, NULL);
822 g_return_val_if_fail (clipboard != NULL, NULL);
825 results.loop = g_main_new (TRUE);
827 gtk_clipboard_request_text (clipboard,
828 clipboard_text_received_func,
831 if (g_main_is_running (results.loop))
833 GDK_THREADS_LEAVE ();
834 g_main_run (results.loop);
835 GDK_THREADS_ENTER ();
838 g_main_destroy (results.loop);
844 * gtk_clipboard_wait_is_text_available:
845 * @clipboard: a #GtkClipboard
847 * Test to see if there is text available to be pasted
848 * This is done by requesting the TARGETS atom and checking
849 * if it contains any of the names: STRING, TEXT, COMPOUND_TEXT,
850 * UTF8_STRING. This function waits for the data to be received
851 * using the main loop, so events, timeouts, etc, may be dispatched
854 * This function is a little faster than calling
855 * gtk_clipboard_wait_for_text() since it doesn't need to retrieve
858 * Return value: %TRUE is there is text available, %FALSE otherwise.
861 gtk_clipboard_wait_is_text_available (GtkClipboard *clipboard)
863 GtkSelectionData *data;
864 gboolean result = FALSE;
866 data = gtk_clipboard_wait_for_contents (clipboard, gdk_atom_intern ("TARGETS", FALSE));
869 result = gtk_selection_data_targets_include_text (data);
870 gtk_selection_data_free (data);