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

<refnamediv>
<refname>Drag and Drop</refname><refpurpose>Functions for controlling drag and drop handling.</refpurpose>
</refnamediv>

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

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


enum        <link linkend="GtkDestDefaults">GtkDestDefaults</link>;
enum        <link linkend="GtkTargetFlags">GtkTargetFlags</link>;

void        <link linkend="gtk-drag-dest-set">gtk_drag_dest_set</link>               (<link linkend="GtkWidget">GtkWidget</link> *widget,
                                             <link linkend="GtkDestDefaults">GtkDestDefaults</link> flags,
                                             const <link linkend="GtkTargetEntry">GtkTargetEntry</link> *targets,
                                             <link linkend="gint">gint</link> n_targets,
                                             <link linkend="GdkDragAction">GdkDragAction</link> actions);
void        <link linkend="gtk-drag-dest-set-proxy">gtk_drag_dest_set_proxy</link>         (<link linkend="GtkWidget">GtkWidget</link> *widget,
                                             <link linkend="GdkWindow">GdkWindow</link> *proxy_window,
                                             <link linkend="GdkDragProtocol">GdkDragProtocol</link> protocol,
                                             <link linkend="gboolean">gboolean</link> use_coordinates);
void        <link linkend="gtk-drag-dest-unset">gtk_drag_dest_unset</link>             (<link linkend="GtkWidget">GtkWidget</link> *widget);
<link linkend="GdkAtom">GdkAtom</link>     <link linkend="gtk-drag-dest-find-target">gtk_drag_dest_find_target</link>       (<link linkend="GtkWidget">GtkWidget</link> *widget,
                                             <link linkend="GdkDragContext">GdkDragContext</link> *context,
                                             <link linkend="GtkTargetList">GtkTargetList</link> *target_list);
<link linkend="GtkTargetList">GtkTargetList</link>* <link linkend="gtk-drag-dest-get-target-list">gtk_drag_dest_get_target_list</link>
                                            (<link linkend="GtkWidget">GtkWidget</link> *widget);
void        <link linkend="gtk-drag-dest-set-target-list">gtk_drag_dest_set_target_list</link>   (<link linkend="GtkWidget">GtkWidget</link> *widget,
                                             <link linkend="GtkTargetList">GtkTargetList</link> *target_list);
void        <link linkend="gtk-drag-finish">gtk_drag_finish</link>                 (<link linkend="GdkDragContext">GdkDragContext</link> *context,
                                             <link linkend="gboolean">gboolean</link> success,
                                             <link linkend="gboolean">gboolean</link> del,
                                             <link linkend="guint32">guint32</link> time);
void        <link linkend="gtk-drag-get-data">gtk_drag_get_data</link>               (<link linkend="GtkWidget">GtkWidget</link> *widget,
                                             <link linkend="GdkDragContext">GdkDragContext</link> *context,
                                             <link linkend="GdkAtom">GdkAtom</link> target,
                                             <link linkend="guint32">guint32</link> time);
<link linkend="GtkWidget">GtkWidget</link>*  <link linkend="gtk-drag-get-source-widget">gtk_drag_get_source_widget</link>      (<link linkend="GdkDragContext">GdkDragContext</link> *context);
void        <link linkend="gtk-drag-highlight">gtk_drag_highlight</link>              (<link linkend="GtkWidget">GtkWidget</link> *widget);
void        <link linkend="gtk-drag-unhighlight">gtk_drag_unhighlight</link>            (<link linkend="GtkWidget">GtkWidget</link> *widget);

<link linkend="GdkDragContext">GdkDragContext</link>* <link linkend="gtk-drag-begin">gtk_drag_begin</link>              (<link linkend="GtkWidget">GtkWidget</link> *widget,
                                             <link linkend="GtkTargetList">GtkTargetList</link> *targets,
                                             <link linkend="GdkDragAction">GdkDragAction</link> actions,
                                             <link linkend="gint">gint</link> button,
                                             <link linkend="GdkEvent">GdkEvent</link> *event);
void        <link linkend="gtk-drag-set-icon-widget">gtk_drag_set_icon_widget</link>        (<link linkend="GdkDragContext">GdkDragContext</link> *context,
                                             <link linkend="GtkWidget">GtkWidget</link> *widget,
                                             <link linkend="gint">gint</link> hot_x,
                                             <link linkend="gint">gint</link> hot_y);
void        <link linkend="gtk-drag-set-icon-pixmap">gtk_drag_set_icon_pixmap</link>        (<link linkend="GdkDragContext">GdkDragContext</link> *context,
                                             <link linkend="GdkColormap">GdkColormap</link> *colormap,
                                             <link linkend="GdkPixmap">GdkPixmap</link> *pixmap,
                                             <link linkend="GdkBitmap">GdkBitmap</link> *mask,
                                             <link linkend="gint">gint</link> hot_x,
                                             <link linkend="gint">gint</link> hot_y);
void        <link linkend="gtk-drag-set-icon-pixbuf">gtk_drag_set_icon_pixbuf</link>        (<link linkend="GdkDragContext">GdkDragContext</link> *context,
                                             <link linkend="GdkPixbuf">GdkPixbuf</link> *pixbuf,
                                             <link linkend="gint">gint</link> hot_x,
                                             <link linkend="gint">gint</link> hot_y);
void        <link linkend="gtk-drag-set-icon-stock">gtk_drag_set_icon_stock</link>         (<link linkend="GdkDragContext">GdkDragContext</link> *context,
                                             const <link linkend="gchar">gchar</link> *stock_id,
                                             <link linkend="gint">gint</link> hot_x,
                                             <link linkend="gint">gint</link> hot_y);
void        <link linkend="gtk-drag-set-icon-default">gtk_drag_set_icon_default</link>       (<link linkend="GdkDragContext">GdkDragContext</link> *context);
void        <link linkend="gtk-drag-set-default-icon">gtk_drag_set_default_icon</link>       (<link linkend="GdkColormap">GdkColormap</link> *colormap,
                                             <link linkend="GdkPixmap">GdkPixmap</link> *pixmap,
                                             <link linkend="GdkBitmap">GdkBitmap</link> *mask,
                                             <link linkend="gint">gint</link> hot_x,
                                             <link linkend="gint">gint</link> hot_y);
<link linkend="gboolean">gboolean</link>    <link linkend="gtk-drag-check-threshold">gtk_drag_check_threshold</link>        (<link linkend="GtkWidget">GtkWidget</link> *widget,
                                             <link linkend="gint">gint</link> start_x,
                                             <link linkend="gint">gint</link> start_y,
                                             <link linkend="gint">gint</link> current_x,
                                             <link linkend="gint">gint</link> current_y);
void        <link linkend="gtk-drag-source-set">gtk_drag_source_set</link>             (<link linkend="GtkWidget">GtkWidget</link> *widget,
                                             <link linkend="GdkModifierType">GdkModifierType</link> start_button_mask,
                                             const <link linkend="GtkTargetEntry">GtkTargetEntry</link> *targets,
                                             <link linkend="gint">gint</link> n_targets,
                                             <link linkend="GdkDragAction">GdkDragAction</link> actions);
void        <link linkend="gtk-drag-source-set-icon">gtk_drag_source_set_icon</link>        (<link linkend="GtkWidget">GtkWidget</link> *widget,
                                             <link linkend="GdkColormap">GdkColormap</link> *colormap,
                                             <link linkend="GdkPixmap">GdkPixmap</link> *pixmap,
                                             <link linkend="GdkBitmap">GdkBitmap</link> *mask);
void        <link linkend="gtk-drag-source-set-icon-pixbuf">gtk_drag_source_set_icon_pixbuf</link> (<link linkend="GtkWidget">GtkWidget</link> *widget,
                                             <link linkend="GdkPixbuf">GdkPixbuf</link> *pixbuf);
void        <link linkend="gtk-drag-source-set-icon-stock">gtk_drag_source_set_icon_stock</link>  (<link linkend="GtkWidget">GtkWidget</link> *widget,
                                             const <link linkend="gchar">gchar</link> *stock_id);
void        <link linkend="gtk-drag-source-unset">gtk_drag_source_unset</link>           (<link linkend="GtkWidget">GtkWidget</link> *widget);
</synopsis>
</refsynopsisdiv>





<refsect1>
<title>Description</title>
<para>
GTK+ has a rich set of functions for doing inter-process
communication via the drag-and-drop metaphor. GTK+
can do drag-and-drop (DND) via multiple protocols.
The currently supported protocols are the Xdnd and
Motif protocols.

As well as the functions listed here, applications
may need to use some facilities provided for
<link linkend="gtk-Selections">Selections</link>.
Also, the Drag and Drop API makes use of signals
in the <link linkend="GtkWidget">GtkWidget</link> class.
</para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="GtkDestDefaults">enum GtkDestDefaults</title>
<programlisting>typedef enum {
  GTK_DEST_DEFAULT_MOTION     = 1 &lt;&lt; 0, /* respond to "drag_motion" */
  GTK_DEST_DEFAULT_HIGHLIGHT  = 1 &lt;&lt; 1, /* auto-highlight */
  GTK_DEST_DEFAULT_DROP       = 1 &lt;&lt; 2, /* respond to "drag_drop" */
  GTK_DEST_DEFAULT_ALL        = 0x07
} GtkDestDefaults;
</programlisting>
<para>
The <link linkend="GtkDestDefaults">GtkDestDefaults</link> enumeration specifies the various
types of action that will be taken on behalf
of the user for a drag destination site.
</para><informaltable pgwide="1" frame="none" role="enum">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row>
<entry><literal>GTK_DEST_DEFAULT_MOTION</literal></entry>
<entry>
   If set for a widget, GTK+, during a drag over this
   widget will check if the drag matches this widget's
   list of possible targets and actions.
   GTK+ will then call <link linkend="gtk-drag-status">gtk_drag_status</link>() as appropriate.
</entry>
</row>
<row>
<entry><literal>GTK_DEST_DEFAULT_HIGHLIGHT</literal></entry>
<entry>
   If set for a widget, GTK+ will draw a highlight on
   this widget as long as a drag is over this widget
   and the widget drag format and action are acceptable.
</entry>
</row>
<row>
<entry><literal>GTK_DEST_DEFAULT_DROP</literal></entry>
<entry>
   If set for a widget, when a drop occurs, GTK+ will
   will check if the drag matches this widget's
   list of possible targets and actions. If so, 
   GTK+ will call <link linkend="gtk-drag-data-get">gtk_drag_data_get</link>() on behalf 
   of the widget. Whether or not the drop is successful,
   GTK+ will call <link linkend="gtk-drag-finish">gtk_drag_finish</link>(). If the action
   was a move, then if the drag was successful, then
   <literal>TRUE</literal> will be passed for the <parameter>delete</parameter> parameter
   to <link linkend="gtk-drag-finish">gtk_drag_finish</link>().
</entry>
</row>
<row>
<entry><literal>GTK_DEST_DEFAULT_ALL</literal></entry>
<entry>
   If set, specifies that all default actions should
   be taken.

</entry>
</row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GtkTargetFlags">enum GtkTargetFlags</title>
<programlisting>typedef enum {
  GTK_TARGET_SAME_APP = 1 &lt;&lt; 0,    /*&lt; nick=same-app &gt;*/
  GTK_TARGET_SAME_WIDGET = 1 &lt;&lt; 1  /*&lt; nick=same-widget &gt;*/
} GtkTargetFlags;
</programlisting>
<para>
The <link linkend="GtkTargetFlags">GtkTargetFlags</link> enumeration is used to specify
constraints on an entry in a <link linkend="GtkTargetTable">GtkTargetTable</link>. 
</para><informaltable pgwide="1" frame="none" role="enum">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row>
<entry><literal>GTK_TARGET_SAME_APP</literal></entry>
<entry>
   If this is set, the target will only be selected
   for drags within a single application.
 <parameter>GTK_TARGET_SAME_WIDGET</parameter>:
   If this is set, the target will only be selected
   for drags within a single widget.
</entry>
</row>
<row>
<entry><literal>GTK_TARGET_SAME_WIDGET</literal></entry>
<entry>

</entry>
</row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-drag-dest-set">gtk_drag_dest_set ()</title>
<programlisting>void        gtk_drag_dest_set               (<link linkend="GtkWidget">GtkWidget</link> *widget,
                                             <link linkend="GtkDestDefaults">GtkDestDefaults</link> flags,
                                             const <link linkend="GtkTargetEntry">GtkTargetEntry</link> *targets,
                                             <link linkend="gint">gint</link> n_targets,
                                             <link linkend="GdkDragAction">GdkDragAction</link> actions);</programlisting>
<para>
Sets a widget as a potential drop destination.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>widget</parameter>&nbsp;:</entry>
<entry>a <link linkend="GtkWidget">GtkWidget</link>
</entry></row>
<row><entry align="right"><parameter>flags</parameter>&nbsp;:</entry>
<entry>the flags that specify what actions GTK+ should take
 on behalf of a widget for drops onto that widget. The <parameter>targets</parameter>
 and <parameter>actions</parameter> fields only are used if <literal>GTK_DEST_DEFAULT_MOTION</literal>
 or <literal>GTK_DEST_DEFAULT_DROP</literal> are given.
</entry></row>
<row><entry align="right"><parameter>targets</parameter>&nbsp;:</entry>
<entry>a pointer to an array of <link linkend="GtkTargetEntry">GtkTargetEntry</link><!>s indicating
 the drop types that this widget will accept.
</entry></row>
<row><entry align="right"><parameter>n_targets</parameter>&nbsp;:</entry>
<entry>the number of entries in <parameter>targets</parameter>.
</entry></row>
<row><entry align="right"><parameter>actions</parameter>&nbsp;:</entry>
<entry>a bitmask of possible actions for a drop onto this
 widget.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-drag-dest-set-proxy">gtk_drag_dest_set_proxy ()</title>
<programlisting>void        gtk_drag_dest_set_proxy         (<link linkend="GtkWidget">GtkWidget</link> *widget,
                                             <link linkend="GdkWindow">GdkWindow</link> *proxy_window,
                                             <link linkend="GdkDragProtocol">GdkDragProtocol</link> protocol,
                                             <link linkend="gboolean">gboolean</link> use_coordinates);</programlisting>
<para>
Sets this widget as a proxy for drops to another window.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>widget</parameter>&nbsp;:</entry>
<entry>a <link linkend="GtkWidget">GtkWidget</link>
</entry></row>
<row><entry align="right"><parameter>proxy_window</parameter>&nbsp;:</entry>
<entry>the window to which to forward drag events
</entry></row>
<row><entry align="right"><parameter>protocol</parameter>&nbsp;:</entry>
<entry>the drag protocol which the <parameter>proxy_window</parameter> accepts
           (You can use <link linkend="gdk-drag-get-protocol">gdk_drag_get_protocol</link>() to determine this)
</entry></row>
<row><entry align="right"><parameter>use_coordinates</parameter>&nbsp;:</entry>
<entry>If true, send the same coordinates to the
                  destination, because it is an embedded 
                  subwindow.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-drag-dest-unset">gtk_drag_dest_unset ()</title>
<programlisting>void        gtk_drag_dest_unset             (<link linkend="GtkWidget">GtkWidget</link> *widget);</programlisting>
<para>
Clears information about a drop destination set with
<link linkend="gtk-drag-dest-set">gtk_drag_dest_set</link>(). The widget will no longer receive
notification of drags.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>widget</parameter>&nbsp;:</entry>
<entry>a <link linkend="GtkWidget">GtkWidget</link>


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-drag-dest-find-target">gtk_drag_dest_find_target ()</title>
<programlisting><link linkend="GdkAtom">GdkAtom</link>     gtk_drag_dest_find_target       (<link linkend="GtkWidget">GtkWidget</link> *widget,
                                             <link linkend="GdkDragContext">GdkDragContext</link> *context,
                                             <link linkend="GtkTargetList">GtkTargetList</link> *target_list);</programlisting>
<para>
Looks for a match between <parameter>context</parameter>->targets and the
<parameter>dest_target_list</parameter>, returning the first matching target, otherwise
returning <literal>GDK_NONE</literal>. <parameter>dest_target_list</parameter> should usually be the return
value from <link linkend="gtk-drag-dest-get-target-list">gtk_drag_dest_get_target_list</link>(), but some widgets may
have different valid targets for different parts of the widget; in
that case, they will have to implement a drag_motion handler that
passes the correct target list to this function.</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>widget</parameter>&nbsp;:</entry>
<entry> drag destination widget
</entry></row>
<row><entry align="right"><parameter>context</parameter>&nbsp;:</entry>
<entry> drag context
</entry></row>
<row><entry align="right"><parameter>target_list</parameter>&nbsp;:</entry>
<entry> list of droppable targets, or <literal>NULL</literal> to use
   gtk_drag_dest_get_target_list (<parameter>widget</parameter>).
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> first target that the source offers and the dest can accept, or <literal>GDK_NONE</literal>
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-drag-dest-get-target-list">gtk_drag_dest_get_target_list ()</title>
<programlisting><link linkend="GtkTargetList">GtkTargetList</link>* gtk_drag_dest_get_target_list
                                            (<link linkend="GtkWidget">GtkWidget</link> *widget);</programlisting>
<para>
Returns the list of targets this widget can accept from
drag-and-drop.</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>widget</parameter>&nbsp;:</entry>
<entry> a <link linkend="GtkWidget">GtkWidget</link>
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> the <link linkend="GtkTargetList">GtkTargetList</link>, or <literal>NULL</literal> if none
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-drag-dest-set-target-list">gtk_drag_dest_set_target_list ()</title>
<programlisting>void        gtk_drag_dest_set_target_list   (<link linkend="GtkWidget">GtkWidget</link> *widget,
                                             <link linkend="GtkTargetList">GtkTargetList</link> *target_list);</programlisting>
<para>
Sets the target types that this widget can accept from drag-and-drop.
The widget must first be made into a drag destination with
<link linkend="gtk-drag-dest-set">gtk_drag_dest_set</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>widget</parameter>&nbsp;:</entry>
<entry> a <link linkend="GtkWidget">GtkWidget</link> that's a drag destination
</entry></row>
<row><entry align="right"><parameter>target_list</parameter>&nbsp;:</entry>
<entry> list of droppable targets, or <literal>NULL</literal> for none
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-drag-finish">gtk_drag_finish ()</title>
<programlisting>void        gtk_drag_finish                 (<link linkend="GdkDragContext">GdkDragContext</link> *context,
                                             <link linkend="gboolean">gboolean</link> success,
                                             <link linkend="gboolean">gboolean</link> del,
                                             <link linkend="guint32">guint32</link> time);</programlisting>
<para>
Informs the drag source that the drop is finished, and
that the data of the drag will no longer be required.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>context</parameter>&nbsp;:</entry>
<entry>the drag context.
</entry></row>
<row><entry align="right"><parameter>success</parameter>&nbsp;:</entry>
<entry>a flag indicating whether the drop was successful
</entry></row>
<row><entry align="right"><parameter>del</parameter>&nbsp;:</entry>
<entry>a flag indicating whether the source should delete the
      original data. (This should be <literal>TRUE</literal> for a move)
</entry></row>
<row><entry align="right"><parameter>time</parameter>&nbsp;:</entry>
<entry>the timestamp from the "drag_data_drop" signal.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-drag-get-data">gtk_drag_get_data ()</title>
<programlisting>void        gtk_drag_get_data               (<link linkend="GtkWidget">GtkWidget</link> *widget,
                                             <link linkend="GdkDragContext">GdkDragContext</link> *context,
                                             <link linkend="GdkAtom">GdkAtom</link> target,
                                             <link linkend="guint32">guint32</link> time);</programlisting>
<para>
Gets the data associated with a drag. When the data
is received or the retrieval fails, GTK+ will emit a 
"drag_data_received" signal. Failure of the retrieval
is indicated by the length field of the <parameter>selection_data</parameter>
signal parameter being negative. However, when <link linkend="gtk-drag-get-data">gtk_drag_get_data</link>() 
is called implicitely because the <literal>GTK_DRAG_DEFAULT_DROP</literal> was set, 
then the widget will not receive notification of failed
drops.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>widget</parameter>&nbsp;:</entry>
<entry>the widget that will receive the "drag_data_received"
 signal.
</entry></row>
<row><entry align="right"><parameter>context</parameter>&nbsp;:</entry>
<entry>the drag context
</entry></row>
<row><entry align="right"><parameter>target</parameter>&nbsp;:</entry>
<entry>the target (form of the data) to retrieve.
</entry></row>
<row><entry align="right"><parameter>time</parameter>&nbsp;:</entry>
<entry>a timestamp for retrieving the data. This will
       generally be the time received in a "drag_data_motion"
       or "drag_data_drop" signal.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-drag-get-source-widget">gtk_drag_get_source_widget ()</title>
<programlisting><link linkend="GtkWidget">GtkWidget</link>*  gtk_drag_get_source_widget      (<link linkend="GdkDragContext">GdkDragContext</link> *context);</programlisting>
<para>
Determines the source widget for a drag.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>context</parameter>&nbsp;:</entry>
<entry>a (destination side) drag context.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>if the drag is occurring within a single application,
          a pointer to the source widget. Otherwise, <literal>NULL</literal>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-drag-highlight">gtk_drag_highlight ()</title>
<programlisting>void        gtk_drag_highlight              (<link linkend="GtkWidget">GtkWidget</link> *widget);</programlisting>
<para>
Draws a highlight around a widget. This will attach
handlers to  "expose_event" and "draw", so the highlight
will continue to be displayed until <link linkend="gtk-drag-unhighlight">gtk_drag_unhighlight</link>()
is called.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>widget</parameter>&nbsp;:</entry>
<entry>a widget to highlight


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-drag-unhighlight">gtk_drag_unhighlight ()</title>
<programlisting>void        gtk_drag_unhighlight            (<link linkend="GtkWidget">GtkWidget</link> *widget);</programlisting>
<para>
Removes a highlight set by <link linkend="gtk-drag-highlight">gtk_drag_highlight</link>() from
a widget.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>widget</parameter>&nbsp;:</entry>
<entry>a widget to remove the highlight from.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-drag-begin">gtk_drag_begin ()</title>
<programlisting><link linkend="GdkDragContext">GdkDragContext</link>* gtk_drag_begin              (<link linkend="GtkWidget">GtkWidget</link> *widget,
                                             <link linkend="GtkTargetList">GtkTargetList</link> *targets,
                                             <link linkend="GdkDragAction">GdkDragAction</link> actions,
                                             <link linkend="gint">gint</link> button,
                                             <link linkend="GdkEvent">GdkEvent</link> *event);</programlisting>
<para>
Initiates a drag on the source side. The function
only needs to be used when the application is
starting drags itself, and is not needed when
<link linkend="gtk-drag-source-set">gtk_drag_source_set</link>() is used.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>widget</parameter>&nbsp;:</entry>
<entry>the source widget.
</entry></row>
<row><entry align="right"><parameter>targets</parameter>&nbsp;:</entry>
<entry>The targets (data formats) in which the
 source can provide the data.
</entry></row>
<row><entry align="right"><parameter>actions</parameter>&nbsp;:</entry>
<entry>A bitmask of the allowed drag actions for this
          drag.
</entry></row>
<row><entry align="right"><parameter>button</parameter>&nbsp;:</entry>
<entry>The button the user clicked to start the drag.
</entry></row>
<row><entry align="right"><parameter>event</parameter>&nbsp;:</entry>
<entry>The event that triggered the start of the
        drag.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>The context for this drag.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-drag-set-icon-widget">gtk_drag_set_icon_widget ()</title>
<programlisting>void        gtk_drag_set_icon_widget        (<link linkend="GdkDragContext">GdkDragContext</link> *context,
                                             <link linkend="GtkWidget">GtkWidget</link> *widget,
                                             <link linkend="gint">gint</link> hot_x,
                                             <link linkend="gint">gint</link> hot_y);</programlisting>
<para>
Changes the icon for a widget to a given widget. GTK+
will not destroy the icon, so if you don't want
it to persist, you should connect to the "drag_end" 
signal and destroy it yourself.</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>context</parameter>&nbsp;:</entry>
<entry> the context for a drag. (This must be called 
          with a  context for the source side of a drag)
</entry></row>
<row><entry align="right"><parameter>widget</parameter>&nbsp;:</entry>
<entry> a toplevel window to use as an icon.
</entry></row>
<row><entry align="right"><parameter>hot_x</parameter>&nbsp;:</entry>
<entry> the X offset within <parameter>widget</parameter> of the hotspot.
</entry></row>
<row><entry align="right"><parameter>hot_y</parameter>&nbsp;:</entry>
<entry> the Y offset within <parameter>widget</parameter> of the hotspot.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-drag-set-icon-pixmap">gtk_drag_set_icon_pixmap ()</title>
<programlisting>void        gtk_drag_set_icon_pixmap        (<link linkend="GdkDragContext">GdkDragContext</link> *context,
                                             <link linkend="GdkColormap">GdkColormap</link> *colormap,
                                             <link linkend="GdkPixmap">GdkPixmap</link> *pixmap,
                                             <link linkend="GdkBitmap">GdkBitmap</link> *mask,
                                             <link linkend="gint">gint</link> hot_x,
                                             <link linkend="gint">gint</link> hot_y);</programlisting>
<para>
Sets <parameter>pixmap</parameter> as the icon for a given drag. GTK+ retains
references for the arguments, and will release them when
they are no longer needed. In general, <link linkend="gtk-drag-set-icon-pixbuf">gtk_drag_set_icon_pixbuf</link>()
will be more convenient to use.</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>context</parameter>&nbsp;:</entry>
<entry> the context for a drag. (This must be called 
           with a  context for the source side of a drag)
</entry></row>
<row><entry align="right"><parameter>colormap</parameter>&nbsp;:</entry>
<entry> the colormap of the icon 
</entry></row>
<row><entry align="right"><parameter>pixmap</parameter>&nbsp;:</entry>
<entry> the image data for the icon 
</entry></row>
<row><entry align="right"><parameter>mask</parameter>&nbsp;:</entry>
<entry> the transparency mask for the icon
</entry></row>
<row><entry align="right"><parameter>hot_x</parameter>&nbsp;:</entry>
<entry> the X offset within <parameter>pixmap</parameter> of the hotspot.
</entry></row>
<row><entry align="right"><parameter>hot_y</parameter>&nbsp;:</entry>
<entry> the Y offset within <parameter>pixmap</parameter> of the hotspot.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-drag-set-icon-pixbuf">gtk_drag_set_icon_pixbuf ()</title>
<programlisting>void        gtk_drag_set_icon_pixbuf        (<link linkend="GdkDragContext">GdkDragContext</link> *context,
                                             <link linkend="GdkPixbuf">GdkPixbuf</link> *pixbuf,
                                             <link linkend="gint">gint</link> hot_x,
                                             <link linkend="gint">gint</link> hot_y);</programlisting>
<para>
Sets <parameter>pixbuf</parameter> as the icon for a given drag.</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>context</parameter>&nbsp;:</entry>
<entry> the context for a drag. (This must be called 
           with a  context for the source side of a drag)
</entry></row>
<row><entry align="right"><parameter>pixbuf</parameter>&nbsp;:</entry>
<entry> the <link linkend="GdkPixbuf">GdkPixbuf</link> to use as the drag icon.
</entry></row>
<row><entry align="right"><parameter>hot_x</parameter>&nbsp;:</entry>
<entry> the X offset within <parameter>widget</parameter> of the hotspot.
</entry></row>
<row><entry align="right"><parameter>hot_y</parameter>&nbsp;:</entry>
<entry> the Y offset within <parameter>widget</parameter> of the hotspot.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-drag-set-icon-stock">gtk_drag_set_icon_stock ()</title>
<programlisting>void        gtk_drag_set_icon_stock         (<link linkend="GdkDragContext">GdkDragContext</link> *context,
                                             const <link linkend="gchar">gchar</link> *stock_id,
                                             <link linkend="gint">gint</link> hot_x,
                                             <link linkend="gint">gint</link> hot_y);</programlisting>
<para>
Sets the the icon for a given drag from a stock ID.</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>context</parameter>&nbsp;:</entry>
<entry> the context for a drag. (This must be called 
           with a  context for the source side of a drag)
</entry></row>
<row><entry align="right"><parameter>stock_id</parameter>&nbsp;:</entry>
<entry> the ID of the stock icon to use for the drag.
</entry></row>
<row><entry align="right"><parameter>hot_x</parameter>&nbsp;:</entry>
<entry> the X offset within the icon of the hotspot.
</entry></row>
<row><entry align="right"><parameter>hot_y</parameter>&nbsp;:</entry>
<entry> the Y offset within the icon of the hotspot.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-drag-set-icon-default">gtk_drag_set_icon_default ()</title>
<programlisting>void        gtk_drag_set_icon_default       (<link linkend="GdkDragContext">GdkDragContext</link> *context);</programlisting>
<para>
Sets the icon for a particular drag to the default
icon.</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>context</parameter>&nbsp;:</entry>
<entry> the context for a drag. (This must be called 
             with a  context for the source side of a drag)
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-drag-set-default-icon">gtk_drag_set_default_icon ()</title>
<programlisting>void        gtk_drag_set_default_icon       (<link linkend="GdkColormap">GdkColormap</link> *colormap,
                                             <link linkend="GdkPixmap">GdkPixmap</link> *pixmap,
                                             <link linkend="GdkBitmap">GdkBitmap</link> *mask,
                                             <link linkend="gint">gint</link> hot_x,
                                             <link linkend="gint">gint</link> hot_y);</programlisting>
<warning>
<para>
<literal>gtk_drag_set_default_icon</literal> is deprecated and should not be used in newly-written code.
</para>
</warning>
<para>
Changes the default drag icon. GTK+ retains references for the
arguments, and will release them when they are no longer needed.
This function is obsolete. The default icon should now be changed
via the stock system by changing the stock pixbuf for <link linkend="GTK-STOCK-DND-CAPS">GTK_STOCK_DND</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>colormap</parameter>&nbsp;:</entry>
<entry> the colormap of the icon
</entry></row>
<row><entry align="right"><parameter>pixmap</parameter>&nbsp;:</entry>
<entry> the image data for the icon
</entry></row>
<row><entry align="right"><parameter>mask</parameter>&nbsp;:</entry>
<entry> the transparency mask for an image.
</entry></row>
<row><entry align="right"><parameter>hot_x</parameter>&nbsp;:</entry>
<entry> The X offset within <parameter>widget</parameter> of the hotspot.
</entry></row>
<row><entry align="right"><parameter>hot_y</parameter>&nbsp;:</entry>
<entry> The Y offset within <parameter>widget</parameter> of the hotspot.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-drag-check-threshold">gtk_drag_check_threshold ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    gtk_drag_check_threshold        (<link linkend="GtkWidget">GtkWidget</link> *widget,
                                             <link linkend="gint">gint</link> start_x,
                                             <link linkend="gint">gint</link> start_y,
                                             <link linkend="gint">gint</link> current_x,
                                             <link linkend="gint">gint</link> current_y);</programlisting>
<para>
Checks to see if a mouse drag starting at (<parameter>start_x</parameter>, <parameter>start_y</parameter>) and ending
at (<parameter>current_x</parameter>, <parameter>current_y</parameter>) has passed the GTK+ drag threshhold, and thus
should trigger the beginning of a drag-and-drop operation.</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>widget</parameter>&nbsp;:</entry>
<entry> a <link linkend="GtkWidget">GtkWidget</link>
</entry></row>
<row><entry align="right"><parameter>start_x</parameter>&nbsp;:</entry>
<entry> X coordinate of start of drag
</entry></row>
<row><entry align="right"><parameter>start_y</parameter>&nbsp;:</entry>
<entry> Y coordinate of start of drag
</entry></row>
<row><entry align="right"><parameter>current_x</parameter>&nbsp;:</entry>
<entry> current X coordinate
</entry></row>
<row><entry align="right"><parameter>current_y</parameter>&nbsp;:</entry>
<entry> current Y coordinate
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> <literal>TRUE</literal> if the drag threshold has been passed.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-drag-source-set">gtk_drag_source_set ()</title>
<programlisting>void        gtk_drag_source_set             (<link linkend="GtkWidget">GtkWidget</link> *widget,
                                             <link linkend="GdkModifierType">GdkModifierType</link> start_button_mask,
                                             const <link linkend="GtkTargetEntry">GtkTargetEntry</link> *targets,
                                             <link linkend="gint">gint</link> n_targets,
                                             <link linkend="GdkDragAction">GdkDragAction</link> actions);</programlisting>
<para>
Sets up a widget so that GTK+ will start a drag
operation when the user clicks and drags on the
widget. The widget must have a window.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>widget</parameter>&nbsp;:</entry>
<entry>a <link linkend="GtkWidget">GtkWidget</link>
</entry></row>
<row><entry align="right"><parameter>start_button_mask</parameter>&nbsp;:</entry>
<entry>the bitmask of buttons that can start the drag
</entry></row>
<row><entry align="right"><parameter>targets</parameter>&nbsp;:</entry>
<entry>the table of targets that the drag will support
</entry></row>
<row><entry align="right"><parameter>n_targets</parameter>&nbsp;:</entry>
<entry>the number of items in <parameter>targets</parameter>
</entry></row>
<row><entry align="right"><parameter>actions</parameter>&nbsp;:</entry>
<entry>the bitmask of possible actions for a drag from this
 widget.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-drag-source-set-icon">gtk_drag_source_set_icon ()</title>
<programlisting>void        gtk_drag_source_set_icon        (<link linkend="GtkWidget">GtkWidget</link> *widget,
                                             <link linkend="GdkColormap">GdkColormap</link> *colormap,
                                             <link linkend="GdkPixmap">GdkPixmap</link> *pixmap,
                                             <link linkend="GdkBitmap">GdkBitmap</link> *mask);</programlisting>
<para>
Sets the icon that will be used for drags from a particular widget
from a pixmap/mask. GTK+ retains references for the arguments, and 
will release them when they are no longer needed.
Use <link linkend="gtk-drag-source-set-icon-pixbuf">gtk_drag_source_set_icon_pixbuf</link>() instead.</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>widget</parameter>&nbsp;:</entry>
<entry> a <link linkend="GtkWidget">GtkWidget</link>
</entry></row>
<row><entry align="right"><parameter>colormap</parameter>&nbsp;:</entry>
<entry> the colormap of the icon
</entry></row>
<row><entry align="right"><parameter>pixmap</parameter>&nbsp;:</entry>
<entry> the image data for the icon
</entry></row>
<row><entry align="right"><parameter>mask</parameter>&nbsp;:</entry>
<entry> the transparency mask for an image.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-drag-source-set-icon-pixbuf">gtk_drag_source_set_icon_pixbuf ()</title>
<programlisting>void        gtk_drag_source_set_icon_pixbuf (<link linkend="GtkWidget">GtkWidget</link> *widget,
                                             <link linkend="GdkPixbuf">GdkPixbuf</link> *pixbuf);</programlisting>
<para>
Sets the icon that will be used for drags from a particular widget
from a <link linkend="GdkPixbuf">GdkPixbuf</link>. GTK+ retains a reference for <parameter>pixbuf</parameter> and will 
release it when it is no longer needed.</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>widget</parameter>&nbsp;:</entry>
<entry> a <link linkend="GtkWidget">GtkWidget</link>
</entry></row>
<row><entry align="right"><parameter>pixbuf</parameter>&nbsp;:</entry>
<entry> the <link linkend="GdkPixbuf">GdkPixbuf</link> for the drag icon
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-drag-source-set-icon-stock">gtk_drag_source_set_icon_stock ()</title>
<programlisting>void        gtk_drag_source_set_icon_stock  (<link linkend="GtkWidget">GtkWidget</link> *widget,
                                             const <link linkend="gchar">gchar</link> *stock_id);</programlisting>
<para>
Sets the icon that will be used for drags from a particular source
to a stock icon.</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>widget</parameter>&nbsp;:</entry>
<entry> a <link linkend="GtkWidget">GtkWidget</link>
</entry></row>
<row><entry align="right"><parameter>stock_id</parameter>&nbsp;:</entry>
<entry> the ID of the stock icon to use
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gtk-drag-source-unset">gtk_drag_source_unset ()</title>
<programlisting>void        gtk_drag_source_unset           (<link linkend="GtkWidget">GtkWidget</link> *widget);</programlisting>
<para>
Undoes the effects of <link linkend="gtk-drag-source-set">gtk_drag_source_set</link>().
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>widget</parameter>&nbsp;:</entry>
<entry>a <link linkend="GtkWidget">GtkWidget</link>


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

</refsect1>




</refentry>
