Clipboards
<!-- ##### SECTION Short_Description ##### -->
-Storing data on Clipboards.
+Storing data on clipboards
<!-- ##### SECTION Long_Description ##### -->
<para>
the same process. Each clipboard is identified by a name encoded as a
#GdkAtom. (Conversion to and from strings can be done with
gdk_atom_intern() and gdk_atom_name().) The default clipboard
- corresponds to the CLIPBOARD atom; another commonly used clipboard
- is the PRIMARY clipboard, which, in X, traditionally contains
- the currently selected text.
+ corresponds to the "CLIPBOARD" atom; another commonly used clipboard
+ is the "PRIMARY" clipboard, which, in X, traditionally contains
+ the currently selected text.
</para>
<para>
To support having a number of different formats on the clipboard
with callbacks to convert it into the various data types that you
advertise. When the @clear_func you provided is called, you
simply free the data blob. The latter is more useful when the
- contents of clipboard reflect the internal state of a @GObject
+ contents of clipboard reflect the internal state of a #GObject
(As an example, for the PRIMARY clipboard, when an entry widget
provides the clipboard's contents the contents are simply the
text within the selected region.) If the contents change, the
callback that will be called when the contents are received (or
when the request fails.) If you don't want to deal with providing
a separate callback, you can also use gtk_clipboard_wait_for_contents().
- What this does is run the Glib main loop recursively waiting for
+ What this does is run the GLib main loop recursively waiting for
the contents. This can simplify the code flow, but you still have
to be aware that other callbacks in your program can be called
while this recursive mainloop is running.
and converting the results into the UTF-8 encoding. (The standard
form for representing strings in GTK+.)
</para>
-
+
<!-- ##### SECTION See_Also ##### -->
<para>
<variablelist>
<varlistentry>
<term>#GtkSelection</term>
-<listitem><para>@GtkClipboard provides a high-level wrapper around the
+<listitem><para>#GtkClipboard provides a high-level wrapper around the
lower level routines that deal with X selections. It is
also possibly to directly manipulate the X selections,
though it is seldom necessary to do so.</para></listitem>
</variablelist>
</para>
+<!-- ##### SECTION Stability_Level ##### -->
+
+
+<!-- ##### SECTION Image ##### -->
+
+
<!-- ##### STRUCT GtkClipboard ##### -->
<para>
</para>
-<!-- ##### FUNCTION gtk_clipboard_get ##### -->
+<!-- ##### SIGNAL GtkClipboard::owner-change ##### -->
<para>
</para>
-@selection:
-@Returns:
+@clipboard: the object which received the signal.
+@event:
+<!-- ##### USER_FUNCTION GtkClipboardReceivedFunc ##### -->
+<para>
+ A function to be called when the results of gtk_clipboard_request_contents()
+ are received, or when the request fails.
+</para>
-<!-- ##### FUNCTION gtk_clipboard_set_with_data ##### -->
+@clipboard: the #GtkClipboard
+@selection_data: a #GtkSelectionData containing the data was received.
+ If retrieving the data failed, then then length field
+ of @selection_data will be negative.
+@data: the @user_data supplied to gtk_clipboard_request_contents().
+
+
+<!-- ##### USER_FUNCTION GtkClipboardTextReceivedFunc ##### -->
+<para>
+ A function to be called when the results of gtk_clipboard_request_text()
+ are received, or when the request fails.
+</para>
+
+@clipboard: the #GtkClipboard
+@text: the text received, as a UTF-8 encoded string, or %NULL
+ if retrieving the data failed.
+@data: the @user_data supplied to gtk_clipboard_request_text().
+
+
+<!-- ##### USER_FUNCTION GtkClipboardImageReceivedFunc ##### -->
+<para>
+ A function to be called when the results of gtk_clipboard_request_image()
+ are received, or when the request fails.
+</para>
+
+@clipboard: the #GtkClipboard
+@pixbuf: the received image
+@data: the @user_data supplied to gtk_clipboard_request_image().
+@Since: 2.6
+
+
+<!-- ##### USER_FUNCTION GtkClipboardTargetsReceivedFunc ##### -->
+<para>
+ A function to be called when the results of gtk_clipboard_request_targets()
+ are received, or when the request fails.
+</para>
+
+@clipboard: the #GtkClipboard
+@atoms: the supported targets, as array of #GdkAtom, or %NULL
+ if retrieving the data failed.
+@n_atoms: the length of the @atoms array.
+@data: the @user_data supplied to gtk_clipboard_request_targets().
+@Since: 2.4
+
+
+<!-- ##### USER_FUNCTION GtkClipboardRichTextReceivedFunc ##### -->
<para>
</para>
@clipboard:
-@targets:
-@n_targets:
-@get_func:
-@clear_func:
-@user_data:
-@Returns:
+@format:
+@text:
+@length:
+@data:
-<!-- ##### FUNCTION gtk_clipboard_set_with_owner ##### -->
+<!-- ##### USER_FUNCTION GtkClipboardURIReceivedFunc ##### -->
<para>
</para>
@clipboard:
-@targets:
-@n_targets:
-@get_func:
-@clear_func:
-@owner:
-@Returns:
+@uris:
+@data:
<!-- ##### USER_FUNCTION GtkClipboardGetFunc ##### -->
A function that will be called to provide the contents of the selection.
If multiple types of data were advertised, the requested type can
be determined from the @info parameter or by checking the target field
-of @selection_data. If the data could succesfully be converted into
+of @selection_data. If the data could successfully be converted into
then it should be stored into the @selection_data object by
calling gtk_selection_data_set() (or related functions such
-as gtk_seletion_data_get().) If no data is set, the requestor
+as gtk_selection_data_set_text()). If no data is set, the requestor
will be informed that the attempt to get the data failed.
</para>
-@clipboard: the #GtkClipboard
-@selection_data: a #GtkSelectionData argument in which the requested
- data should be stored.
-@info: the info field corresponding to the requested
+@clipboard: the #GtkClipboard
+@selection_data: a #GtkSelectionData argument in which the requested
+ data should be stored.
+@info: the info field corresponding to the requested
target from the #GtkTargetEntry array passed to
gtk_clipboard_set_with_data() or gtk_clipboard_set_with_owner().
@user_data_or_owner: the @user_data argument passed to gtk_clipboard_set_with_data(), or
- the @owner argument passed to gtk_clipboard_set_owner()
+ the @owner argument passed to gtk_clipboard_set_with_owner()
+
<!-- ##### USER_FUNCTION GtkClipboardClearFunc ##### -->
<para>
will not be used again.
</para>
-@clipboard: the #GtkClipboard
+@clipboard: the #GtkClipboard
@user_data_or_owner: the @user_data argument passed to gtk_clipboard_set_with_data(), or
- the @owner argument passed to gtk_clipboard_set_owner()
+ the @owner argument passed to gtk_clipboard_set_with_owner()
+
+
+<!-- ##### FUNCTION gtk_clipboard_get ##### -->
+<para>
+
+</para>
+
+@selection:
+@Returns:
+
+
+<!-- ##### FUNCTION gtk_clipboard_get_for_display ##### -->
+<para>
+
+</para>
+
+@display:
+@selection:
+@Returns:
+
+
+<!-- ##### FUNCTION gtk_clipboard_get_display ##### -->
+<para>
+
+</para>
+
+@clipboard:
+@Returns:
+
+
+<!-- ##### FUNCTION gtk_clipboard_set_with_data ##### -->
+<para>
+
+</para>
+
+@clipboard:
+@targets:
+@n_targets:
+@get_func:
+@clear_func:
+@user_data:
+@Returns:
+
+
+<!-- ##### FUNCTION gtk_clipboard_set_with_owner ##### -->
+<para>
+
+</para>
+
+@clipboard:
+@targets:
+@n_targets:
+@get_func:
+@clear_func:
+@owner:
+@Returns:
<!-- ##### FUNCTION gtk_clipboard_get_owner ##### -->
@len:
+<!-- ##### FUNCTION gtk_clipboard_set_image ##### -->
+<para>
+
+</para>
+
+@clipboard:
+@pixbuf:
+
+
<!-- ##### FUNCTION gtk_clipboard_request_contents ##### -->
<para>
@user_data:
-<!-- ##### USER_FUNCTION GtkClipboardReceivedFunc ##### -->
+<!-- ##### FUNCTION gtk_clipboard_request_text ##### -->
<para>
- A function to be called when the results of gtk_clipboard_request_text()
- are received, or when the request fails.
+
</para>
-@clipboard: the #GtkClipboard
-@selection_data: a #GtkSelectionData containing the data was received.
- If retrieving the data failed, then then length field
- of @selection_data will be negative.
-@data: the @user_data supplied to gtk_clipboard_request_contents().
+@clipboard:
+@callback:
+@user_data:
-<!-- ##### FUNCTION gtk_clipboard_request_text ##### -->
+<!-- ##### FUNCTION gtk_clipboard_request_image ##### -->
<para>
</para>
@user_data:
-<!-- ##### USER_FUNCTION GtkClipboardTextReceivedFunc ##### -->
+<!-- ##### FUNCTION gtk_clipboard_request_targets ##### -->
<para>
- A function to be called when the results of gtk_clipboard_request_text()
- are received, or when the request fails.
+
</para>
-@clipboard: the #GtkClipboard
-@text: the text received, as a UTF-8 encoded string, or %NULL
- if retrieving the data failed.
-@data: the @user_data supplied to gtk_clipboard_request_text().
+@clipboard:
+@callback:
+@user_data:
+
+
+<!-- ##### FUNCTION gtk_clipboard_request_rich_text ##### -->
+<para>
+
+</para>
+
+@clipboard:
+@buffer:
+@callback:
+@user_data:
+
+
+<!-- ##### FUNCTION gtk_clipboard_request_uris ##### -->
+<para>
+
+</para>
+
+@clipboard:
+@callback:
+@user_data:
<!-- ##### FUNCTION gtk_clipboard_wait_for_contents ##### -->
@Returns:
+<!-- ##### FUNCTION gtk_clipboard_wait_for_image ##### -->
+<para>
+
+</para>
+
+@clipboard:
+@Returns:
+
+
+<!-- ##### FUNCTION gtk_clipboard_wait_for_rich_text ##### -->
+<para>
+
+</para>
+
+@clipboard:
+@buffer:
+@format:
+@length:
+@Returns:
+
+
+<!-- ##### FUNCTION gtk_clipboard_wait_for_uris ##### -->
+<para>
+
+</para>
+
+@clipboard:
+@Returns:
+
+
+<!-- ##### FUNCTION gtk_clipboard_wait_is_text_available ##### -->
+<para>
+
+</para>
+
+@clipboard:
+@Returns:
+
+
+<!-- ##### FUNCTION gtk_clipboard_wait_is_image_available ##### -->
+<para>
+
+</para>
+
+@clipboard:
+@Returns:
+
+
+<!-- ##### FUNCTION gtk_clipboard_wait_is_rich_text_available ##### -->
+<para>
+
+</para>
+
+@clipboard:
+@buffer:
+@Returns:
+
+
+<!-- ##### FUNCTION gtk_clipboard_wait_is_uris_available ##### -->
+<para>
+
+</para>
+
+@clipboard:
+@Returns:
+
+
+<!-- ##### FUNCTION gtk_clipboard_wait_for_targets ##### -->
+<para>
+
+</para>
+
+@clipboard:
+@targets:
+@n_targets:
+@Returns:
+
<!--
Local variables:
mode: sgml
sgml-parent-document: ("../gtk-docs.sgml" "book" "refsect2" "")
End:
-->
+
+
+<!-- ##### FUNCTION gtk_clipboard_wait_is_target_available ##### -->
+<para>
+
+</para>
+
+@clipboard:
+@target:
+@Returns:
+
+
+<!-- ##### FUNCTION gtk_clipboard_set_can_store ##### -->
+<para>
+
+</para>
+
+@clipboard:
+@targets:
+@n_targets:
+
+
+<!-- ##### FUNCTION gtk_clipboard_store ##### -->
+<para>
+
+</para>
+
+@clipboard:
+
+