Pileus Git - ~andy/gtk/blob - gtk/gtkclipboard.c

   1 /* GTK - The GIMP Toolkit
   2  * Copyright (C) 2000 Red Hat, Inc.
   3  *
   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.
   8  *
   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.
  13  *
  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.
  18  *
  19  * Global clipboard abstraction.
  20  */
  21
  22 #include <string.h>
  23
  24 #include "gtkclipboard.h"
  25 #include "gtkinvisible.h"
  26 #include "gtkmain.h"
  27 #include "gtksignal.h"
  28
  29 #ifdef GDK_WINDOWING_X11
  30 #include "x11/gdkx.h"
  31 #endif
  32
  33 #ifdef GDK_WINDOWING_WIN32
  34 #include "win32/gdkwin32.h"
  35 #endif
  36
  37 typedef struct _RequestContentsInfo RequestContentsInfo;
  38 typedef struct _RequestTextInfo RequestTextInfo;
  39
  40 struct _GtkClipboard
  41 {
  42   GdkAtom selection;
  43
  44   GtkClipboardGetFunc get_func;
  45   GtkClipboardClearFunc clear_func;
  46   gpointer user_data;
  47   gboolean have_owner;
  48
  49   guint32 timestamp;
  50
  51   gboolean have_selection;
  52 };
  53
  54 struct _RequestContentsInfo
  55 {
  56   GtkClipboardReceivedFunc callback;
  57   gpointer user_data;
  58 };
  59
  60 struct _RequestTextInfo
  61 {
  62   GtkClipboardTextReceivedFunc callback;
  63   gpointer user_data;
  64 };
  65
  66 static void clipboard_unset    (GtkClipboard     *clipboard);
  67 static void selection_received (GtkWidget        *widget,
  68                                 GtkSelectionData *selection_data,
  69                                 guint             time);
  70
  71 static GSList *clipboards;
  72 static GtkWidget *clipboard_widget;
  73
  74 enum {
  75   TARGET_STRING,
  76   TARGET_TEXT,
  77   TARGET_COMPOUND_TEXT,
  78   TARGET_UTF8_STRING
  79 };
  80
  81 static const gchar *request_contents_key = "gtk-request-contents";
  82 static GQuark request_contents_key_id = 0;
  83
  84 static const gchar *clipboards_owned_key = "gtk-clipboards-owned";
  85 static GQuark clipboards_owned_key_id = 0;
  86
  87
  88 /**
  89  * gtk_clipboard_get:
  90  * @selection: a #GdkAtom which identifies the clipboard
  91  *             to use.
  92  *
  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.
 101  *
 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.)
 109  *
 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".
 116  *
 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
 121  *             cannot be freed.
 122  **/
 123 GtkClipboard *
 124 gtk_clipboard_get (GdkAtom selection)
 125 {
 126   GtkClipboard *clipboard = NULL;
 127   GSList *tmp_list;
 128
 129   if (selection == GDK_NONE)
 130     selection = gdk_atom_intern ("CLIPBOARD", FALSE);
 131
 132   tmp_list = clipboards;
 133   while (tmp_list)
 134     {
 135       clipboard = tmp_list->data;
 136       if (clipboard->selection == selection)
 137         break;
 138
 139       tmp_list = tmp_list->next;
 140     }
 141
 142   if (!tmp_list)
 143     {
 144       clipboard = g_new0 (GtkClipboard, 1);
 145       clipboard->selection = selection;
 146       clipboards = g_slist_prepend (clipboards, clipboard);
 147     }
 148
 149   return clipboard;
 150 }
 151
 152 static void
 153 selection_get_cb (GtkWidget          *widget,
 154                   GtkSelectionData   *selection_data,
 155                   guint               time,
 156                   guint               info)
 157 {
 158   GtkClipboard *clipboard = gtk_clipboard_get (selection_data->selection);
 159
 160   if (clipboard && clipboard->get_func)
 161     clipboard->get_func (clipboard, selection_data, info, clipboard->user_data);
 162 }
 163
 164 static gboolean
 165 selection_clear_event_cb (GtkWidget         *widget,
 166                           GdkEventSelection *event)
 167 {
 168   GtkClipboard *clipboard = gtk_clipboard_get (event->selection);
 169
 170   if (clipboard)
 171     {
 172       clipboard_unset (clipboard);
 173       return TRUE;
 174     }
 175
 176   return FALSE;
 177 }
 178
 179 static GtkWidget *
 180 make_clipboard_widget (gboolean provider)
 181 {
 182   GtkWidget *widget = gtk_invisible_new ();
 183
 184   gtk_signal_connect (GTK_OBJECT (widget), "selection_received",
 185                       GTK_SIGNAL_FUNC (selection_received), NULL);
 186
 187   if (provider)
 188     {
 189       /* We need this for gdk_x11_get_server_time() */
 190       gtk_widget_add_events (widget, GDK_PROPERTY_CHANGE_MASK);
 191
 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);
 196     }
 197
 198   return widget;
 199 }
 200
 201
 202 static void
 203 ensure_clipboard_widget ()
 204 {
 205   if (!clipboard_widget)
 206     clipboard_widget = make_clipboard_widget (TRUE);
 207 }
 208
 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.
 215  *
 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.
 223  */
 224 static guint32
 225 clipboard_get_timestamp (GtkClipboard *clipboard)
 226 {
 227   guint32 timestamp = gtk_get_current_event_time ();
 228
 229   ensure_clipboard_widget ();
 230
 231   if (timestamp == GDK_CURRENT_TIME)
 232     {
 233 #ifdef GDK_WINDOWING_X11
 234       timestamp = gdk_x11_get_server_time (clipboard_widget->window);
 235 #elif defined GDK_WINDOWING_WIN32
 236       timestamp = GetMessageTime ();
 237 #endif
 238     }
 239   else
 240     {
 241       if (clipboard->timestamp != GDK_CURRENT_TIME)
 242         {
 243           /* Check to see if clipboard->timestamp is newer than
 244            * timestamp, accounting for wraparound.
 245            */
 246
 247           guint32 max = timestamp + 0x80000000;
 248
 249           if ((max > timestamp &&
 250                (clipboard->timestamp > timestamp &&
 251                 clipboard->timestamp <= max)) ||
 252               (max <= timestamp &&
 253                (clipboard->timestamp > timestamp ||
 254                 clipboard->timestamp <= max)))
 255             {
 256               timestamp = clipboard->timestamp;
 257             }
 258         }
 259     }
 260
 261   clipboard->timestamp = timestamp;
 262
 263   return timestamp;
 264 }
 265
 266 static void
 267 clipboard_owner_destroyed (gpointer data)
 268 {
 269   GSList *clipboards = data;
 270   GSList *tmp_list;
 271
 272   tmp_list = clipboards;
 273   while (tmp_list)
 274     {
 275       GtkClipboard *clipboard = tmp_list->data;
 276
 277       clipboard->get_func = NULL;
 278       clipboard->clear_func = NULL;
 279       clipboard->user_data = NULL;
 280       clipboard->have_owner = FALSE;
 281
 282       gtk_clipboard_clear (clipboard);
 283
 284       tmp_list = tmp_list->next;
 285     }
 286
 287   g_slist_free (clipboards);
 288 }
 289
 290 static void
 291 clipboard_add_owner_notify (GtkClipboard *clipboard)
 292 {
 293   if (!clipboards_owned_key_id)
 294     clipboards_owned_key_id = g_quark_from_static_string (clipboards_owned_key);
 295
 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),
 300                                               clipboard),
 301                              clipboard_owner_destroyed);
 302 }
 303
 304 static void
 305 clipboard_remove_owner_notify (GtkClipboard *clipboard)
 306 {
 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),
 311                                               clipboard),
 312                               clipboard_owner_destroyed);
 313 }
 314
 315 static gboolean
 316 gtk_clipboard_set_contents (GtkClipboard         *clipboard,
 317                             const GtkTargetEntry *targets,
 318                             guint                 n_targets,
 319                             GtkClipboardGetFunc   get_func,
 320                             GtkClipboardClearFunc clear_func,
 321                             gpointer              user_data,
 322                             gboolean              have_owner)
 323 {
 324   ensure_clipboard_widget ();
 325
 326   if (gtk_selection_owner_set (clipboard_widget, clipboard->selection,
 327                                clipboard_get_timestamp (clipboard)))
 328     {
 329       clipboard->have_selection = TRUE;
 330
 331       if (!(clipboard->have_owner && have_owner) ||
 332           clipboard->user_data != user_data)
 333         {
 334           clipboard_unset (clipboard);
 335
 336           if (clipboard->get_func)
 337             {
 338               /* Calling unset() caused the clipboard contents to be reset!
 339                * Avoid leaking and return
 340                */
 341               if (!(clipboard->have_owner && have_owner) ||
 342                   clipboard->user_data != user_data)
 343                 {
 344                   (*clear_func) (clipboard, user_data);
 345                   return FALSE;
 346                 }
 347               else
 348                 return TRUE;
 349             }
 350           else
 351             {
 352               clipboard->user_data = user_data;
 353               clipboard->have_owner = have_owner;
 354               if (have_owner)
 355                 clipboard_add_owner_notify (clipboard);
 356             }
 357
 358         }
 359
 360       clipboard->get_func = get_func;
 361       clipboard->clear_func = clear_func;
 362
 363       gtk_selection_clear_targets (clipboard_widget, clipboard->selection);
 364       gtk_selection_add_targets (clipboard_widget, clipboard->selection,
 365                                  targets, n_targets);
 366
 367       return TRUE;
 368     }
 369   else
 370     return FALSE;
 371 }
 372
 373 /**
 374  * gtk_clipboard_set_with_data:
 375  * @clipboard:  a #GtkClipboard
 376  * @targets:    array containing information about the available forms for the
 377  *              clipboard data
 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.
 383  *
 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.
 387  *
 388  * Return value: %TRUE if setting the clipboard data succeeded. If setting
 389  *               the clipboard data failed the provided callback functions
 390  *               will be ignored.
 391  **/
 392 gboolean
 393 gtk_clipboard_set_with_data (GtkClipboard          *clipboard,
 394                              const GtkTargetEntry  *targets,
 395                              guint                  n_targets,
 396                              GtkClipboardGetFunc    get_func,
 397                              GtkClipboardClearFunc  clear_func,
 398                              gpointer               user_data)
 399 {
 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);
 403
 404   return gtk_clipboard_set_contents (clipboard, targets, n_targets,
 405                                      get_func, clear_func, user_data,
 406                                      FALSE);
 407 }
 408
 409 /**
 410  * gtk_clipboard_set_with_owner:
 411  * @clipboard:  a #GtkClipboard
 412  * @targets:    array containing information about the available forms for the
 413  *              clipboard data
 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.
 420  *
 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.
 424  *
 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
 427  * in.
 428  *
 429  * Return value: %TRUE if setting the clipboard data succeeded. If setting
 430  *               the clipboard data failed the provided callback functions
 431  *               will be ignored.
 432  **/
 433 gboolean
 434 gtk_clipboard_set_with_owner (GtkClipboard          *clipboard,
 435                               const GtkTargetEntry  *targets,
 436                               guint                  n_targets,
 437                               GtkClipboardGetFunc    get_func,
 438                               GtkClipboardClearFunc  clear_func,
 439                               GObject               *owner)
 440 {
 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);
 445
 446   return gtk_clipboard_set_contents (clipboard, targets, n_targets,
 447                                      get_func, clear_func, owner,
 448                                      TRUE);
 449 }
 450
 451 /**
 452  * gtk_clipboard_get_owner:
 453  * @clipboard: a #GtkClipboard
 454  *
 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().
 459  *
 460  * Return value: the owner of the clipboard, if any; otherwise %NULL.
 461  **/
 462 GObject *
 463 gtk_clipboard_get_owner (GtkClipboard *clipboard)
 464 {
 465   g_return_val_if_fail (clipboard != NULL, NULL);
 466
 467   if (clipboard->have_owner)
 468     return clipboard->user_data;
 469   else
 470     return NULL;
 471 }
 472
 473 static void
 474 clipboard_unset (GtkClipboard *clipboard)
 475 {
 476   GtkClipboardClearFunc old_clear_func;
 477   gpointer old_data;
 478
 479   old_clear_func = clipboard->clear_func;
 480   old_data = clipboard->user_data;
 481
 482   if (clipboard->have_owner)
 483     {
 484       clipboard_remove_owner_notify (clipboard);
 485       clipboard->have_owner = FALSE;
 486     }
 487
 488   clipboard->get_func = NULL;
 489   clipboard->clear_func = NULL;
 490   clipboard->user_data = NULL;
 491
 492   if (old_clear_func)
 493     old_clear_func (clipboard, old_data);
 494 }
 495
 496 /**
 497  * gtk_clipboard_clear:
 498  * @clipboard:  a #GtkClipboard
 499  *
 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.
 504  **/
 505 void
 506 gtk_clipboard_clear (GtkClipboard *clipboard)
 507 {
 508   g_return_if_fail (clipboard != NULL);
 509
 510   if (clipboard->have_selection)
 511     gtk_selection_owner_set (NULL, clipboard->selection,
 512                              clipboard_get_timestamp (clipboard));
 513 }
 514
 515 static void
 516 text_get_func (GtkClipboard     *clipboard,
 517                GtkSelectionData *selection_data,
 518                guint             info,
 519                gpointer          data)
 520 {
 521   gtk_selection_data_set_text (selection_data, data, -1);
 522 }
 523
 524 static void
 525 text_clear_func (GtkClipboard *clipboard,
 526                  gpointer      data)
 527 {
 528   g_free (data);
 529 }
 530
 531 /**
 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>.
 537  *
 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.
 542  **/
 543 void
 544 gtk_clipboard_set_text (GtkClipboard *clipboard,
 545                         const gchar  *text,
 546                         gint          len)
 547 {
 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 }
 553   };
 554
 555   g_return_if_fail (clipboard != NULL);
 556   g_return_if_fail (text != NULL);
 557
 558   if (len < 0)
 559     len = strlen (text);
 560
 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));
 565 }
 566
 567 static void
 568 set_request_contents_info (GtkWidget           *widget,
 569                            RequestContentsInfo *info)
 570 {
 571   if (!request_contents_key_id)
 572     request_contents_key_id = g_quark_from_static_string (request_contents_key);
 573
 574   gtk_object_set_data_by_id (GTK_OBJECT (widget),
 575                              request_contents_key_id,
 576                              info);
 577 }
 578
 579 static RequestContentsInfo *
 580 get_request_contents_info (GtkWidget *widget)
 581 {
 582   if (!request_contents_key_id)
 583     return NULL;
 584   else
 585     return gtk_object_get_data_by_id (GTK_OBJECT (widget),
 586                                       request_contents_key_id);
 587 }
 588
 589 static void
 590 selection_received (GtkWidget            *widget,
 591                     GtkSelectionData     *selection_data,
 592                     guint                 time)
 593 {
 594   RequestContentsInfo *request_info = get_request_contents_info (widget);
 595   set_request_contents_info (widget, NULL);
 596
 597   request_info->callback (gtk_clipboard_get (selection_data->selection),
 598                           selection_data,
 599                           request_info->user_data);
 600
 601   g_free (request_info);
 602
 603   if (widget != clipboard_widget)
 604     gtk_widget_destroy (widget);
 605 }
 606
 607 /**
 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
 615  *             negative.
 616  * @user_data: user data to pass to @callback
 617  *
 618  * Requests the contents of clipboard as the given target.
 619  * When the results of the result are later received the supplied callback
 620  * will be called.
 621  **/
 622 void
 623 gtk_clipboard_request_contents (GtkClipboard            *clipboard,
 624                                 GdkAtom                  target,
 625                                 GtkClipboardReceivedFunc callback,
 626                                 gpointer                 user_data)
 627 {
 628   RequestContentsInfo *info;
 629   GtkWidget *widget;
 630
 631   g_return_if_fail (clipboard != NULL);
 632   g_return_if_fail (target != GDK_NONE);
 633   g_return_if_fail (callback != NULL);
 634
 635   ensure_clipboard_widget ();
 636
 637   if (get_request_contents_info (clipboard_widget))
 638     widget = make_clipboard_widget (FALSE);
 639   else
 640     widget = clipboard_widget;
 641
 642   info = g_new (RequestContentsInfo, 1);
 643   info->callback = callback;
 644   info->user_data = user_data;
 645
 646   set_request_contents_info (widget, info);
 647
 648   gtk_selection_convert (widget, clipboard->selection, target,
 649                          clipboard_get_timestamp (clipboard));
 650 }
 651
 652 static void
 653 request_text_received_func (GtkClipboard     *clipboard,
 654                             GtkSelectionData *selection_data,
 655                             gpointer          data)
 656 {
 657   RequestTextInfo *info = data;
 658   gchar *result = NULL;
 659
 660   result = gtk_selection_data_get_text (selection_data);
 661
 662   if (!result)
 663     {
 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.
 667        */
 668       if (selection_data->target == gdk_atom_intern ("UTF8_STRING", FALSE))
 669         {
 670           gtk_clipboard_request_contents (clipboard,
 671                                           gdk_atom_intern ("COMPOUND_TEXT", FALSE),
 672                                           request_text_received_func, info);
 673           return;
 674         }
 675       else if (selection_data->target == gdk_atom_intern ("COMPOUND_TEXT", FALSE))
 676         {
 677           gtk_clipboard_request_contents (clipboard,
 678                                           GDK_TARGET_STRING,
 679                                           request_text_received_func, info);
 680           return;
 681         }
 682     }
 683
 684   info->callback (clipboard, result, info->user_data);
 685   g_free (info);
 686   g_free (result);
 687 }
 688
 689 /**
 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.
 696  *
 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.
 700  *
 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.
 705  **/
 706 void
 707 gtk_clipboard_request_text (GtkClipboard                *clipboard,
 708                             GtkClipboardTextReceivedFunc callback,
 709                             gpointer                     user_data)
 710 {
 711   RequestTextInfo *info;
 712
 713   g_return_if_fail (clipboard != NULL);
 714   g_return_if_fail (callback != NULL);
 715
 716   info = g_new (RequestTextInfo, 1);
 717   info->callback = callback;
 718   info->user_data = user_data;
 719
 720   gtk_clipboard_request_contents (clipboard, gdk_atom_intern ("UTF8_STRING", FALSE),
 721                                   request_text_received_func,
 722                                   info);
 723 }
 724
 725
 726 typedef struct
 727 {
 728   GMainLoop *loop;
 729   gpointer data;
 730 } WaitResults;
 731
 732 static void
 733 clipboard_received_func (GtkClipboard     *clipboard,
 734                          GtkSelectionData *selection_data,
 735                          gpointer          data)
 736 {
 737   WaitResults *results = data;
 738
 739   if (selection_data->length >= 0)
 740     results->data = gtk_selection_data_copy (selection_data);
 741
 742   g_main_quit (results->loop);
 743 }
 744
 745 /**
 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.
 750  *
 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.
 754  *
 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.
 759  **/
 760 GtkSelectionData *
 761 gtk_clipboard_wait_for_contents (GtkClipboard *clipboard,
 762                                  GdkAtom       target)
 763 {
 764   WaitResults results;
 765
 766   g_return_val_if_fail (clipboard != NULL, NULL);
 767   g_return_val_if_fail (target != GDK_NONE, NULL);
 768
 769   results.data = NULL;
 770   results.loop = g_main_new (TRUE);
 771
 772   gtk_clipboard_request_contents (clipboard, target,
 773                                   clipboard_received_func,
 774                                   &results);
 775
 776   if (g_main_is_running (results.loop))
 777     {
 778       GDK_THREADS_LEAVE ();
 779       g_main_run (results.loop);
 780       GDK_THREADS_ENTER ();
 781     }
 782
 783   g_main_destroy (results.loop);
 784
 785   return results.data;
 786 }
 787
 788 static void
 789 clipboard_text_received_func (GtkClipboard *clipboard,
 790                               const gchar  *text,
 791                               gpointer      data)
 792 {
 793   WaitResults *results = data;
 794
 795   results->data = g_strdup (text);
 796   g_main_quit (results->loop);
 797 }
 798
 799
 800 /**
 801  * gtk_clipboard_wait_for_text:
 802  * @clipboard: a #GtkClipboard
 803  *
 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.
 808  *
 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.)
 815  **/
 816 gchar *
 817 gtk_clipboard_wait_for_text (GtkClipboard *clipboard)
 818 {
 819   WaitResults results;
 820
 821   g_return_val_if_fail (clipboard != NULL, NULL);
 822   g_return_val_if_fail (clipboard != NULL, NULL);
 823
 824   results.data = NULL;
 825   results.loop = g_main_new (TRUE);
 826
 827   gtk_clipboard_request_text (clipboard,
 828                               clipboard_text_received_func,
 829                               &results);
 830
 831   if (g_main_is_running (results.loop))
 832     {
 833       GDK_THREADS_LEAVE ();
 834       g_main_run (results.loop);
 835       GDK_THREADS_ENTER ();
 836     }
 837
 838   g_main_destroy (results.loop);
 839
 840   return results.data;
 841 }
 842
 843 /**
 844  * gtk_clipboard_wait_is_text_available:
 845  * @clipboard: a #GtkClipboard
 846  *
 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
 852  * during the wait.
 853  *
 854  * This function is a little faster than calling
 855  * gtk_clipboard_wait_for_text() since it doesn't need to retrieve
 856  * the actual text.
 857  *
 858  * Return value: %TRUE is there is text available, %FALSE otherwise.
 859  **/
 860 gboolean
 861 gtk_clipboard_wait_is_text_available (GtkClipboard *clipboard)
 862 {
 863   GtkSelectionData *data;
 864   gboolean result = FALSE;
 865
 866   data = gtk_clipboard_wait_for_contents (clipboard, gdk_atom_intern ("TARGETS", FALSE));
 867   if (data)
 868     {
 869       result = gtk_selection_data_targets_include_text (data);
 870       gtk_selection_data_free (data);
 871     }
 872
 873   return result;
 874 }