DND updates

Wed Nov 29 13:39:19 GMT 2000  Tony Gale <gale@gtk.org>

	* docs/tutorial/gtk-tut.sgml: DND updates

1 files changed, 82 insertions, 27 deletions

diff --git a/docs/tutorial/gtk-tut.sgml b/docs/tutorial/gtk-tut.sgml
index 2eb1cbe7e..c4e222202 100755
--- a/docs/tutorial/gtk-tut.sgml
+++ b/docs/tutorial/gtk-tut.sgml
@@ -12778,24 +12778,25 @@ int main( int   argc,
 
 <!-- ***************************************************************** -->
 <chapter id="ch-DragAngDrop">
-<title>Drag and Drop (DND)</title>
+<title>Drag-and-drop (DND)</title>
 
-<para>GTK+ has a high level set of functions for doing inter-window
-communication using the drag and drop system on top of the low level
-Xdnd and Motif protocols.</para>
+<para>GTK+ has a high level set of functions for doing inter-process
+communication via the drag-and-drop system. GTK+ can perform
+drag-and-drop on top of the low level Xdnd and Motif drag-and-drop
+protocols.</para>
 
 <!-- ----------------------------------------------------------------- -->
 <sect1 id="sec-DragAndDropOverview">
 <title>Overview</title>
 
-<para>An application capable of GTK+ drag and drop first defines and sets up
-the GTK+ widget(s) for drag and drop. Each widget can be a source
-and/or destination for drag and drop. Note that these GTK+ widgets must have
-an associated X Window, check using GTK_WIDGET_NO_WINDOW(wid)).</para>
+<para>An application capable of GTK+ drag-and-drop first defines and sets up
+the GTK+ widget(s) for drag-and-drop. Each widget can be a source
+and/or destination for drag-and-drop. Note that these GTK+ widgets must have
+an associated X Window, check using GTK_WIDGET_NO_WINDOW(widget)).</para>
 
 <para>Source widgets can send out drag data, thus allowing the user to drag
 things off of them, while destination widgets can receive drag data.
-Drag and drop destinations can limit who they accept drag data from,
+Drag-and-drop destinations can limit who they accept drag data from,
 e.g. the same application or any application (including itself).</para>
 
 <para>Sending and receiving drop data makes use of GTK+ signals.
@@ -12803,7 +12804,7 @@ Dropping an item to a destination widget requires both a data
 request (for the source widget) and data received signal handler (for
 the target widget). Additional signal handers can be connected if you
 want to know when a drag begins (at the very instant it starts), to
-when a drop is made, and when the entire drag and drop procedure has
+when a drop is made, and when the entire drag-and-drop procedure has
 ended (successfully or not).</para>
 
 <para>Your application will need to provide data for source widgets when
@@ -12811,7 +12812,7 @@ requested, that involves having a drag data request signal handler. For
 destination widgets they will need a drop data received signal
 handler. </para>
 
-<para>So a typical drag and drop cycle would look as follows:</para>
+<para>So a typical drag-and-drop cycle would look as follows:</para>
 <orderedlist>
 <listitem><simpara> Drag begins.</simpara>
 </listitem>
@@ -12822,7 +12823,7 @@ application).</simpara>
 </listitem>
 <listitem><simpara> Drag data delete (if the drag was a move).</simpara>
 </listitem>
-<listitem><simpara> Drag and drop procedure done.</simpara>
+<listitem><simpara> Drag-and-drop procedure done.</simpara>
 </listitem>
 </orderedlist>
 
@@ -12841,8 +12842,7 @@ will get into detail about that later.</para>
 <listitem><simpara> Drag action type (ie GDK_ACTION_COPY, GDK_ACTION_MOVE).</simpara>
 </listitem>
 
-<listitem><simpara> Client specified arbitrary drag and drop type (a
-gchar *name and a gint info id number pair).</simpara>
+<listitem><simpara> Client specified arbitrary drag-and-drop type (a name and number pair).</simpara>
 </listitem>
 
 <listitem><simpara> Sent and received data format type.</simpara>
@@ -12851,17 +12851,17 @@ gchar *name and a gint info id number pair).</simpara>
 
 <para>Drag actions are quite obvious, they specify if the widget can
 drag with the specified action(s), e.g. GDK_ACTION_COPY and/or
-GDK_ACTION_MOVE. A GDK_ACTION_COPY would be a typical drag and drop
+GDK_ACTION_MOVE. A GDK_ACTION_COPY would be a typical drag-and-drop
 without the source data being deleted while GDK_ACTION_MOVE would be
 just like GDK_ACTION_COPY but the source data will be 'suggested' to be
 deleted after the received signal handler is called. There are
 additional drag actions including GDK_ACTION_LINK which you may want to
-look into when you get to more advanced levels of drag and drop.</para>
+look into when you get to more advanced levels of drag-and-drop.</para>
 
-<para>The client specified arbitrary drag and drop type is much more
+<para>The client specified arbitrary drag-and-drop type is much more
 flexible, because your application will be defining and checking for
 that specifically. You will need to set up your destination widgets to
-receive certain drag and drop types by specifying a name and/or number.
+receive certain drag-and-drop types by specifying a name and/or number.
 It would be more reliable to use a name since another application may
 just happen to use the same number for an entirely different
 meaning.</para>
@@ -12884,18 +12884,66 @@ received.</para>
 <sect1 id="sec-DragAndDropFunctions">
 <title>Functions</title>
 
-<para>Setting up source widget:</para>
+<sect2 id="sec-DNDSourceWidgets">
+<title>Setting up the source widget</title>
 
+<para>The function <literal>gtk_drag_source_set()</literal> specifies a
+set of target types for a drag operation on a widget.</para>
+
+<programlisting role="C">
+void gtk_drag_source_set( GtkWidget            *widget,
+                          GdkModifierType       start_button_mask,
+                          const GtkTargetEntry *targets,
+                          gint                  n_targets,
+                          GdkDragAction         actions );
+</programlisting>
+
+<para>The parameters signify the following:</para>
 <itemizedlist>
-<listitem><simpara> <literal>gtk_drag_source_set()</literal> specifies a
-set of target types for a drag operation on a widget.</simpara>
+<listitem><simpara><literal>widget</literal> specifies the drag source
+widget</simpara>
+</listitem>
+<listitem><simpara><literal>start_button_mask</literal> specifies a
+bitmask of buttons that can start the drag (e.g. GDK_BUTTON1_MASK)</simpara>
+</listitem>
+<listitem><simpara><literal>targets</literal> specifies a table of
+target data types the drag will support</simpara>
+</listitem>
+<listitem><simpara><literal>n_targets</literal> specifies the number of
+targets above</simpara>
+</listitem>
+<listitem><simpara><literal>actions</literal> specifies a bitmask of
+possible actions for a drag from this window</simpara>
 </listitem>
-<listitem><simpara> <literal>gtk_drag_source_unset()</literal> specifies
-that the widget is to no longer perform drag operations.</simpara>
-</listitem> 
 </itemizedlist>
 
-<para>Signals on the source widget:</para>
+<para>The <literal>targets</literal> parameter is an array of the
+following structure:</para>
+
+<programlisting role="C">
+struct GtkTargetEntry {
+   gchar *target;
+   guint  flags;
+   guint  info;
+ };
+</programlisting>
+
+<para>The fields specify a string representing the drag type, optional
+flags and application assigned integer identifier.</para>
+
+<para>If a widget is no longer required to act as a source for
+drag-and-drop operations, the function
+<literal>gtk_drag_source_unset()</literal> can be used to remove a set
+of drag-and-drop target types.</para>
+
+<programlisting role="C">
+void gtk_drag_source_unset( GtkWidget *widget );
+</programlisting>
+
+</sect2>
+
+<sect2 id="sec-SignalsOnSourceWidgets">
+<title>Signals on the source widget:</title>
 
 <itemizedlist>
 <listitem><simpara> drag_begin - prototype: void (*drag_begin)(GtkWidget
@@ -12922,7 +12970,10 @@ that the widget is to no longer perform drag operations.</simpara>
 </listitem>
 </itemizedlist>
 
-<para>Setting up destination widget:</para>
+</sect2>
+
+<sect2 id="sec-DNDDestWidgets">
+<title>Setting up a destination widget:</title>
 
 <itemizedlist>
 <listitem><simpara> <literal> gtk_drag_dest_set()</literal> specifies
@@ -12935,7 +12986,10 @@ that the widget can no longer recieve drops.</simpara>
 </listitem>
 </itemizedlist>
 
-<para>Signals on the destination widget:</para>
+</sect2>
+
+<sect2 id="sec-SignalsOnDestWidgets">
+<title>Signals on the destination widget:</title>
 
 <itemizedlist>
 <listitem><simpara> drag_data_received - prototype: void (*drag_data_received)(GtkWidget *widget, GdkDragContext
@@ -12943,6 +12997,7 @@ that the widget can no longer recieve drops.</simpara>
 </listitem>
 </itemizedlist>
 
+</sect2>
 </sect1>
 </chapter>