<refentry id="gdk-Selections">
<refmeta>
<refentrytitle>Selections</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GDK Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Selections</refname><refpurpose>functions for transfering data via the X selection mechanism.</refpurpose>
</refnamediv>

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

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


typedef     <link linkend="GdkSelection">GdkSelection</link>;
typedef     <link linkend="GdkSelectionType">GdkSelectionType</link>;
typedef     <link linkend="GdkTarget">GdkTarget</link>;
#define     <link linkend="GDK-SELECTION-PRIMARY-CAPS">GDK_SELECTION_PRIMARY</link>
#define     <link linkend="GDK-SELECTION-SECONDARY-CAPS">GDK_SELECTION_SECONDARY</link>
#define     <link linkend="GDK-SELECTION-CLIPBOARD-CAPS">GDK_SELECTION_CLIPBOARD</link>
#define     <link linkend="GDK-TARGET-BITMAP-CAPS">GDK_TARGET_BITMAP</link>
#define     <link linkend="GDK-TARGET-COLORMAP-CAPS">GDK_TARGET_COLORMAP</link>
#define     <link linkend="GDK-TARGET-DRAWABLE-CAPS">GDK_TARGET_DRAWABLE</link>
#define     <link linkend="GDK-TARGET-PIXMAP-CAPS">GDK_TARGET_PIXMAP</link>
#define     <link linkend="GDK-TARGET-STRING-CAPS">GDK_TARGET_STRING</link>
#define     <link linkend="GDK-SELECTION-TYPE-ATOM-CAPS">GDK_SELECTION_TYPE_ATOM</link>
#define     <link linkend="GDK-SELECTION-TYPE-BITMAP-CAPS">GDK_SELECTION_TYPE_BITMAP</link>
#define     <link linkend="GDK-SELECTION-TYPE-COLORMAP-CAPS">GDK_SELECTION_TYPE_COLORMAP</link>
#define     <link linkend="GDK-SELECTION-TYPE-DRAWABLE-CAPS">GDK_SELECTION_TYPE_DRAWABLE</link>
#define     <link linkend="GDK-SELECTION-TYPE-INTEGER-CAPS">GDK_SELECTION_TYPE_INTEGER</link>
#define     <link linkend="GDK-SELECTION-TYPE-PIXMAP-CAPS">GDK_SELECTION_TYPE_PIXMAP</link>
#define     <link linkend="GDK-SELECTION-TYPE-WINDOW-CAPS">GDK_SELECTION_TYPE_WINDOW</link>
#define     <link linkend="GDK-SELECTION-TYPE-STRING-CAPS">GDK_SELECTION_TYPE_STRING</link>
<link linkend="gboolean">gboolean</link>    <link linkend="gdk-selection-owner-set">gdk_selection_owner_set</link>         (<link linkend="GdkWindow">GdkWindow</link> *owner,
                                             <link linkend="GdkAtom">GdkAtom</link> selection,
                                             <link linkend="guint32">guint32</link> time,
                                             <link linkend="gboolean">gboolean</link> send_event);
<link linkend="GdkWindow">GdkWindow</link>*  <link linkend="gdk-selection-owner-get">gdk_selection_owner_get</link>         (<link linkend="GdkAtom">GdkAtom</link> selection);
void        <link linkend="gdk-selection-convert">gdk_selection_convert</link>           (<link linkend="GdkWindow">GdkWindow</link> *requestor,
                                             <link linkend="GdkAtom">GdkAtom</link> selection,
                                             <link linkend="GdkAtom">GdkAtom</link> target,
                                             <link linkend="guint32">guint32</link> time);
<link linkend="gboolean">gboolean</link>    <link linkend="gdk-selection-property-get">gdk_selection_property_get</link>      (<link linkend="GdkWindow">GdkWindow</link> *requestor,
                                             <link linkend="guchar">guchar</link> **data,
                                             <link linkend="GdkAtom">GdkAtom</link> *prop_type,
                                             <link linkend="gint">gint</link> *prop_format);
void        <link linkend="gdk-selection-send-notify">gdk_selection_send_notify</link>       (<link linkend="guint32">guint32</link> requestor,
                                             <link linkend="GdkAtom">GdkAtom</link> selection,
                                             <link linkend="GdkAtom">GdkAtom</link> target,
                                             <link linkend="GdkAtom">GdkAtom</link> property,
                                             <link linkend="guint32">guint32</link> time);
</synopsis>
</refsynopsisdiv>





<refsect1>
<title>Description</title>
<para>
The X selection mechanism provides a way to transfer
arbitrary chunks of data between programs. 
A <firstterm>selection</firstterm> is a essentially 
a named clipboard, identified by a string interned
as a <link linkend="GdkAtom">GdkAtom</link>. By claiming ownership of a selection,
an application indicates that it will be responsible
for supplying its contents. The most common 
selections are <literal>PRIMARY</literal> and 
<literal>CLIPBOARD</literal>.
</para>
<para>
The contents of a selection can be represented in
a number of formats, called <firstterm>targets</firstterm>.
Each target is identified by an atom. A list of
all possible targets supported by the selection owner
can be retrieved by requesting the special target
<literal>TARGETS</literal>. When a selection is 
retrieved, the data is accompanied by a type
(an atom), and a format (an integer, representing
the number of bits per item).
See <link linkend="gdk-Properties-and-Atoms">Properties and Atoms</link>
for more information.
</para>
<para>
The functions in this section only contain the lowlevel
parts of the selection protocol. A considerably more
complicated implementation is needed on top of this.
GTK+ contains such an implementation in the functions
in <literal>gtkselection.h</literal> and programmers
should use those functions instead of the ones presented 
here. If you plan to implement selection handling
directly on top of the functions here, you should refer
to the X Inter-client Communication Conventions Manual
(ICCCM).
</para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="GdkSelection">GdkSelection</title>
<programlisting>typedef GdkAtom GdkSelection;
</programlisting>
<warning>
<para>
<literal>GdkSelection</literal> is deprecated and should not be used in newly-written code.
</para>
</warning>
<para>
The <link linkend="GdkSelection">GdkSelection</link> enumeration contains predefined 
atom values for several common selections.
</para></refsect2>
<refsect2>
<title><anchor id="GdkSelectionType">GdkSelectionType</title>
<programlisting>typedef GdkAtom GdkSelectionType;
</programlisting>
<warning>
<para>
<literal>GdkSelectionType</literal> is deprecated and should not be used in newly-written code.
</para>
</warning>
<para>
The <link linkend="GdkSelectionType">GdkSelectionType</link> enumeration contains predefined
atom values used to represent the types of data transferred
in response to a request for a target. See the
ICCCM for details about what data should be transferred
for each of these types. Other atoms can be used,
and the recommended practice for GTK+ is to to use mime 
types for this purpose. However, supporting these types
may be useful for compatibility with older programs.
</para></refsect2>
<refsect2>
<title><anchor id="GdkTarget">GdkTarget</title>
<programlisting>typedef GdkAtom GdkTarget;
</programlisting>
<warning>
<para>
<literal>GdkTarget</literal> is deprecated and should not be used in newly-written code.
</para>
</warning>
<para>
The <link linkend="GdkTarget">GdkTarget</link> enumeration contains predefined atom values which are
used to describe possible targets for a selection. Other atoms can be
used, and the recommended practice for GTK+ is to to use mime types
for this purpose. However, supporting these types may be useful for
compatibility with older programs.
</para></refsect2>
<refsect2>
<title><anchor id="GDK-SELECTION-PRIMARY-CAPS">GDK_SELECTION_PRIMARY</title>
<programlisting>#define GDK_SELECTION_PRIMARY 		_GDK_MAKE_ATOM (1)
</programlisting>
<para>
A <link linkend="GdkAtom">GdkAtom</link> representing the <literal>PRIMARY</literal> selection.
</para></refsect2>
<refsect2>
<title><anchor id="GDK-SELECTION-SECONDARY-CAPS">GDK_SELECTION_SECONDARY</title>
<programlisting>#define GDK_SELECTION_SECONDARY 	_GDK_MAKE_ATOM (2)
</programlisting>
<para>
A <link linkend="GdkAtom">GdkAtom</link> representing the <literal>SECONDARY</literal> selection.
</para></refsect2>
<refsect2>
<title><anchor id="GDK-SELECTION-CLIPBOARD-CAPS">GDK_SELECTION_CLIPBOARD</title>
<programlisting>#define GDK_SELECTION_CLIPBOARD 	_GDK_MAKE_ATOM (69)
</programlisting>
<para>
A <link linkend="GdkAtom">GdkAtom</link> representing the <literal>CLIPBOARD</literal> selection.
</para></refsect2>
<refsect2>
<title><anchor id="GDK-TARGET-BITMAP-CAPS">GDK_TARGET_BITMAP</title>
<programlisting>#define GDK_TARGET_BITMAP 		_GDK_MAKE_ATOM (5)
</programlisting>
<para>
A <link linkend="GdkAtom">GdkAtom</link> representing the <literal>BITMAP</literal> selection target.
</para></refsect2>
<refsect2>
<title><anchor id="GDK-TARGET-COLORMAP-CAPS">GDK_TARGET_COLORMAP</title>
<programlisting>#define GDK_TARGET_COLORMAP 		_GDK_MAKE_ATOM (7)
</programlisting>
<para>
A <link linkend="GdkAtom">GdkAtom</link> representing the <literal>COLORMAP</literal> selection target.
</para></refsect2>
<refsect2>
<title><anchor id="GDK-TARGET-DRAWABLE-CAPS">GDK_TARGET_DRAWABLE</title>
<programlisting>#define GDK_TARGET_DRAWABLE 		_GDK_MAKE_ATOM (17)
</programlisting>
<para>
A <link linkend="GdkAtom">GdkAtom</link> representing the <literal>DRAWABLE</literal> selection target.
</para></refsect2>
<refsect2>
<title><anchor id="GDK-TARGET-PIXMAP-CAPS">GDK_TARGET_PIXMAP</title>
<programlisting>#define GDK_TARGET_PIXMAP 		_GDK_MAKE_ATOM (20)
</programlisting>
<para>
A <link linkend="GdkAtom">GdkAtom</link> representing the <literal>PIXMAP</literal> selection target.
</para></refsect2>
<refsect2>
<title><anchor id="GDK-TARGET-STRING-CAPS">GDK_TARGET_STRING</title>
<programlisting>#define GDK_TARGET_STRING 		_GDK_MAKE_ATOM (31)
</programlisting>
<para>
A <link linkend="GdkAtom">GdkAtom</link> representing the <literal>STRING</literal> selection target.
</para></refsect2>
<refsect2>
<title><anchor id="GDK-SELECTION-TYPE-ATOM-CAPS">GDK_SELECTION_TYPE_ATOM</title>
<programlisting>#define GDK_SELECTION_TYPE_ATOM 	_GDK_MAKE_ATOM (4)
</programlisting>
<para>
A <link linkend="GdkAtom">GdkAtom</link> representing the <literal>ATOM</literal> selection type.
</para></refsect2>
<refsect2>
<title><anchor id="GDK-SELECTION-TYPE-BITMAP-CAPS">GDK_SELECTION_TYPE_BITMAP</title>
<programlisting>#define GDK_SELECTION_TYPE_BITMAP 	_GDK_MAKE_ATOM (5)
</programlisting>
<para>
A <link linkend="GdkAtom">GdkAtom</link> representing the <literal>BITMAP</literal> selection type.
</para></refsect2>
<refsect2>
<title><anchor id="GDK-SELECTION-TYPE-COLORMAP-CAPS">GDK_SELECTION_TYPE_COLORMAP</title>
<programlisting>#define GDK_SELECTION_TYPE_COLORMAP 	_GDK_MAKE_ATOM (7)
</programlisting>
<para>
A <link linkend="GdkAtom">GdkAtom</link> representing the <literal>COLORMAP</literal> selection type.
</para></refsect2>
<refsect2>
<title><anchor id="GDK-SELECTION-TYPE-DRAWABLE-CAPS">GDK_SELECTION_TYPE_DRAWABLE</title>
<programlisting>#define GDK_SELECTION_TYPE_DRAWABLE 	_GDK_MAKE_ATOM (17)
</programlisting>
<para>
A <link linkend="GdkAtom">GdkAtom</link> representing the <literal>DRAWABLE</literal> selection type.
</para></refsect2>
<refsect2>
<title><anchor id="GDK-SELECTION-TYPE-INTEGER-CAPS">GDK_SELECTION_TYPE_INTEGER</title>
<programlisting>#define GDK_SELECTION_TYPE_INTEGER 	_GDK_MAKE_ATOM (19)
</programlisting>
<para>
A <link linkend="GdkAtom">GdkAtom</link> representing the <literal>INTEGER</literal> selection type.
</para></refsect2>
<refsect2>
<title><anchor id="GDK-SELECTION-TYPE-PIXMAP-CAPS">GDK_SELECTION_TYPE_PIXMAP</title>
<programlisting>#define GDK_SELECTION_TYPE_PIXMAP 	_GDK_MAKE_ATOM (20)
</programlisting>
<para>
A <link linkend="GdkAtom">GdkAtom</link> representing the <literal>PIXMAP</literal> selection type.
</para></refsect2>
<refsect2>
<title><anchor id="GDK-SELECTION-TYPE-WINDOW-CAPS">GDK_SELECTION_TYPE_WINDOW</title>
<programlisting>#define GDK_SELECTION_TYPE_WINDOW 	_GDK_MAKE_ATOM (33)
</programlisting>
<para>
A <link linkend="GdkAtom">GdkAtom</link> representing the <literal>WINDOW</literal> selection type.
</para></refsect2>
<refsect2>
<title><anchor id="GDK-SELECTION-TYPE-STRING-CAPS">GDK_SELECTION_TYPE_STRING</title>
<programlisting>#define GDK_SELECTION_TYPE_STRING 	_GDK_MAKE_ATOM (31)
</programlisting>
<para>
A <link linkend="GdkAtom">GdkAtom</link> representing the <literal>STRING</literal> selection type.
</para></refsect2>
<refsect2>
<title><anchor id="gdk-selection-owner-set">gdk_selection_owner_set ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    gdk_selection_owner_set         (<link linkend="GdkWindow">GdkWindow</link> *owner,
                                             <link linkend="GdkAtom">GdkAtom</link> selection,
                                             <link linkend="guint32">guint32</link> time,
                                             <link linkend="gboolean">gboolean</link> send_event);</programlisting>
<para>
Sets the owner of the given selection.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>owner</parameter>&nbsp;:</entry>
<entry>a <link linkend="GdkWindow">GdkWindow</link> or <literal>NULL</literal> to indicate that the
        the owner for the given should be unset.
</entry></row>
<row><entry align="right"><parameter>selection</parameter>&nbsp;:</entry>
<entry>an atom identifying a selection.
</entry></row>
<row><entry align="right"><parameter>time</parameter>&nbsp;:</entry>
<entry>timestamp to use when setting the selection.
       If this is older than the timestamp given last
       time the owner was set for the given selection, the 
       request will be ignored.
</entry></row>
<row><entry align="right"><parameter>send_event</parameter>&nbsp;:</entry>
<entry>if <literal>TRUE</literal>, and the new owner is different
             from the current owner, the current owner
             will be sent a SelectionClear event.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry><literal>TRUE</literal> if the selection owner was successfully
          changed to <parameter>owner</parameter>, otherwise <literal>FALSE</literal>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-selection-owner-get">gdk_selection_owner_get ()</title>
<programlisting><link linkend="GdkWindow">GdkWindow</link>*  gdk_selection_owner_get         (<link linkend="GdkAtom">GdkAtom</link> selection);</programlisting>
<para>
Determines the owner of the given selection.
</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>an atom indentifying a selection.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>if there is a selection owner for this window,
          and it is a window known to the current process,
          the <link linkend="GdkWindow">GdkWindow</link> that owns the selection, otherwise
          <literal>NULL</literal>. Note that the return value may be owned
          by a different process if a foreign window
          was previously created for that window, but
          a new foreign window will never be created by
          this call.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-selection-convert">gdk_selection_convert ()</title>
<programlisting>void        gdk_selection_convert           (<link linkend="GdkWindow">GdkWindow</link> *requestor,
                                             <link linkend="GdkAtom">GdkAtom</link> selection,
                                             <link linkend="GdkAtom">GdkAtom</link> target,
                                             <link linkend="guint32">guint32</link> time);</programlisting>
<para>
Retrieves the contents of a selection in a given
form.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>requestor</parameter>&nbsp;:</entry>
<entry>a <link linkend="GdkWindow">GdkWindow</link>.
</entry></row>
<row><entry align="right"><parameter>selection</parameter>&nbsp;:</entry>
<entry>an atom identifying the selection to get the
            contents of.
</entry></row>
<row><entry align="right"><parameter>target</parameter>&nbsp;:</entry>
<entry>the form in which to retrieve the selection.
</entry></row>
<row><entry align="right"><parameter>time</parameter>&nbsp;:</entry>
<entry>the timestamp to use when retrieving the
       selection. The selection owner may refuse the
       request if it did not own the selection at 
       the time indicated by the timestamp.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-selection-property-get">gdk_selection_property_get ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    gdk_selection_property_get      (<link linkend="GdkWindow">GdkWindow</link> *requestor,
                                             <link linkend="guchar">guchar</link> **data,
                                             <link linkend="GdkAtom">GdkAtom</link> *prop_type,
                                             <link linkend="gint">gint</link> *prop_format);</programlisting>
<para>
Retrieves selection data that was stored by the selection
data in response to a call to <link linkend="gdk-selection-convert">gdk_selection_convert</link>().
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>requestor</parameter>&nbsp;:</entry>
<entry>the window on which the data is stored
</entry></row>
<row><entry align="right"><parameter>data</parameter>&nbsp;:</entry>
<entry>location to store a pointer to the retrieved data.
       If the retrieval failed, <literal>NULL</literal> we be stored here, otherwise, it
       will be non-<literal>NULL</literal> and the returned data should be freed with <link linkend="g-free">g_free</link>()
       when you are finished using it. The length of the
       allocated memory is one more than the the length
       of the returned data, and the final byte will always
       be zero, to ensure nul-termination of strings.
</entry></row>
<row><entry align="right"><parameter>prop_type</parameter>&nbsp;:</entry>
<entry>location to store the type of the property.
</entry></row>
<row><entry align="right"><parameter>prop_format</parameter>&nbsp;:</entry>
<entry>location to store the format of the property.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the length of the retrieved data.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-selection-send-notify">gdk_selection_send_notify ()</title>
<programlisting>void        gdk_selection_send_notify       (<link linkend="guint32">guint32</link> requestor,
                                             <link linkend="GdkAtom">GdkAtom</link> selection,
                                             <link linkend="GdkAtom">GdkAtom</link> target,
                                             <link linkend="GdkAtom">GdkAtom</link> property,
                                             <link linkend="guint32">guint32</link> time);</programlisting>
<para>
Sends a response to SelectionRequest event.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>requestor</parameter>&nbsp;:</entry>
<entry>window to which to deliver response.
</entry></row>
<row><entry align="right"><parameter>selection</parameter>&nbsp;:</entry>
<entry>selection that was requested.
</entry></row>
<row><entry align="right"><parameter>target</parameter>&nbsp;:</entry>
<entry>target that was selected.
</entry></row>
<row><entry align="right"><parameter>property</parameter>&nbsp;:</entry>
<entry>property in which the selection owner stored the
           data, or <literal>GDK_NONE</literal> to indicate that the request
           was rejected.
</entry></row>
<row><entry align="right"><parameter>time</parameter>&nbsp;:</entry>
<entry>timestamp.


</entry></row>
</tbody></tgroup></informaltable></refsect2>

</refsect1>




</refentry>
