<refentry id="gtk-Clipboards">
<refmeta>
<refentrytitle>Clipboards</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GTK Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Clipboards</refname><refpurpose>Storing data on clipboards.</refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>
<synopsis>

#include &lt;gtk/gtk.h&gt;


struct      <link linkend="GtkClipboard">GtkClipboard</link>;
void        (<link linkend="GtkClipboardReceivedFunc">*GtkClipboardReceivedFunc</link>)     (<link linkend="GtkClipboard">GtkClipboard</link> *clipboard,
                                             <link linkend="GtkSelectionData">GtkSelectionData</link> *selection_data,
                                             <link linkend="gpointer">gpointer</link> data);
void        (<link linkend="GtkClipboardTextReceivedFunc">*GtkClipboardTextReceivedFunc</link>) (<link linkend="GtkClipboard">GtkClipboard</link> *clipboard,
                                             const <link linkend="gchar">gchar</link> *text,
                                             <link linkend="gpointer">gpointer</link> data);
void        (<link linkend="GtkClipboardGetFunc">*GtkClipboardGetFunc</link>)          (<link linkend="GtkClipboard">GtkClipboard</link> *clipboard,
                                             <link linkend="GtkSelectionData">GtkSelectionData</link> *selection_data,
                                             <link linkend="guint">guint</link> info,
                                             <link linkend="gpointer">gpointer</link> user_data_or_owner);
void        (<link linkend="GtkClipboardClearFunc">*GtkClipboardClearFunc</link>)        (<link linkend="GtkClipboard">GtkClipboard</link> *clipboard,
                                             <link linkend="gpointer">gpointer</link> user_data_or_owner);
<link linkend="GtkClipboard">GtkClipboard</link>* <link linkend="gtk-clipboard-get">gtk_clipboard_get</link>             (<link linkend="GdkAtom">GdkAtom</link> selection);
<link linkend="gboolean">gboolean</link>    <link linkend="gtk-clipboard-set-with-data">gtk_clipboard_set_with_data</link>     (<link linkend="GtkClipboard">GtkClipboard</link> *clipboard,
                                             const <link linkend="GtkTargetEntry">GtkTargetEntry</link> *targets,
                                             <link linkend="guint">guint</link> n_targets,
                                             <link linkend="GtkClipboardGetFunc">GtkClipboardGetFunc</link> get_func,
                                             <link linkend="GtkClipboardClearFunc">GtkClipboardClearFunc</link> clear_func,
                                             <link linkend="gpointer">gpointer</link> user_data);
<link linkend="gboolean">gboolean</link>    <link linkend="gtk-clipboard-set-with-owner">gtk_clipboard_set_with_owner</link>    (<link linkend="GtkClipboard">GtkClipboard</link> *clipboard,
                                             const <link linkend="GtkTargetEntry">GtkTargetEntry</link> *targets,
                                             <link linkend="guint">guint</link> n_targets,
                                             <link linkend="GtkClipboardGetFunc">GtkClipboardGetFunc</link> get_func,
                                             <link linkend="GtkClipboardClearFunc">GtkClipboardClearFunc</link> clear_func,
                                             <link linkend="GObject">GObject</link> *owner);
<link linkend="GObject">GObject</link>*    <link linkend="gtk-clipboard-get-owner">gtk_clipboard_get_owner</link>         (<link linkend="GtkClipboard">GtkClipboard</link> *clipboard);
void        <link linkend="gtk-clipboard-clear">gtk_clipboard_clear</link>             (<link linkend="GtkClipboard">GtkClipboard</link> *clipboard);
void        <link linkend="gtk-clipboard-set-text">gtk_clipboard_set_text</link>          (<link linkend="GtkClipboard">GtkClipboard</link> *clipboard,
                                             const <link linkend="gchar">gchar</link> *text,
                                             <link linkend="gint">gint</link> len);
void        <link linkend="gtk-clipboard-request-contents">gtk_clipboard_request_contents</link>  (<link linkend="GtkClipboard">GtkClipboard</link> *clipboard,
                                             <link linkend="GdkAtom">GdkAtom</link> target,
                                             <link linkend="GtkClipboardReceivedFunc">GtkClipboardReceivedFunc</link> callback,
                                             <link linkend="gpointer">gpointer</link> user_data);
void        <link linkend="gtk-clipboard-request-text">gtk_clipboard_request_text</link>      (<link linkend="GtkClipboard">GtkClipboard</link> *clipboard,
                                             <link linkend="GtkClipboardTextReceivedFunc">GtkClipboardTextReceivedFunc</link> callback,
                                             <link linkend="gpointer">gpointer</link> user_data);
<link linkend="GtkSelectionData">GtkSelectionData</link>* <link linkend="gtk-clipboard-wait-for-contents">gtk_clipboard_wait_for_contents</link>
                                            (<link linkend="GtkClipboard">GtkClipboard</link> *clipboard,
                                             <link linkend="GdkAtom">GdkAtom</link> target);
<link linkend="gchar">gchar</link>*      <link linkend="gtk-clipboard-wait-for-text">gtk_clipboard_wait_for_text</link>     (<link linkend="GtkClipboard">GtkClipboard</link> *clipboard);
<link linkend="gboolean">gboolean</link>    <link linkend="gtk-clipboard-wait-is-text-available">gtk_clipboard_wait_is_text_available</link>
                                            (<link linkend="GtkClipboard">GtkClipboard</link> *clipboard);
</synopsis>
</refsynopsisdiv>





<refsect1>
<title>Description</title>
  <para>
    The <link linkend="GtkClipboard">GtkClipboard</link> object represents a clipboard of data shared
    between different processes or between different widgets in
    the same process. Each clipboard is identified by a name encoded as a
    <link linkend="GdkAtom">GdkAtom</link>. (Conversion to and from strings can be done with
    <link linkend="gdk-atom-intern">gdk_atom_intern</link>() and <link linkend="gdk-atom-name">gdk_atom_name</link>().) 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.
  </para>
  <para>
    To support having a number of different formats on the clipboard
    at the same time, the clipboard mechanism allows providing
    callbacks instead of the actual data.  When you set the contents
    of the clipboard, you can either supply the data directly (via
    functions like <link linkend="gtk-clipboard-set-text">gtk_clipboard_set_text</link>()), or you can supply a
    callback to be called at a later time when the data is needed (via
    <link linkend="gtk-clipboard-set-with-data">gtk_clipboard_set_with_data</link>() or <link linkend="gtk-clipboard-set-with-owner">gtk_clipboard_set_with_owner</link>().)
    Providing a callback also avoids having to make copies of the data
    when it is not needed.
  </para>
  <para>
    <link linkend="gtk-clipboard-set-with-data">gtk_clipboard_set_with_data</link>() and <link linkend="gtk-clipboard-set-with-owner">gtk_clipboard_set_with_owner</link>()
    are quite similar; the choice between the two depends mostly on
    which is more convenient in a particular situation.
    The former is most useful when you want to have a blob of data
    with callbacks to convert it into the various data types that you
    advertise. When the <parameter>clear_func</parameter> 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 <link linkend="GObject">GObject</link>
    (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
    entry widget can call <link linkend="gtk-clipboard-set-with-owner">gtk_clipboard_set_with_owner</link>() to update
    the timestamp for clipboard ownership, without having to worry
    about <parameter>clear_func</parameter> being called.
  </para>
  <para>
    Requesting the data from the clipboard is essentially
    asynchronous. If the contents of the clipboard are provided within
    the same process, then a direct function call will be made to
    retrieve the data, but if they are provided by another process,
    then the data needs to be retrieved from the other process, which
    may take some time. To avoid blocking the user interface, the call
    to request the selection, <link linkend="gtk-clipboard-request-contents">gtk_clipboard_request_contents</link>() takes a
    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 <link linkend="gtk-clipboard-wait-for-contents">gtk_clipboard_wait_for_contents</link>().
    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.
  </para>
  <para>
    Along with the functions to get the clipboard contents as an
    arbitrary data chunk, there are also functions to retrieve
    it as text, <link linkend="gtk-clipboard-request-text">gtk_clipboard_request_text</link>() and
    <link linkend="gtk-clipboard-wait-for-text">gtk_clipboard_wait_for_text</link>(). These functions take care of
    determining which formats are advertised by the clipboard
    provider, asking for the clipboard in the best available format
    and converting the results into the UTF-8 encoding. (The standard
    form for representing strings in GTK+.)
  </para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="GtkClipboard">struct GtkClipboard</title>
<programlisting>struct GtkClipboard;</programlisting>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="GtkClipboardReceivedFunc">GtkClipboardReceivedFunc ()</title>
<programlisting>void        (*GtkClipboardReceivedFunc)     (<link linkend="GtkClipboard">GtkClipboard</link> *clipboard,
                                             <link linkend="GtkSelectionData">GtkSelectionData</link> *selection_data,
                                             <link linkend="gpointer">gpointer</link> data);</programlisting>
<para>
    A function to be called when the results of <link linkend="gtk-clipboard-request-contents">gtk_clipboard_request_contents</link>()
    are received, or when the request fails.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>clipboard</parameter>&nbsp;:</entry>
<entry>the <link linkend="GtkClipboard">GtkClipboard</link>
</entry></row>
<row><entry align="right"><parameter>selection_data</parameter>&nbsp;:</entry>
<entry>a <link linkend="GtkSelectionData">GtkSelectionData</link> containing the data was received.
                 If retrieving the data failed, then then length field
                 of <parameter>selection_data</parameter> will be negative.
</entry></row>
<row><entry align="right"><parameter>data</parameter>&nbsp;:</entry>
<entry>the <parameter>user_data</parameter> supplied to <link linkend="gtk-clipboard-request-contents">gtk_clipboard_request_contents</link>().


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GtkClipboardTextReceivedFunc">GtkClipboardTextReceivedFunc ()</title>
<programlisting>void        (*GtkClipboardTextReceivedFunc) (<link linkend="GtkClipboard">GtkClipboard</link> *clipboard,
                                             const <link linkend="gchar">gchar</link> *text,
                                             <link linkend="gpointer">gpointer</link> data);</programlisting>
<para>
    A function to be called when the results of <link linkend="gtk-clipboard-request-text">gtk_clipboard_request_text</link>()
    are received, or when the request fails.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>clipboard</parameter>&nbsp;:</entry>
<entry>the <link linkend="GtkClipboard">GtkClipboard</link>
</entry></row>
<row><entry align="right"><parameter>text</parameter>&nbsp;:</entry>
<entry>the text received, as a UTF-8 encoded string, or <literal>NULL</literal>
            if retrieving the data failed.
</entry></row>
<row><entry align="right"><parameter>data</parameter>&nbsp;:</entry>
<entry>the <parameter>user_data</parameter> supplied to <link linkend="gtk-clipboard-request-text">gtk_clipboard_request_text</link>().


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GtkClipboardGetFunc">GtkClipboardGetFunc ()</title>
<programlisting>void        (*GtkClipboardGetFunc)          (<link linkend="GtkClipboard">GtkClipboard</link> *clipboard,
                                             <link linkend="GtkSelectionData">GtkSelectionData</link> *selection_data,
                                             <link linkend="guint">guint</link> info,
                                             <link linkend="gpointer">gpointer</link> user_data_or_owner);</programlisting>
<para>
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 <parameter>info</parameter> parameter or by checking the target field
of <parameter>selection_data</parameter>. If the data could successfully be converted into
then it should be stored into the <parameter>selection_data</parameter> object by
calling <link linkend="gtk-selection-data-set">gtk_selection_data_set</link>() (or related functions such
as <link linkend="gtk-selection-data-set-text">gtk_selection_data_set_text</link>()). If no data is set, the requestor
will be informed that the attempt to get the data failed.    
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>clipboard</parameter>&nbsp;:</entry>
<entry>the <link linkend="GtkClipboard">GtkClipboard</link>
</entry></row>
<row><entry align="right"><parameter>selection_data</parameter>&nbsp;:</entry>
<entry>a <link linkend="GtkSelectionData">GtkSelectionData</link> argument in which the requested
                     data should be stored.
</entry></row>
<row><entry align="right"><parameter>info</parameter>&nbsp;:</entry>
<entry>the info field corresponding to the requested
                     target from the <link linkend="GtkTargetEntry">GtkTargetEntry</link> array passed to
                     <link linkend="gtk-clipboard-set-with-data">gtk_clipboard_set_with_data</link>() or <link linkend="gtk-clipboard-set-with-owner">gtk_clipboard_set_with_owner</link>().
</entry></row>
<row><entry align="right"><parameter>user_data_or_owner</parameter>&nbsp;:</entry>
<entry>the <parameter>user_data</parameter> argument passed to <link linkend="gtk-clipboard-set-with-data">gtk_clipboard_set_with_data</link>(), or
                     the <parameter>owner</parameter> argument passed to <link linkend="gtk-clipboard-set-with-owner">gtk_clipboard_set_with_owner</link>()


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GtkClipboardClearFunc">GtkClipboardClearFunc ()</title>
<programlisting>void        (*GtkClipboardClearFunc)        (<link linkend="GtkClipboard">GtkClipboard</link> *clipboard,
                                             <link linkend="gpointer">gpointer</link> user_data_or_owner);</programlisting>
<para>
A function that will be called when the contents of the clipboard are changed
or cleared. Once this has called, the <parameter>user_data_or_owner</parameter> argument
will not be used again.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>clipboard</parameter>&nbsp;:</entry>
<entry>the <link linkend="GtkClipboard">GtkClipboard</link>
</entry></row>
<row><entry align="right"><parameter>user_data_or_owner</parameter>&nbsp;:</entry>
<entry>the <parameter>user_data</parameter> argument passed to <link linkend="gtk-clipboard-set-with-data">gtk_clipboard_set_with_data</link>(), or
                     the <parameter>owner</parameter> argument passed to <link linkend="gtk-clipboard-set-with-owner">gtk_clipboard_set_with_owner</link>()


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-clipboard-get">gtk_clipboard_get ()</title>
<programlisting><link linkend="GtkClipboard">GtkClipboard</link>* gtk_clipboard_get             (<link linkend="GdkAtom">GdkAtom</link> selection);</programlisting>
<para>
Returns the clipboard object for the given selection.
Cut/copy/paste menu items and keyboard shortcuts should use
the default clipboard, returned by passing <link linkend="GDK-NONE-CAPS">GDK_NONE</link> for <parameter>selection</parameter>.
The currently-selected object or text should be provided on the clipboard
identified by <link linkend="GDK-SELECTION-PRIMARY-CAPS">GDK_SELECTION_PRIMARY</link>. Cut/copy/paste menu items
conceptually copy the contents of the <link linkend="GDK-SELECTION-PRIMARY-CAPS">GDK_SELECTION_PRIMARY</link> clipboard
to the default clipboard, i.e. they copy the selection to what the
user sees as the clipboard.
</para>
<para>
(Passing <link linkend="GDK-NONE-CAPS">GDK_NONE</link> 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 <link linkend="GDK-SELECTION-PRIMARY-CAPS">GDK_SELECTION_PRIMARY</link>
clipboard is essentially ignored.)
</para>
<para>
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".</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>selection</parameter>&nbsp;:</entry>
<entry> a <link linkend="GdkAtom">GdkAtom</link> which identifies the clipboard
            to use.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> the appropriate clipboard object. If no
            clipboard already exists, a new one will
            be created. Once a clipboard object has
            been created, it is persistent for all time and
            cannot be freed.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-clipboard-set-with-data">gtk_clipboard_set_with_data ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    gtk_clipboard_set_with_data     (<link linkend="GtkClipboard">GtkClipboard</link> *clipboard,
                                             const <link linkend="GtkTargetEntry">GtkTargetEntry</link> *targets,
                                             <link linkend="guint">guint</link> n_targets,
                                             <link linkend="GtkClipboardGetFunc">GtkClipboardGetFunc</link> get_func,
                                             <link linkend="GtkClipboardClearFunc">GtkClipboardClearFunc</link> clear_func,
                                             <link linkend="gpointer">gpointer</link> user_data);</programlisting>
<para>
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.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>clipboard</parameter>&nbsp;:</entry>
<entry>  a <link linkend="GtkClipboard">GtkClipboard</link>
</entry></row>
<row><entry align="right"><parameter>targets</parameter>&nbsp;:</entry>
<entry>    array containing information about the available forms for the
             clipboard data
</entry></row>
<row><entry align="right"><parameter>n_targets</parameter>&nbsp;:</entry>
<entry>  number of elements in <parameter>targets</parameter>
</entry></row>
<row><entry align="right"><parameter>get_func</parameter>&nbsp;:</entry>
<entry>   function to call to get the actual clipboard data
</entry></row>
<row><entry align="right"><parameter>clear_func</parameter>&nbsp;:</entry>
<entry> when the clipboard contents are set again, this function will
             be called, and <parameter>get_func</parameter> will not be subsequently called.
</entry></row>
<row><entry align="right"><parameter>user_data</parameter>&nbsp;:</entry>
<entry>  user data to pass to <parameter>get_func</parameter> and <parameter>clear_func</parameter>.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> <literal>TRUE</literal> if setting the clipboard data succeeded. If setting
              the clipboard data failed the provided callback functions
              will be ignored.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-clipboard-set-with-owner">gtk_clipboard_set_with_owner ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    gtk_clipboard_set_with_owner    (<link linkend="GtkClipboard">GtkClipboard</link> *clipboard,
                                             const <link linkend="GtkTargetEntry">GtkTargetEntry</link> *targets,
                                             <link linkend="guint">guint</link> n_targets,
                                             <link linkend="GtkClipboardGetFunc">GtkClipboardGetFunc</link> get_func,
                                             <link linkend="GtkClipboardClearFunc">GtkClipboardClearFunc</link> clear_func,
                                             <link linkend="GObject">GObject</link> *owner);</programlisting>
<para>
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.
</para>
<para>
The difference between this function and <link linkend="gtk-clipboard-set-with-data">gtk_clipboard_set_with_data</link>()
is that instead of an generic <parameter>user_data</parameter> pointer, a <link linkend="GObject">GObject</link> is passed
in.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>clipboard</parameter>&nbsp;:</entry>
<entry>  a <link linkend="GtkClipboard">GtkClipboard</link>
</entry></row>
<row><entry align="right"><parameter>targets</parameter>&nbsp;:</entry>
<entry>    array containing information about the available forms for the
             clipboard data
</entry></row>
<row><entry align="right"><parameter>n_targets</parameter>&nbsp;:</entry>
<entry>  number of elements in <parameter>targets</parameter>
</entry></row>
<row><entry align="right"><parameter>get_func</parameter>&nbsp;:</entry>
<entry>   function to call to get the actual clipboard data
</entry></row>
<row><entry align="right"><parameter>clear_func</parameter>&nbsp;:</entry>
<entry> when the clipboard contents are set again, this function will
             be called, and <parameter>get_func</parameter> will not be subsequently called.
</entry></row>
<row><entry align="right"><parameter>owner</parameter>&nbsp;:</entry>
<entry>      an object that "owns" the data. This object will be passed
             to the callbacks when called. 
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> <literal>TRUE</literal> if setting the clipboard data succeeded. If setting
              the clipboard data failed the provided callback functions
              will be ignored.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-clipboard-get-owner">gtk_clipboard_get_owner ()</title>
<programlisting><link linkend="GObject">GObject</link>*    gtk_clipboard_get_owner         (<link linkend="GtkClipboard">GtkClipboard</link> *clipboard);</programlisting>
<para>
If the clipboard contents callbacks were set with 
<link linkend="gtk-clipboard-set-with-owner">gtk_clipboard_set_with_owner</link>(), and the <link linkend="gtk-clipboard-set-with-data">gtk_clipboard_set_with_data</link>() or 
<link linkend="gtk-clipboard-clear">gtk_clipboard_clear</link>() has not subsequently called, returns the owner set 
by <link linkend="gtk-clipboard-set-with-owner">gtk_clipboard_set_with_owner</link>().</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>clipboard</parameter>&nbsp;:</entry>
<entry> a <link linkend="GtkClipboard">GtkClipboard</link>
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> the owner of the clipboard, if any; otherwise <literal>NULL</literal>.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-clipboard-clear">gtk_clipboard_clear ()</title>
<programlisting>void        gtk_clipboard_clear             (<link linkend="GtkClipboard">GtkClipboard</link> *clipboard);</programlisting>
<para>
Clears the contents of the clipboard. Generally this should only
be called between the time you call <link linkend="gtk-clipboard-set-with-owner">gtk_clipboard_set_with_owner</link>()
or <link linkend="gtk-clipboard-set-with-data">gtk_clipboard_set_with_data</link>(),
and when the <parameter>clear_func</parameter> you supplied is called. Otherwise, the
clipboard may be owned by someone else.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>clipboard</parameter>&nbsp;:</entry>
<entry>  a <link linkend="GtkClipboard">GtkClipboard</link>
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-clipboard-set-text">gtk_clipboard_set_text ()</title>
<programlisting>void        gtk_clipboard_set_text          (<link linkend="GtkClipboard">GtkClipboard</link> *clipboard,
                                             const <link linkend="gchar">gchar</link> *text,
                                             <link linkend="gint">gint</link> len);</programlisting>
<para>
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.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>clipboard</parameter>&nbsp;:</entry>
<entry> a <link linkend="GtkClipboard">GtkClipboard</link> object
</entry></row>
<row><entry align="right"><parameter>text</parameter>&nbsp;:</entry>
<entry>      a UTF-8 string.
</entry></row>
<row><entry align="right"><parameter>len</parameter>&nbsp;:</entry>
<entry>       length of <parameter>text</parameter>, in bytes, or -1, in which case
            the length will be determined with <function><link linkend="strlen">strlen</link>()</function>.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-clipboard-request-contents">gtk_clipboard_request_contents ()</title>
<programlisting>void        gtk_clipboard_request_contents  (<link linkend="GtkClipboard">GtkClipboard</link> *clipboard,
                                             <link linkend="GdkAtom">GdkAtom</link> target,
                                             <link linkend="GtkClipboardReceivedFunc">GtkClipboardReceivedFunc</link> callback,
                                             <link linkend="gpointer">gpointer</link> user_data);</programlisting>
<para>
Requests the contents of clipboard as the given target.
When the results of the result are later received the supplied callback
will be called.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>clipboard</parameter>&nbsp;:</entry>
<entry> a <link linkend="GtkClipboard">GtkClipboard</link>
</entry></row>
<row><entry align="right"><parameter>target</parameter>&nbsp;:</entry>
<entry>    an atom representing the form into which the clipboard
            owner should convert the selection.
</entry></row>
<row><entry align="right"><parameter>callback</parameter>&nbsp;:</entry>
<entry>  A function to call when the results are received
            (or the retrieval fails). If the retrieval fails
            the length field of <parameter>selection_data</parameter> will be
            negative.
</entry></row>
<row><entry align="right"><parameter>user_data</parameter>&nbsp;:</entry>
<entry> user data to pass to <parameter>callback</parameter>
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-clipboard-request-text">gtk_clipboard_request_text ()</title>
<programlisting>void        gtk_clipboard_request_text      (<link linkend="GtkClipboard">GtkClipboard</link> *clipboard,
                                             <link linkend="GtkClipboardTextReceivedFunc">GtkClipboardTextReceivedFunc</link> callback,
                                             <link linkend="gpointer">gpointer</link> user_data);</programlisting>
<para>
Requests the contents of the clipboard as text. When the text is
later received, it will be converted to UTF-8 if necessary, and
<parameter>callback</parameter> will be called. 
</para>
<para>
The <parameter>text</parameter> parameter to <parameter>callback</parameter> will contain the resulting text if
the request succeeded, or <literal>NULL</literal> 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 text form.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>clipboard</parameter>&nbsp;:</entry>
<entry> a <link linkend="GtkClipboard">GtkClipboard</link>
</entry></row>
<row><entry align="right"><parameter>callback</parameter>&nbsp;:</entry>
<entry>  a function to call when the text is received,
            or the retrieval fails. (It will always be called
            one way or the other.)
</entry></row>
<row><entry align="right"><parameter>user_data</parameter>&nbsp;:</entry>
<entry> user data to pass to <parameter>callback</parameter>.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-clipboard-wait-for-contents">gtk_clipboard_wait_for_contents ()</title>
<programlisting><link linkend="GtkSelectionData">GtkSelectionData</link>* gtk_clipboard_wait_for_contents
                                            (<link linkend="GtkClipboard">GtkClipboard</link> *clipboard,
                                             <link linkend="GdkAtom">GdkAtom</link> target);</programlisting>
<para>
Requests the contents of the clipboard using the given target.
This function waits for the data to be received using the main 
loop, so events, timeouts, etc, may be dispatched during the wait.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>clipboard</parameter>&nbsp;:</entry>
<entry> a <link linkend="GtkClipboard">GtkClipboard</link>
</entry></row>
<row><entry align="right"><parameter>target</parameter>&nbsp;:</entry>
<entry> an atom representing the form into which the clipboard
         owner should convert the selection.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> a newly-allocated <link linkend="GtkSelectionData">GtkSelectionData</link> object or <literal>NULL</literal>
              if retrieving the given target failed. If non-<literal>NULL</literal>,
              this value must be freed with <link linkend="gtk-selection-data-free">gtk_selection_data_free</link>() 
              when you are finished with it.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-clipboard-wait-for-text">gtk_clipboard_wait_for_text ()</title>
<programlisting><link linkend="gchar">gchar</link>*      gtk_clipboard_wait_for_text     (<link linkend="GtkClipboard">GtkClipboard</link> *clipboard);</programlisting>
<para>
Requests the contents of the clipboard as text and converts
the result to UTF-8 if necessary. This function waits for
the data to be received using the main loop, so events,
timeouts, etc, may be dispatched during the wait.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>clipboard</parameter>&nbsp;:</entry>
<entry> a <link linkend="GtkClipboard">GtkClipboard</link>
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> a newly-allocated UTF-8 string which must
              be freed with <link linkend="g-free">g_free</link>(), or <literal>NULL</literal> 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 text form.)
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-clipboard-wait-is-text-available">gtk_clipboard_wait_is_text_available ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    gtk_clipboard_wait_is_text_available
                                            (<link linkend="GtkClipboard">GtkClipboard</link> *clipboard);</programlisting>
<para>
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.
</para>
<para>
This function is a little faster than calling
<link linkend="gtk-clipboard-wait-for-text">gtk_clipboard_wait_for_text</link>() since it doesn't need to retrieve
the actual text.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>clipboard</parameter>&nbsp;:</entry>
<entry> a <link linkend="GtkClipboard">GtkClipboard</link>
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> <literal>TRUE</literal> is there is text available, <literal>FALSE</literal> otherwise.
</entry></row>
</tbody></tgroup></informaltable></refsect2>

</refsect1>



<refsect1>
<title>See Also</title>
<para>
<variablelist>

<varlistentry>
<term><link linkend="GtkSelection">GtkSelection</link></term>
<listitem><para><link linkend="GtkClipboard">GtkClipboard</link> 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>
</varlistentry>

</variablelist>
</para>
</refsect1>

</refentry>
