<?xml version="1.0" standalone="no"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">

<refentry id="class-gdkdragcontext">
  <refnamediv>
    <refname>gtk.gdk.DragContext</refname>
    <refpurpose>an object containing the drag and drop context
data</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>gtk.gdk.DragContext</classname></ooclass>
      <ooclass><classname><link
linkend="class-gobject">gobject.GObject</link></classname></ooclass>
      <constructorsynopsis language="python">
	<methodname><link
linkend="constructor-gdkdragcontext">gtk.gdk.DragContext</link></methodname>
	<methodparam></methodparam>  </constructorsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gdkdragcontext--drag-status">drag_status</link></methodname>
	<methodparam><parameter
		       role="keyword">action</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">time</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gdkdragcontext--drop-reply">drop_reply</link></methodname>
	<methodparam><parameter role="keyword">ok</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">time</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gdkdragcontext--drop-finish">drop_finish</link></methodname>
	<methodparam><parameter
		       role="keyword">success</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">time</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gdkdragcontext--drag-get-selection">drag_get_selection</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gdkdragcontext--drag-find-window">drag_find_window</link></methodname>
	<methodparam><parameter
		       role="keyword">drag_window</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">x_root</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">y_root</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gdkdragcontext--drag-find-window-for-screen">drag_find_window_for_screen</link></methodname>
	<methodparam><parameter
		       role="keyword">drag_window</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">screen</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">x_root</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">y_root</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gdkdragcontext--drag-motion">drag_motion</link></methodname>
	<methodparam><parameter
		       role="keyword">dest_window</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">protocol</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">x_root</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">y_root</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">suggested_action</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">possible_actions</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">time</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gdkdragcontext--drag-drop">drag_drop</link></methodname>
	<methodparam><parameter
		       role="keyword">time</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gdkdragcontext--drag-abort">drag_abort</link></methodname>
	<methodparam><parameter
		       role="keyword">time</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gdkdragcontext--finish">finish</link></methodname>
	<methodparam><parameter
		       role="keyword">success</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">del_</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">time</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gdkdragcontext--get-source-widget">get_source_widget</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gdkdragcontext--set-icon-widget">set_icon_widget</link></methodname>
	<methodparam><parameter
		       role="keyword">widget</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">hot_x</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">hot_y</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gdkdragcontext--set-icon-pixmap">set_icon_pixmap</link></methodname>
	<methodparam><parameter
		       role="keyword">colormap</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">pixmap</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">mask</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">hot_x</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">hot_y</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gdkdragcontext--set-icon-pixbuf">set_icon_pixbuf</link></methodname>
	<methodparam><parameter
		       role="keyword">pixbuf</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">hot_x</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">hot_y</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gdkdragcontext--set-icon-stock">set_icon_stock</link></methodname>
	<methodparam><parameter
		       role="keyword">stock_id</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">hot_x</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">hot_y</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gdkdragcontext--set-icon-name">set_icon_name</link></methodname>
	<methodparam><parameter
		       role="keyword">icon_name</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">hot_x</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">hot_y</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gdkdragcontext--set-icon-default">set_icon_default</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gdkdragcontext--drag-drop-succeeded">drag_drop_succeeded</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
    </classsynopsis>

  </refsect1>

  <refsect1>
    <title>Ancestry</title>

<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link>
  +-- <link linkend="class-gdkdragcontext">gtk.gdk.DragContext</link>
</synopsis>

  </refsect1>

  <refsect1>
    <title>Attributes</title>

    <blockquote role="properties">
      <informaltable pgwide="1" frame="none">
	<tgroup cols="3">
	<?dbhtml cellpadding="5"?>
	  <colspec column="1" colwidth="1in"/>
	  <colspec column="2" colwidth="1in"/>
	  <colspec column="3" colwidth="4in"/>
	  <tbody>

	    <row valign="top">
	      <entry>"action"</entry>
	      <entry>Read</entry>
	      <entry>the action chosen by the destination. One of:
<literal>gtk.gdk.ACTION_COPY</literal>,
<literal>gtk.gdk.ACTION_MOVE</literal>,
<literal>gtk.gdk.ACTION_LINK</literal>,
<literal>gtk.gdk.ACTION_PRIVATE</literal></entry>
	    </row>

	    <row valign="top">
	      <entry>"actions"</entry>
	      <entry>Read</entry>
	      <entry>a bitmask of actions proposed by the source when
<literal>suggested_action</literal> is
<literal>gtk.gdk.ACTION_ASK</literal>. A combination of:
<literal>gtk.gdk.ACTION_COPY</literal>,
<literal>gtk.gdk.ACTION_MOVE</literal>,
<literal>gtk.gdk.ACTION_LINK</literal>,
<literal>gtk.gdk.ACTION_PRIVATE</literal></entry>
	    </row>

	    <row valign="top">
	      <entry>"dest_window"</entry>
	      <entry>Read</entry>
	      <entry>the destination <link
linkend="class-gdkwindow"><classname>gtk.gdk.Window</classname></link> of
this drag.</entry>
	    </row>

	    <row valign="top">
	      <entry>"is_source"</entry>
	      <entry>Read</entry>
	      <entry>if True the context is used on the source side.</entry>
	    </row>

	    <row valign="top">
	      <entry>"protocol"</entry>
	      <entry>Read</entry>
	      <entry>the DND protocol which governs this drag - one of:
<literal>gtk.gdk.DRAG_PROTO_MOTIF</literal>,
<literal>gtk.gdk.DRAG_PROTO_XDND</literal>,
<literal>gtk.gdk.DRAG_PROTO_ROOTWIN</literal>,
<literal>gtk.gdk.DRAG_PROTO_NONE</literal>,
<literal>gtk.gdk.DRAG_PROTO_WIN32_DROPFILES</literal>,
<literal>gtk.gdk.DRAG_PROTO_OLE2</literal>,
<literal>gtk.gdk.DRAG_PROTO_LOCAL</literal></entry>
	    </row>

	    <row valign="top">
	      <entry>"source_window"</entry>
	      <entry>Read</entry>
	      <entry>the source <link
linkend="class-gdkwindow"><classname>gtk.gdk.Window</classname></link> of
this drag.</entry>
	    </row>

	    <row valign="top">
	      <entry>"start_time"</entry>
	      <entry>Read</entry>
	      <entry>a timestamp recording the start time of this
drag.</entry>
	    </row>

	    <row valign="top">
	      <entry>"suggested_action"</entry>
	      <entry>Read</entry>
	      <entry>the action suggested by the source. One of:
<literal>gtk.gdk.ACTION_DEFAULT</literal>,
<literal>gtk.gdk.ACTION_COPY</literal>,
<literal>gtk.gdk.ACTION_MOVE</literal>,
<literal>gtk.gdk.ACTION_LINK</literal>,
<literal>gtk.gdk.ACTION_PRIVATE</literal>,
<literal>gtk.gdk.ACTION_ASK</literal></entry>
	    </row>

	    <row valign="top">
	      <entry>"targets"</entry>
	      <entry>Read</entry>
	      <entry>a list of targets offered by the source.</entry>
	    </row>

	  </tbody>
	</tgroup>
      </informaltable>
    </blockquote>

  </refsect1>

  <refsect1>
    <title>Description</title>

    <para>A <link
linkend="class-gdkdragcontext"><classname>gtk.gdk.DragContext</classname></link>
holds information about a drag in progress. It is used for both source and
destination. A <link
linkend="class-gdkdragcontext"><classname>gtk.gdk.DragContext</classname></link>
can be created using the <link
linkend="constructor-gdkdragcontext">gtk.gdk.DragContext</link>()
constructor but since there is no way to set its attributes the new object
is not much use. Useful <link
linkend="class-gdkdragcontext"><classname>gtk.gdk.DragContext</classname></link>
objects are created as a result of the <link
linkend="method-gdkwindow--drag-begin"><methodname>gtk.gdk.Window.drag_begin</methodname>()</link>
or the <link
linkend="method-gtkwidget--drag-begin"><methodname>gtk.Widget.drag_begin</methodname>()</link>
methods.</para>

  </refsect1>

  <refsect1 id="constructor-gdkdragcontext">
    <title>Constructor</title>

    <programlisting><constructorsynopsis language="python">
	<methodname>gtk.gdk.DragContext</methodname>
	<methodparam></methodparam>  </constructorsynopsis></programlisting>
    <variablelist>
      <varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	<listitem><simpara>a new <link
linkend="class-gdkdragcontext"><classname>gtk.gdk.DragContext</classname></link></simpara></listitem>
      </varlistentry>
    </variablelist>

    <para>Creates a new <link
linkend="class-gdkdragcontext"><classname>gtk.gdk.DragContext</classname></link> 
object.</para>

  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-gdkdragcontext--drag-status">
      <title>gtk.gdk.DragContext.drag_status</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>drag_status</methodname>
	  <methodparam><parameter
			 role="keyword">action</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">time</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">action</parameter>&nbsp;:</term>
	  <listitem><simpara>a drag action that will be taken when a drop
happens</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">time</parameter>&nbsp;:</term>
	  <listitem><simpara>the timestamp for this
action</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>drag_status</methodname>() method sets the
specified <parameter>action</parameter> to be taken when a drop happens. The
value of <parameter>action</parameter> is one of:</para>

      <variablelist>
	<varlistentry>
	  <term><literal>gtk.gdk.ACTION_DEFAULT</literal></term>
	  <listitem>
	    <simpara></simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gtk.gdk.ACTION_COPY</literal></term>
	  <listitem>
	    <simpara>Copy the data.</simpara>
	  </listitem>
	</varlistentry>
 	<varlistentry>
	  <term><literal>gtk.gdk.ACTION_MOVE</literal></term>
	  <listitem>
	    <simpara>Move the data, i.e. first copy it, then delete it from
the source using the DELETE target of the X selection protocol.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gtk.gdk.ACTION_LINK</literal></term>
	  <listitem>
	    <simpara>Add a link to the data. Note that this is only useful
if source and destination agree on what it means.</simpara>
	  </listitem>
	</varlistentry>
 	<varlistentry>
	  <term><literal>gtk.gdk.ACTION_PRIVATE</literal></term>
	  <listitem>
	    <simpara>Special action which tells the source that the
destination will do something that the source doesn't understand.</simpara>
	  </listitem>
	</varlistentry>
 	<varlistentry>
	  <term><literal>gtk.gdk.ACTION_ASK</literal></term>
	  <listitem>
	    <simpara>Ask the user what to do with the data.</simpara>
	  </listitem>
	</varlistentry>
      </variablelist>

      <para>The time the action occurred is specified by
<parameter>time</parameter>. This method is called by the drag destination
in response to <link
linkend="method-gdkdragcontext--drag-motion"><methodname>drag_motion</methodname>()</link> 
called by the drag source.
</para>

    </refsect2>

    <refsect2 id="method-gdkdragcontext--drop-reply">
      <title>gtk.gdk.DragContext.drop_reply</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>drop_reply</methodname>
	  <methodparam><parameter
			 role="keyword">ok</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">time</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">ok</parameter>&nbsp;:</term>
	  <listitem><simpara>if <literal>True</literal> the drop is accepted
by the destination</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">time</parameter>&nbsp;:</term>
	  <listitem><simpara>the timestamp</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>drop_reply</methodname>() method determines if
the drop is accepted or rejected according to the value specified by
<parameter>ok</parameter>. If <parameter>ok</parameter> is
<literal>True</literal> the drop is accepted. <parameter>time</parameter>
specifies the time that the drop reply occurred. This method is called by
the drag destination when a drop is initiated by the drag source.</para>

    </refsect2>

    <refsect2 id="method-gdkdragcontext--drop-finish">
      <title>gtk.gdk.DragContext.drop_finish</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>drop_finish</methodname>
	  <methodparam><parameter
			 role="keyword">success</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">time</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">success</parameter>&nbsp;:</term>
	  <listitem><simpara>if True the data was
received</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">time</parameter>&nbsp;:</term>
	  <listitem><simpara>the time of the finish</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>drop_finish</methodname>() method ends a drag
operation and indicates if the drop was successful by setting the value of
<parameter>success</parameter>. <parameter>time</parameter> indicates the
time of the drop finish. This method is called by the drag
destination.</para>

    </refsect2>

    <refsect2 id="method-gdkdragcontext--drag-get-selection">
      <title>gtk.gdk.DragContext.drag_get_selection</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>drag_get_selection</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the selection atom</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>drag_get_selection</methodname>() method returns
the selection atom for the current source window.</para>

    </refsect2>

    <refsect2 id="method-gdkdragcontext--drag-find-window">
      <title>gtk.gdk.DragContext.drag_find_window</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>drag_find_window</methodname>
	  <methodparam><parameter
			 role="keyword">drag_window</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">x_root</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">y_root</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
role="keyword">drag_window</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-gdkwindow"><classname>gtk.gdk.Window</classname></link></simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">x_root</parameter>&nbsp;:</term>
	  <listitem><simpara>the x position of the pointer in root
coordinates.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">y_root</parameter>&nbsp;:</term>
	  <listitem><simpara>the y position of the pointer in root
coordinates.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a 2-tuple containing the drag destination <link
linkend="class-gdkwindow"><classname>gtk.gdk.Window</classname></link> and
the drag protocol</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>drag_find_window</methodname>() method returns a
2-tuple containing the drag destination <link
linkend="class-gdkwindow"><classname>gtk.gdk.Window</classname></link> and
the drag protocol being used. The drag protocol is one of:</para>

      <variablelist>
	<varlistentry>
	  <term><literal>gtk.gdk.DRAG_PROTO_MOTIF</literal></term>
	  <listitem>
	    <simpara>The Motif DND protocol. </simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gtk.gdk.DRAG_PROTO_XDND</literal></term>
	  <listitem>
	    <simpara>The Xdnd protocol.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gtk.gdk.DRAG_PROTO_ROOTWIN</literal></term>
	  <listitem>
	    <simpara>An extension to the Xdnd protocol for unclaimed root
window drops. </simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gtk.gdk.DRAG_PROTO_NONE</literal></term>
	  <listitem>
	    <simpara>no protocol.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gtk.gdk.DRAG_PROTO_WIN32_DROPFILES</literal></term>
	  <listitem>
	    <simpara>The simple WM_DROPFILES protocol.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gtk.gdk.DRAG_PROTO_OLE2</literal></term>
	  <listitem>
	    <simpara>The complex OLE2 DND protocol (not
implemented).</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gtk.gdk.DRAG_PROTO_LOCAL</literal></term>
	  <listitem>
	    <simpara>Intra-application DND.</simpara>
	  </listitem>
	</varlistentry>
      </variablelist>

      <para><parameter>drag_window</parameter> is a <link
linkend="class-gdkwindow"><classname>gtk.gdk.Window</classname></link> and
<parameter>x_root</parameter> and <parameter>y_root</parameter> specify the
location of the mouse pointer in the root window.</para>

    </refsect2>

    <refsect2 id="method-gdkdragcontext--drag-find-window-for-screen">
      <title>gtk.gdk.DragContext.drag_find_window_for_screen</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>drag_find_window_for_screen</methodname>
	  <methodparam><parameter
			 role="keyword">drag_window</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">screen</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">x_root</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">y_root</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
role="keyword">drag_window</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-gdkwindow"><classname>gtk.gdk.Window</classname></link></simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">screen</parameter>&nbsp;:</term>
<listitem><simpara>a <link
linkend="class-gdkscreen"><classname>gtk.gdk.Screen</classname></link></simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">x_root</parameter>&nbsp;:</term>
	  <listitem><simpara>the x position of the pointer in root
coordinates.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">y_root</parameter>&nbsp;:</term>
	  <listitem><simpara>the y position of the pointer in root
coordinates.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a 2-tuple containing the drag destination <link
linkend="class-gdkwindow"><classname>gtk.gdk.Window</classname></link> and
the drag protocol</simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
	<para>This method is available in PyGTK 2.2 and above.</para>
      </note>

      <para>The <methodname>drag_find_window_for_screen</methodname>()
method returns a 2-tuple containing the drag destination <link
linkend="class-gdkwindow"><classname>gtk.gdk.Window</classname></link> and
the drag protocol being used. The drag protocol is one of:</para>

      <variablelist>
	<varlistentry>
	  <term><literal>gtk.gdk.DRAG_PROTO_MOTIF</literal></term>
	  <listitem>
	    <simpara>The Motif DND protocol. </simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gtk.gdk.DRAG_PROTO_XDND</literal></term>
	  <listitem>
	    <simpara>The Xdnd protocol.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gtk.gdk.DRAG_PROTO_ROOTWIN</literal></term>
	  <listitem>
	    <simpara>An extension to the Xdnd protocol for unclaimed root
window drops. </simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gtk.gdk.DRAG_PROTO_NONE</literal></term>
	  <listitem>
	    <simpara>no protocol.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gtk.gdk.DRAG_PROTO_WIN32_DROPFILES</literal></term>
	  <listitem>
	    <simpara>The simple WM_DROPFILES protocol.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gtk.gdk.DRAG_PROTO_OLE2</literal></term>
	  <listitem>
	    <simpara>The complex OLE2 DND protocol (not
implemented).</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gtk.gdk.DRAG_PROTO_LOCAL</literal></term>
	  <listitem>
	    <simpara>Intra-application DND.</simpara>
	  </listitem>
	</varlistentry>
      </variablelist>

      <para><parameter>drag_window</parameter> is a <link
linkend="class-gdkwindow"><classname>gtk.gdk.Window</classname></link> and
<parameter>x_root</parameter> and <parameter>y_root</parameter> specify the
location of the mouse pointer in the root window.</para>

    </refsect2>

    <refsect2 id="method-gdkdragcontext--drag-motion">
      <title>gtk.gdk.DragContext.drag_motion</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>drag_motion</methodname>
	  <methodparam><parameter
			 role="keyword">dest_window</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">protocol</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">x_root</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">y_root</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">suggested_action</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">possible_actions</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">time</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
role="keyword">dest_window</parameter>&nbsp;:</term>
	  <listitem><simpara>the destination <link
linkend="class-gdkwindow"><classname>gtk.gdk.Window</classname></link> the
drag is moving over</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">protocol</parameter>&nbsp;:</term>
	  <listitem><simpara>the drag protocol in use</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">x_root</parameter>&nbsp;:</term>
	  <listitem><simpara>the x root coordinate of the mouse
pointer</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">y_root</parameter>&nbsp;:</term>
	  <listitem><simpara>the y root coordinate of the mouse
pointer</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter
role="keyword">suggested_action</parameter>&nbsp;:</term>
	  <listitem><simpara>the suggest drag action</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter
role="keyword">possible_actions</parameter>&nbsp;:</term>
	  <listitem><simpara>the possible drag actions</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">time</parameter>&nbsp;:</term>
	  <listitem><simpara>the timestamp of the drag
motion</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>True if there is a drag destination window and
the drag has paused or a drop has occurred.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>drag_motion</methodname>() method updates the
drag context when the pointer moves or the set of actions changes. This
method is called by the drag source. <parameter>dest_window</parameter>
specifies the drag destination <link
linkend="class-gdkwindow"><classname>gtk.gdk.Window</classname></link>;
<parameter>protocol</parameter> specifies the drag protocol being used (see
the <link
linkend="method-gdkdragcontext--drag-find-window"><methodname>drag_find_window</methodname>()</link> 
method for details); <parameter>x_root</parameter> and
<parameter>y_root</parameter> specify the root window coordinates of the
mouse pointer; <parameter>suggested_action</parameter> specifies the
suggested drag action (see the <link
linkend="method-gdkdragcontext--drag-status"><methodname>drag_status</methodname>()</link> 
method for more detail); possible_actions specifies the possible drag
actions for the drag (see  the <link
linkend="method-gdkdragcontext--drag-status"><methodname>drag_status</methodname>()</link> 
method for more detail); and, <parameter>time</parameter> specifies the
timestamp of the drag motion.</para>

    </refsect2>

    <refsect2 id="method-gdkdragcontext--drag-drop">
      <title>gtk.gdk.DragContext.drag_drop</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>drag_drop</methodname>
	  <methodparam><parameter
			 role="keyword">time</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">time</parameter>&nbsp;:</term>
	  <listitem><simpara>the timestamp of the drag
drop.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>drag_drop</methodname>() method initiates a drop
on the current drag destination at the time specified by
<parameter>time</parameter>. This method is called by the drag
source.</para>

    </refsect2>

    <refsect2 id="method-gdkdragcontext--drag-abort">
      <title>gtk.gdk.DragContext.drag_abort</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>drag_abort</methodname>
	  <methodparam><parameter
			 role="keyword">time</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">time</parameter>&nbsp;:</term>
	  <listitem><simpara>the time of the drag abort
operation</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>drag_abort</methodname>() method aborts the
current drag operation at the specified <parameter>time</parameter>. No drop
operation is initiated. This method is called by the drag source.</para>

    </refsect2>

    <refsect2 id="method-gdkdragcontext--finish">
      <title>gtk.gdk.DragContext.finish</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>finish</methodname>
	  <methodparam><parameter
			 role="keyword">success</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">del_</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">time</parameter></methodparam> 
</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">success</parameter>&nbsp;:</term>
	  <listitem><simpara>if <literal>True</literal> the drop was
completed</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">del_</parameter>&nbsp;:</term>
	  <listitem><simpara>if <literal>True</literal> the drag source
should delete the source data</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">time</parameter>&nbsp;:</term>
	  <listitem><simpara>the time of the drag finish
operation.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>finish</methodname>() method informs the drag
source that the drop is finished, and that the data of the drag will no
longer be required. If <parameter>success</parameter> is
<literal>True</literal> the drag drop completed successfully; if
<parameter>del_</parameter> is <literal>True</literal> the source data
should be deleted; <parameter>time</parameter> is the timestamp of the
finish operation. This method is called by the drag destination.</para>

    </refsect2>

    <refsect2 id="method-gdkdragcontext--get-source-widget">
      <title>gtk.gdk.DragContext.get_source_widget</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_source_widget</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the source <link
linkend="class-gtkwidget"><classname>gtk.Widget</classname></link> if the
drag is within the same  application or <literal>None</literal>
otherwise.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_source_widget</methodname>() method returns
the source <link
linkend="class-gtkwidget"><classname>gtk.Widget</classname></link> if the
drag is within the application; otherwise <literal>None</literal> is
returned.</para>

    </refsect2>

    <refsect2 id="method-gdkdragcontext--set-icon-widget">
      <title>gtk.gdk.DragContext.set_icon_widget</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_icon_widget</methodname>
	  <methodparam><parameter
			 role="keyword">widget</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">hot_x</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">hot_y</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">widget</parameter>&nbsp;:</term>
	  <listitem><simpara>a toplevel window to use as an
icon.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">hot_x</parameter>&nbsp;:</term>
	  <listitem><simpara>the X offset within
<parameter>widget</parameter> of the hotspot.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">hot_y</parameter>&nbsp;:</term>
	  <listitem><simpara>the Y offset within
<parameter>widget</parameter> of the hotspot.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_icon_widget</methodname>() method changes
the icon for a drag source to the specified <parameter>widget</parameter>
with its hot spot at the offset specified by <parameter>hot_x</parameter>
and <parameter>hot_y</parameter>. <literal>PyGTK</literal> 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>

    </refsect2>

    <refsect2 id="method-gdkdragcontext--set-icon-pixmap">
      <title>gtk.gdk.DragContext.set_icon_pixmap</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_icon_pixmap</methodname>
	  <methodparam><parameter
			 role="keyword">colormap</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">pixmap</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">mask</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">hot_x</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">hot_y</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">colormap</parameter>&nbsp;:</term>
	  <listitem><simpara>the colormap of the icon</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">pixmap</parameter>&nbsp;:</term>
	  <listitem><simpara>the <link
linkend="class-gdkpixmap"><classname>gtk.gdk.Pixmap</classname></link> image
data for the icon</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">mask</parameter>&nbsp;:</term>
	  <listitem><simpara>the <link
linkend="class-gdkpixmap"><classname>gtk.gdk.Pixmap</classname></link>
transparency mask for the icon</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">hot_x</parameter>&nbsp;:</term>
	  <listitem><simpara>the X offset within
<parameter>pixmap</parameter> of the hotspot.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">hot_y</parameter>&nbsp;:</term>
	  <listitem><simpara>the Y offset within
<parameter>pixmap</parameter> of the hotspot.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_icon_pixmap</methodname>() method sets
<parameter>pixmap</parameter> as the icon for the drag.
<parameter>mask</parameter> is a bitmap mask for
<parameter>pixmap</parameter> and <parameter>hot_x</parameter> and
<parameter>hot_y</parameter> specify the offset of the hot spot in
<parameter>pixmap</parameter>. In general, <link
linkend="method-gdkdragcontext--set-icon-pixbuf"><function>gtk.gdk.DragContext.set_icon_pixbuf()</function></link> 
will be more convenient to use.</para>

    </refsect2>

    <refsect2 id="method-gdkdragcontext--set-icon-pixbuf">
      <title>gtk.gdk.DragContext.set_icon_pixbuf</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_icon_pixbuf</methodname>
	  <methodparam><parameter
			 role="keyword">pixbuf</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">hot_x</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">hot_y</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">pixbuf</parameter>&nbsp;:</term>
	  <listitem><simpara>the <link
linkend="class-gdkpixbuf"><classname>gtk.gdk.Pixbuf</classname></link> to
use as the drag icon.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">hot_x</parameter>&nbsp;:</term>
	  <listitem><simpara>the X offset within
<parameter>pixbuf</parameter> of the hotspot.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">hot_y</parameter>&nbsp;:</term>
	  <listitem><simpara>the Y offset within
<parameter>pixbuf</parameter> of the hotspot.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_icon_pixbuf</methodname>() method sets
<parameter>pixbuf</parameter> as the icon for the drag.
<parameter>hot_x</parameter> and <parameter>hot_y</parameter> specify the
offset of the hot spot within <parameter>pixbuf</parameter>.</para>

    </refsect2>

    <refsect2 id="method-gdkdragcontext--set-icon-stock">
      <title>gtk.gdk.DragContext.set_icon_stock</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_icon_stock</methodname>
	  <methodparam><parameter
			 role="keyword">stock_id</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">hot_x</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">hot_y</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">stock_id</parameter>&nbsp;:</term>
	  <listitem><simpara>the ID of the stock icon to use for the
drag.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">hot_x</parameter>&nbsp;:</term>
	  <listitem><simpara>the X offset within the icon of the
hotspot.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">hot_y</parameter>&nbsp;:</term>
	  <listitem><simpara>the Y offset within the icon of the
hotspot.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_icon_stock</methodname>() method sets the
the icon for a given drag from a stock ID specified by
<parameter>stock_id</parameter>. <parameter>hot_x</parameter> and
<parameter>hot_y</parameter> specify the offset of the hot spot within the
stock icon.</para>

    </refsect2>

    <refsect2 id="method-gdkdragcontext--set-icon-name">
      <title>gtk.gdk.DragContext.set_icon_name</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_icon_name</methodname>
	  <methodparam><parameter
			 role="keyword">icon_name</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">hot_x</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">hot_y</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">icon_name</parameter>&nbsp;:</term>
	  <listitem><simpara>the name of the icon to use for the
drag.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">hot_x</parameter>&nbsp;:</term>
	  <listitem><simpara>the X offset within the icon of the
hotspot.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">hot_y</parameter>&nbsp;:</term>
	  <listitem><simpara>the Y offset within the icon of the
hotspot.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
        <para>This method is available in PyGTK 2.10 and above.</para>
      </note>

      <para>The <methodname>set_icon_name</methodname>() method sets the the
icon for a given drag from the named themed icon specified by
<parameter>icon_name</parameter>. <parameter>hot_x</parameter> and
<parameter>hot_y</parameter> specify the offset of the hot spot within the
stock icon. See the docs for <link
linkend="class-gtkicontheme"><classname>gtk.IconTheme</classname></link> for
more information. Note that the size of the icon depends on the icon theme
(the icon is loaded at the symbolic size
<literal>gtk.ICON_SIZE_DND</literal>), thus <parameter>hot_x</parameter> and
<parameter>hot_y</parameter> have to be used with care.</para>

    </refsect2>

  <refsect2 id="method-gdkdragcontext--set-icon-default">
      <title>gtk.gdk.DragContext.set_icon_default</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_icon_default</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>

      <para>The <methodname>set_icon_default</methodname>() method sets the
icon for the drag to the default icon.</para>

    </refsect2>

  <refsect2 id="method-gdkdragcontext--drag-drop-succeeded">
      <title>gtk.gdk.DragContext.drag_drop_succeeded</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>drag_drop_succeeded</methodname>
	  <methodparam></methodparam>
        </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>True</literal> if the drop was
successful.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>drag_drop_succeeded</methodname>() method
returns <literal>True</literal> if the dropped data has been successfully
transferred. This method is intended to be used while handling a
<literal>gtk.gdk.DROP_FINISHED</literal> event, its return value is
meaningless at other times.</para>

    </refsect2>

  </refsect1>

</refentry>
