gtk+ r20465 - in trunk: . docs/reference/gtk gtk

[chpe svn gnome org]

Author: chpe
Date: Thu Jun 19 12:55:57 2008
New Revision: 20465
URL: http://svn.gnome.org/viewvc/gtk+?rev=20465&view=rev

Log:
Add clipboard convenience helpers for URIs. Bug #537639.


Modified:
   trunk/ChangeLog
   trunk/docs/reference/gtk/gtk-sections.txt
   trunk/gtk/gtk.symbols
   trunk/gtk/gtkclipboard.c
   trunk/gtk/gtkclipboard.h

Modified: trunk/docs/reference/gtk/gtk-sections.txt
==============================================================================
--- trunk/docs/reference/gtk/gtk-sections.txt	(original)
+++ trunk/docs/reference/gtk/gtk-sections.txt	Thu Jun 19 12:55:57 2008
@@ -5822,13 +5822,16 @@
 gtk_clipboard_request_image
 gtk_clipboard_request_targets
 gtk_clipboard_request_rich_text
+gtk_clipboard_request_uris
 gtk_clipboard_wait_for_contents
 gtk_clipboard_wait_for_text
 gtk_clipboard_wait_for_image
 gtk_clipboard_wait_for_rich_text
+gtk_clipboard_wait_for_uris
 gtk_clipboard_wait_is_text_available
 gtk_clipboard_wait_is_image_available
 gtk_clipboard_wait_is_rich_text_available
+gtk_clipboard_wait_is_uris_available
 gtk_clipboard_wait_for_targets
 gtk_clipboard_wait_is_target_available
 gtk_clipboard_set_can_store

Modified: trunk/gtk/gtk.symbols
==============================================================================
--- trunk/gtk/gtk.symbols	(original)
+++ trunk/gtk/gtk.symbols	Thu Jun 19 12:55:57 2008
@@ -679,6 +679,7 @@
 gtk_clipboard_request_rich_text
 gtk_clipboard_request_targets
 gtk_clipboard_request_text
+gtk_clipboard_request_uris
 gtk_clipboard_set_can_store
 gtk_clipboard_set_image
 gtk_clipboard_set_text
@@ -688,11 +689,13 @@
 gtk_clipboard_wait_for_contents
 gtk_clipboard_wait_for_image
 gtk_clipboard_wait_for_rich_text
+gtk_clipboard_wait_for_uris
 gtk_clipboard_wait_for_targets
 gtk_clipboard_wait_for_text
 gtk_clipboard_wait_is_image_available
 gtk_clipboard_wait_is_rich_text_available
 gtk_clipboard_wait_is_text_available
+gtk_clipboard_wait_is_uris_available
 gtk_clipboard_wait_is_target_available
 #endif
 #endif

Modified: trunk/gtk/gtkclipboard.c
==============================================================================
--- trunk/gtk/gtkclipboard.c	(original)
+++ trunk/gtk/gtkclipboard.c	Thu Jun 19 12:55:57 2008
@@ -50,6 +50,7 @@
 typedef struct _RequestTextInfo RequestTextInfo;
 typedef struct _RequestRichTextInfo RequestRichTextInfo;
 typedef struct _RequestImageInfo RequestImageInfo;
+typedef struct _RequestURIInfo RequestURIInfo;
 typedef struct _RequestTargetsInfo RequestTargetsInfo;
 
 struct _GtkClipboard 
@@ -114,6 +115,12 @@
   gpointer user_data;
 };
 
+struct _RequestURIInfo
+{
+  GtkClipboardURIReceivedFunc callback;
+  gpointer user_data;
+};
+
 struct _RequestTargetsInfo
 {
   GtkClipboardTargetsReceivedFunc callback;
@@ -1140,6 +1147,58 @@
 }
 
 static void 
+request_uris_received_func (GtkClipboard     *clipboard,
+			    GtkSelectionData *selection_data,
+			    gpointer          data)
+{
+  RequestURIInfo *info = data;
+  gchar **uris;
+
+  uris = gtk_selection_data_get_uris (selection_data);
+  info->callback (clipboard, uris, info->user_data);
+  g_strfreev (uris);
+
+  g_slice_free (RequestURIInfo, info);
+}
+
+/**
+ * gtk_clipboard_request_uris:
+ * @clipboard: a #GtkClipboard
+ * @callback:  a function to call when the URIs are received,
+ *             or the retrieval fails. (It will always be called
+ *             one way or the other.)
+ * @user_data: user data to pass to @callback.
+ * 
+ * Requests the contents of the clipboard as URIs. When the URIs are
+ * later received @callback will be called.
+ *
+ * The @uris parameter to @callback will contain the resulting array of
+ * URIs if the request succeeded, or %NULL if it failed. This could happen
+ * for various reasons, in particular if the clipboard was empty or if the
+ * contents of the clipboard could not be converted into URI form.
+ *
+ * Since: 2.14
+ **/
+void 
+gtk_clipboard_request_uris (GtkClipboard                *clipboard,
+			    GtkClipboardURIReceivedFunc  callback,
+			    gpointer                     user_data)
+{
+  RequestURIInfo *info;
+  
+  g_return_if_fail (clipboard != NULL);
+  g_return_if_fail (callback != NULL);
+  
+  info = g_slice_new (RequestURIInfo);
+  info->callback = callback;
+  info->user_data = user_data;
+
+  gtk_clipboard_request_contents (clipboard, gdk_atom_intern_static_string ("text/uri-list"),
+				  request_uris_received_func,
+				  info);
+}
+
+static void 
 request_targets_received_func (GtkClipboard     *clipboard,
 			       GtkSelectionData *selection_data,
 			       gpointer          data)
@@ -1443,6 +1502,60 @@
   return results.data;
 }
 
+static void 
+clipboard_uris_received_func (GtkClipboard *clipboard,
+			      gchar       **uris,
+			      gpointer      data)
+{
+  WaitResults *results = data;
+
+  results->data = g_strdupv (uris);
+  g_main_loop_quit (results->loop);
+}
+
+/**
+ * gtk_clipboard_wait_for_uris:
+ * @clipboard: a #GtkClipboard
+ * 
+ * Requests the contents of the clipboard as URIs. This function waits
+ * for the data to be received using the main loop, so events,
+ * timeouts, etc, may be dispatched during the wait.
+ * 
+ * Return value: a newly-allocated %NULL-terminated array of strings which must
+ *               be freed with g_strfreev(), or %NULL if
+ *               retrieving the selection data failed. (This 
+ *               could happen for various reasons, in particular 
+ *               if the clipboard was empty or if the contents of 
+ *               the clipboard could not be converted into URI form.)
+ *
+ * Since: 2.14
+ **/
+gchar **
+gtk_clipboard_wait_for_uris (GtkClipboard *clipboard)
+{
+  WaitResults results;
+
+  g_return_val_if_fail (clipboard != NULL, NULL);
+  
+  results.data = NULL;
+  results.loop = g_main_loop_new (NULL, TRUE);
+
+  gtk_clipboard_request_uris (clipboard,
+			      clipboard_uris_received_func,
+			      &results);
+
+  if (g_main_loop_is_running (results.loop))
+    {
+      GDK_THREADS_LEAVE ();
+      g_main_loop_run (results.loop);
+      GDK_THREADS_ENTER ();
+    }
+
+  g_main_loop_unref (results.loop);
+
+  return results.data;
+}
+
 /**
  * gtk_clipboard_get_display:
  * @clipboard: a #GtkClipboard
@@ -1568,6 +1681,41 @@
 }
 
 /**
+ * gtk_clipboard_wait_is_uris_available:
+ * @clipboard: a #GtkClipboard
+ * 
+ * Test to see if there is a list of URIs available to be pasted
+ * This is done by requesting the TARGETS atom and checking
+ * if it contains the URI targets. This function
+ * waits for the data to be received using the main loop, so events, 
+ * timeouts, etc, may be dispatched during the wait.
+ *
+ * This function is a little faster than calling
+ * gtk_clipboard_wait_for_uris() since it doesn't need to retrieve
+ * the actual URI data.
+ * 
+ * Return value: %TRUE is there is an URI list available, %FALSE otherwise.
+ *
+ * Since: 2.14
+ **/
+gboolean
+gtk_clipboard_wait_is_uris_available (GtkClipboard *clipboard)
+{
+  GtkSelectionData *data;
+  gboolean result = FALSE;
+
+  data = gtk_clipboard_wait_for_contents (clipboard, 
+					  gdk_atom_intern_static_string ("TARGETS"));
+  if (data)
+    {
+      result = gtk_selection_data_targets_include_uri (data);
+      gtk_selection_data_free (data);
+    }
+
+  return result;
+}
+
+/**
  * gtk_clipboard_wait_for_targets
  * @clipboard: a #GtkClipboard
  * @targets: location to store an array of targets. The result

Modified: trunk/gtk/gtkclipboard.h
==============================================================================
--- trunk/gtk/gtkclipboard.h	(original)
+++ trunk/gtk/gtkclipboard.h	Thu Jun 19 12:55:57 2008
@@ -48,6 +48,9 @@
 typedef void (* GtkClipboardImageReceivedFunc)    (GtkClipboard     *clipboard,
 						   GdkPixbuf        *pixbuf,
 						   gpointer          data);
+typedef void (* GtkClipboardURIReceivedFunc)      (GtkClipboard     *clipboard,
+						   gchar           **uris,
+						   gpointer          data);
 typedef void (* GtkClipboardTargetsReceivedFunc)  (GtkClipboard     *clipboard,
 					           GdkAtom          *atoms,
 						   gint              n_atoms,
@@ -109,6 +112,9 @@
 void gtk_clipboard_request_image     (GtkClipboard                     *clipboard,
                                       GtkClipboardImageReceivedFunc     callback,
                                       gpointer                          user_data);
+void gtk_clipboard_request_uris      (GtkClipboard                     *clipboard,
+                                      GtkClipboardURIReceivedFunc       callback,
+                                      gpointer                          user_data);
 void gtk_clipboard_request_targets   (GtkClipboard                     *clipboard,
                                       GtkClipboardTargetsReceivedFunc   callback,
                                       gpointer                          user_data);
@@ -121,6 +127,7 @@
                                                     GdkAtom       *format,
                                                     gsize         *length);
 GdkPixbuf *       gtk_clipboard_wait_for_image     (GtkClipboard  *clipboard);
+gchar **          gtk_clipboard_wait_for_uris      (GtkClipboard  *clipboard);
 gboolean          gtk_clipboard_wait_for_targets   (GtkClipboard  *clipboard,
                                                     GdkAtom      **targets,
                                                     gint          *n_targets);
@@ -129,6 +136,7 @@
 gboolean gtk_clipboard_wait_is_rich_text_available (GtkClipboard  *clipboard,
                                                     GtkTextBuffer *buffer);
 gboolean gtk_clipboard_wait_is_image_available     (GtkClipboard  *clipboard);
+gboolean gtk_clipboard_wait_is_uris_available      (GtkClipboard  *clipboard);
 gboolean gtk_clipboard_wait_is_target_available    (GtkClipboard  *clipboard,
                                                     GdkAtom        target);