/**
* gtk_clipboard_get:
* @selection: a #GdkAtom which identifies the clipboard
- * to use. A value of GDK_NONE here is the
- * same as gdk_atom_intern ("CLIPBOARD", FALSE),
- * and provides the default clipboard. Another
- * common value is GDK_SELECTION_PRIMARY, which
- * identifies the primary X selection.
+ * to use.
*
* Returns the clipboard object for the given selection.
+ * Cut/copy/paste menu items and keyboard shortcuts should use
+ * the default clipboard, returned by passing #GDK_NONE for @selection.
+ * The currently-selected object or text should be provided on the clipboard
+ * identified by #GDK_SELECTION_PRIMARY. Cut/copy/paste menu items
+ * conceptually copy the contents of the #GDK_SELECTION_PRIMARY clipboard
+ * to the default clipboard, i.e. they copy the selection to what the
+ * user sees as the clipboard.
+ *
+ * (Passing #GDK_NONE is the same as using <literal>gdk_atom_intern
+ * ("CLIPBOARD", FALSE)</literal>. See
+ * <ulink url="http://www.freedesktop.org/standards/clipboards.txt">
+ * http://www.freedesktop.org/standards/clipboards.txt</ulink>
+ * for a detailed discussion of the "CLIPBOARD" vs. "PRIMARY" selections
+ * under the X window system. On Win32 the #GDK_SELECTION_PRIMARY
+ * clipboard is essentially ignored.)
+ *
+ * It's possible to have arbitrary named clipboards; if you do invent
+ * new clipboards, you should prefix the selection name with an
+ * underscore (because the ICCCM requires that nonstandard atoms are
+ * underscore-prefixed), and namespace it as well. For example,
+ * if your application called "Foo" has a special-purpose
+ * clipboard, you might call it "_FOO_SPECIAL_CLIPBOARD".
*
* Return value: the appropriate clipboard object. If no
* clipboard already exists, a new one will
* be created. Once a clipboard object has
- * been created, it is persistant for all time.
+ * been created, it is persistent for all time and
+ * cannot be freed.
**/
GtkClipboard *
gtk_clipboard_get (GdkAtom selection)
return FALSE;
}
-GtkWidget *
+static GtkWidget *
make_clipboard_widget (gboolean provider)
{
GtkWidget *widget = gtk_invisible_new ();
}
-void
+static void
ensure_clipboard_widget ()
{
if (!clipboard_widget)
* @n_targets: number of elements in @targets
* @get_func: function to call to get the actual clipboard data
* @clear_func: when the clipboard contents are set again, this function will
- * be called, and get_func will not be subsequently called.
+ * be called, and @get_func will not be subsequently called.
* @user_data: user data to pass to @get_func and @clear_func.
*
- * Virtually set the contents of the specified clipboard by providing
+ * Virtually sets the contents of the specified clipboard by providing
* a list of supported formats for the clipboard data and a function
* to call to get the actual data when it is requested.
*
* @n_targets: number of elements in @targets
* @get_func: function to call to get the actual clipboard data
* @clear_func: when the clipboard contents are set again, this function will
- * be called, and get_func will not be subsequently called.
+ * be called, and @get_func will not be subsequently called.
* @owner: an object that "owns" the data. This object will be passed
* to the callbacks when called.
*
- * Virtually set the contents of the specified clipboard by providing
+ * Virtually sets the contents of the specified clipboard by providing
* a list of supported formats for the clipboard data and a function
* to call to get the actual data when it is requested.
*
- * The difference between this function and gtk_clipboard_set_with_data
+ * The difference between this function and gtk_clipboard_set_with_data()
* is that instead of an generic @user_data pointer, a #GObject is passed
- * in. Because of this,
+ * in.
*
* Return value: %TRUE if setting the clipboard data succeeded. If setting
* the clipboard data failed the provided callback functions
* gtk_clipboard_get_owner:
* @clipboard: a #GtkClipboard
*
- * If the clipboard contents callbacks were set with gtk_clipboard_set_owner(),
- * and the gtk_clipboard_set_with_data() or gtk_clipboard_clear() has not
- * subsequently called, returns the @owner set by gtk_clipboard_set_owner().
+ * If the clipboard contents callbacks were set with
+ * gtk_clipboard_set_with_owner(), and the gtk_clipboard_set_with_data() or
+ * gtk_clipboard_clear() has not subsequently called, returns the owner set
+ * by gtk_clipboard_set_with_owner().
*
* Return value: the owner of the clipboard, if any; otherwise %NULL.
**/
* gtk_clipboard_clear:
* @clipboard: a #GtkClipboard
*
- * Clear the contents of the clipboard. Generally this should only
- * be called between the time you call gtk_clipboard_set_contents(),
+ * Clears the contents of the clipboard. Generally this should only
+ * be called between the time you call gtk_clipboard_set_with_owner()
+ * or gtk_clipboard_set_with_data(),
* and when the @clear_func you supplied is called. Otherwise, the
* clipboard may be owned by someone else.
**/
clipboard_get_timestamp (clipboard));
}
-void
+static void
text_get_func (GtkClipboard *clipboard,
GtkSelectionData *selection_data,
guint info,
gpointer data)
{
- gtk_selection_data_set_text (selection_data, data);
+ gtk_selection_data_set_text (selection_data, data, -1);
}
-void
+static void
text_clear_func (GtkClipboard *clipboard,
gpointer data)
{
* @clipboard: a #GtkClipboard object
* @text: a UTF-8 string.
* @len: length of @text, in bytes, or -1, in which case
- * the length will be determined with strlen().
+ * the length will be determined with <function>strlen()</function>.
*
- * Set the contents of the clipboard to the given UTF-8 string. GTK+ will
+ * Sets the contents of the clipboard to the given UTF-8 string. GTK+ will
* make a copy of the text and take responsibility for responding
* for requests for the text, and for converting the text into
* the requested format.
* @target: an atom representing the form into which the clipboard
* owner should convert the selection.
* @callback: A function to call when the results are received
- * (or the retrieval fails.) If the retrieval fails
+ * (or the retrieval fails). If the retrieval fails
* the length field of @selection_data will be
* negative.
* @user_data: user data to pass to @callback
if (!result)
{
- /* If we asked for UTF8 and didn't get it, try text; if we asked
- * for text and didn't get it, try string. If we asked for
- * anything else and didn't get it, give up.
+ /* If we asked for UTF8 and didn't get it, try compound_text;
+ * if we asked for compound_text and didn't get it, try string;
+ * If we asked for anything else and didn't get it, give up.
*/
if (selection_data->target == gdk_atom_intern ("UTF8_STRING", FALSE))
{
gtk_clipboard_request_contents (clipboard,
- gdk_atom_intern ("TEXT", FALSE),
+ gdk_atom_intern ("COMPOUND_TEXT", FALSE),
request_text_received_func, info);
return;
}
- else if (selection_data->target == gdk_atom_intern ("TEXT", FALSE))
+ else if (selection_data->target == gdk_atom_intern ("COMPOUND_TEXT", FALSE))
{
gtk_clipboard_request_contents (clipboard,
GDK_TARGET_STRING,
* 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 #GtkSelectionData object or %NULL
+ * Return value: a newly-allocated #GtkSelectionData object or %NULL
* if retrieving the given target failed. If non-%NULL,
- * this value freed with gtk_selection_data_free() when
- * you are finished with it.
+ * this value must be freed with gtk_selection_data_free()
+ * when you are finished with it.
**/
GtkSelectionData *
gtk_clipboard_wait_for_contents (GtkClipboard *clipboard,
&results);
if (g_main_is_running (results.loop))
- g_main_run (results.loop);
+ {
+ GDK_THREADS_LEAVE ();
+ g_main_run (results.loop);
+ GDK_THREADS_ENTER ();
+ }
g_main_destroy (results.loop);
* the data to be received using the main loop, so events,
* timeouts, etc, may be dispatched during the wait.
*
- * Return value: a newly allocated UTF-8 string which must
+ * Return value: a newly-allocated UTF-8 string which must
* be freed with g_free(), or %NULL if retrieving
* the selection data failed. (This could happen
* for various reasons, in particular if the
&results);
if (g_main_is_running (results.loop))
- g_main_run (results.loop);
+ {
+ GDK_THREADS_LEAVE ();
+ g_main_run (results.loop);
+ GDK_THREADS_ENTER ();
+ }
g_main_destroy (results.loop);
return results.data;
}
+/**
+ * gtk_clipboard_wait_is_text_available:
+ * @clipboard: a #GtkClipboard
+ *
+ * Test to see if there is text available to be pasted
+ * This is done by requesting the TARGETS atom and checking
+ * if it contains any of the names: STRING, TEXT, COMPOUND_TEXT,
+ * UTF8_STRING. 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_text() since it doesn't need to retrieve
+ * the actual text.
+ *
+ * Return value: %TRUE is there is text available, %FALSE otherwise.
+ **/
+gboolean
+gtk_clipboard_wait_is_text_available (GtkClipboard *clipboard)
+{
+ GtkSelectionData *data;
+ gboolean result = FALSE;
+
+ data = gtk_clipboard_wait_for_contents (clipboard, gdk_atom_intern ("TARGETS", FALSE));
+ if (data)
+ {
+ result = gtk_selection_data_targets_include_text (data);
+ gtk_selection_data_free (data);
+ }
+
+ return result;
+}
projects / ~andy / gtk / blobdiff