Document the tree DND API.

Sun Feb 15 02:49:45 2004  Matthias Clasen  <maclas@gmx.de>

	* gtk/gtktreednd.c:
	* gtk/gtktreeview.c: Document the tree DND API.

	* gtk/gtktreeview.c (gtk_tree_view_unset_rows_drag_source):
	Call gtk_drag_source_unset().

ChangeLog

@@ -1,3 +1,11 @@
+Sun Feb 15 02:49:45 2004  Matthias Clasen  <maclas@gmx.de>
+
+	* gtk/gtktreednd.c: 
+	* gtk/gtktreeview.c: Document the tree DND API.
+
+	* gtk/gtktreeview.c (gtk_tree_view_unset_rows_drag_source): 
+	Call gtk_drag_source_unset().  
+	
 Sun Feb 15 00:49:59 2004  Matthias Clasen  <maclas@gmx.de>
 
 	* gtk/gtkcellrendererpixbuf.c (gtk_cell_renderer_pixbuf_class_init): 

ChangeLog.pre-2-10

@@ -1,3 +1,11 @@
+Sun Feb 15 02:49:45 2004  Matthias Clasen  <maclas@gmx.de>
+
+	* gtk/gtktreednd.c: 
+	* gtk/gtktreeview.c: Document the tree DND API.
+
+	* gtk/gtktreeview.c (gtk_tree_view_unset_rows_drag_source): 
+	Call gtk_drag_source_unset().  
+	
 Sun Feb 15 00:49:59 2004  Matthias Clasen  <maclas@gmx.de>
 
 	* gtk/gtkcellrendererpixbuf.c (gtk_cell_renderer_pixbuf_class_init): 

ChangeLog.pre-2-4

@@ -1,3 +1,11 @@
+Sun Feb 15 02:49:45 2004  Matthias Clasen  <maclas@gmx.de>
+
+	* gtk/gtktreednd.c: 
+	* gtk/gtktreeview.c: Document the tree DND API.
+
+	* gtk/gtktreeview.c (gtk_tree_view_unset_rows_drag_source): 
+	Call gtk_drag_source_unset().  
+	
 Sun Feb 15 00:49:59 2004  Matthias Clasen  <maclas@gmx.de>
 
 	* gtk/gtkcellrendererpixbuf.c (gtk_cell_renderer_pixbuf_class_init): 

ChangeLog.pre-2-6

@@ -1,3 +1,11 @@
+Sun Feb 15 02:49:45 2004  Matthias Clasen  <maclas@gmx.de>
+
+	* gtk/gtktreednd.c: 
+	* gtk/gtktreeview.c: Document the tree DND API.
+
+	* gtk/gtktreeview.c (gtk_tree_view_unset_rows_drag_source): 
+	Call gtk_drag_source_unset().  
+	
 Sun Feb 15 00:49:59 2004  Matthias Clasen  <maclas@gmx.de>
 
 	* gtk/gtkcellrendererpixbuf.c (gtk_cell_renderer_pixbuf_class_init): 

ChangeLog.pre-2-8

@@ -1,3 +1,11 @@
+Sun Feb 15 02:49:45 2004  Matthias Clasen  <maclas@gmx.de>
+
+	* gtk/gtktreednd.c: 
+	* gtk/gtktreeview.c: Document the tree DND API.
+
+	* gtk/gtktreeview.c (gtk_tree_view_unset_rows_drag_source): 
+	Call gtk_drag_source_unset().  
+	
 Sun Feb 15 00:49:59 2004  Matthias Clasen  <maclas@gmx.de>
 
 	* gtk/gtkcellrendererpixbuf.c (gtk_cell_renderer_pixbuf_class_init): 

docs/reference/ChangeLog

@@ -1,3 +1,7 @@
+Sun Feb 15 02:46:53 2004  Matthias Clasen  <maclas@gmx.de>
+
+	* gtk/tmpl/gtktreednd.sgml: Add docs.
+
 Sat Feb 14 03:09:49 2004  Matthias Clasen  <maclas@gmx.de>
 
 	* gtk/gtk-sections.txt: Remove duplicated section for

docs/reference/gtk/tmpl/gtktreednd.sgml

@@ -2,27 +2,82 @@
 GtkTreeView drag-and-drop
 
 <!-- ##### SECTION Short_Description ##### -->
-
+Interfaces for drag-and-drop support in GtkTreeView
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+GTK+ supports Drag-and-Drop in tree views with a high-level and a low-level 
+API.
+</para>
+<para>
+The low-level API consists of the GTK+ DND API, augmented by some treeview 
+utility functions: gtk_tree_view_set_drag_dest_row(),
+gtk_tree_view_get_drag_dest_row(), gtk_tree_view_get_dest_row_at_pos(), 
+gtk_tree_view_create_row_drag_icon(), gtk_tree_set_row_drag_data() and
+gtk_tree_get_row_drag_data(). This API leaves a lot of flexibility, but
+nothing is done automatically, and implementing advanced features like
+hover-to-open-rows or autoscrolling on top of this API is a lot of work.
+</para>
+<para>
+On the other hand, if you write to the high-level API, then all the 
+bookkeeping of rows is done for you, as well as things like hover-to-open 
+and auto-scroll, but your models have to implement the 
+#GtkTreeDragSource and #GtkTreeDragDest interfaces.
 </para>
-
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
 
 </para>
 
-
+<!-- ##### STRUCT GtkTreeDragSource ##### -->
-<!-- ##### STRUCT GtkTreeDragDest ##### -->
 <para>
 
 </para>
 
 
-<!-- ##### STRUCT GtkTreeDragSource ##### -->
+<!-- ##### STRUCT GtkTreeDragSourceIface ##### -->
+<para>
+
+</para>
+
+@g_iface: 
+@row_draggable: 
+@drag_data_get: 
+@drag_data_delete: 
+
+<!-- ##### FUNCTION gtk_tree_drag_source_drag_data_delete ##### -->
+<para>
+
+</para>
+
+@drag_source: 
+@path: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gtk_tree_drag_source_drag_data_get ##### -->
+<para>
+
+</para>
+
+@drag_source: 
+@path: 
+@selection_data: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gtk_tree_drag_source_row_draggable ##### -->
+<para>
+
+</para>
+
+@drag_source: 
+@path: 
+@Returns: 
+
+
+<!-- ##### STRUCT GtkTreeDragDest ##### -->
 <para>
 
 </para>
@@ -37,13 +92,47 @@ GtkTreeView drag-and-drop
 @drag_data_received: 
 @row_drop_possible: 
 
-<!-- ##### STRUCT GtkTreeDragSourceIface ##### -->
+<!-- ##### FUNCTION gtk_tree_drag_dest_drag_data_received ##### -->
 <para>
 
 </para>
 
-@g_iface: 
+@drag_dest: 
-@row_draggable: 
+@dest: 
-@drag_data_get: 
+@selection_data: 
-@drag_data_delete: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gtk_tree_drag_dest_row_drop_possible ##### -->
+<para>
+
+</para>
+
+@drag_dest: 
+@dest_path: 
+@selection_data: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gtk_tree_set_row_drag_data ##### -->
+<para>
+
+</para>
+
+@selection_data: 
+@tree_model: 
+@path: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gtk_tree_get_row_drag_data ##### -->
+<para>
+
+</para>
+
+@selection_data: 
+@tree_model: 
+@path: 
+@Returns: 
+
 

gtk/gtktreednd.c

@@ -186,7 +186,7 @@ gtk_tree_drag_dest_drag_data_received (GtkTreeDragDest  *drag_dest,
 
 
 /**
- * gtk_tree_drag_dest_drop_possible:
+ * gtk_tree_drag_dest_row_drop_possible:
  * @drag_dest: a #GtkTreeDragDest
  * @dest_path: destination row
  * @selection_data: the data being dragged

gtk/gtktreeview.c

@@ -10914,6 +10914,17 @@ unset_reorderable (GtkTreeView *tree_view)
     }
 }
 
+/**
+ * gtk_tree_view_enable_model_drag_source:
+ * @tree_view: a #GtkTreeView
+ * @start_button_mask: Mask of allowed buttons to start drag
+ * @targets: the table of targets that the drag will support
+ * @n_targets: the number of items in @targets
+ * @actions: the bitmask of possible actions for a drag from this
+ *    widget
+ * 
+ * Turns @tree_view into a drag source for automatic DND.
+ **/
 void
 gtk_tree_view_enable_model_drag_source (GtkTreeView              *tree_view,
 					GdkModifierType           start_button_mask,
@@ -10943,6 +10954,16 @@ gtk_tree_view_enable_model_drag_source (GtkTreeView              *tree_view,
   unset_reorderable (tree_view);
 }
 
+/**
+ * gtk_tree_view_enable_model_drag_dest:
+ * @tree_view: a #GtkTreeView
+ * @targets: the table of targets that the drag will support
+ * @n_targets: the number of items in @targets
+ * @actions: the bitmask of possible actions for a drag from this
+ *    widget
+ * 
+ * Turns @tree_view into a drop destination for automatic DND.
+ **/
 void
 gtk_tree_view_enable_model_drag_dest (GtkTreeView              *tree_view,
 				      const GtkTargetEntry     *targets,
@@ -10970,6 +10991,12 @@ gtk_tree_view_enable_model_drag_dest (GtkTreeView              *tree_view,
   unset_reorderable (tree_view);
 }
 
+/**
+ * gtk_tree_view_unset_rows_drag_source:
+ * @tree_view: a #GtkTreeView
+ * 
+ * Undoes the effect of gtk_tree_view_enable_model_drag_source().
+ **/
 void
 gtk_tree_view_unset_rows_drag_source (GtkTreeView *tree_view)
 {
@@ -10983,6 +11010,7 @@ gtk_tree_view_unset_rows_drag_source (GtkTreeView *tree_view)
     {
       if (di->source_set)
         {
+          gtk_drag_source_unset (GTK_WIDGET (tree_view));
           clear_source_info (di);
           di->source_set = FALSE;
         }
@@ -10994,6 +11022,12 @@ gtk_tree_view_unset_rows_drag_source (GtkTreeView *tree_view)
   unset_reorderable (tree_view);
 }
 
+/**
+ * gtk_tree_view_unset_rows_drag_dest:
+ * @tree_view: a #GtkTreeView
+ * 
+ * Undoes the effect of gtk_tree_view_enable_model_drag_dest().
+ **/
 void
 gtk_tree_view_unset_rows_drag_dest (GtkTreeView *tree_view)
 {
@@ -11019,6 +11053,14 @@ gtk_tree_view_unset_rows_drag_dest (GtkTreeView *tree_view)
   unset_reorderable (tree_view);
 }
 
+/**
+ * gtk_tree_view_set_drag_dest_row:
+ * @tree_view: a #GtkTreeView
+ * @path: The path of the row to highlight, or %NULL.
+ * @pos: Specifies whether to drop before, after or into the row
+ * 
+ * Sets the row that is highlighted for feedback.
+ **/
 void
 gtk_tree_view_set_drag_dest_row (GtkTreeView            *tree_view,
                                  GtkTreePath            *path,
@@ -11089,6 +11131,14 @@ gtk_tree_view_set_drag_dest_row (GtkTreeView            *tree_view,
     }
 }
 
+/**
+ * gtk_tree_view_get_drag_dest_row:
+ * @tree_view: a #GtkTreeView
+ * @path: Return location for the path of the highlighted row, or %NULL.
+ * @pos: Return location for the drop position, or %NULL
+ * 
+ * Gets information about the row that is highlighted for feedback.
+ **/
 void
 gtk_tree_view_get_drag_dest_row (GtkTreeView              *tree_view,
                                  GtkTreePath             **path,
@@ -11113,6 +11163,18 @@ gtk_tree_view_get_drag_dest_row (GtkTreeView              *tree_view,
     *pos = tree_view->priv->drag_dest_pos;
 }
 
+/**
+ * gtk_tree_view_get_dest_row_at_pos:
+ * @tree_view: a #GtkTreeView
+ * @drag_x: the position to determine the destination row for
+ * @drag_y: the position to determine the destination row for
+ * @path: Return location for the path of the highlighted row, or %NULL.
+ * @pos: Return location for the drop position, or %NULL
+ * 
+ * Determines the destination row for a given position.
+ * 
+ * Return value: whether there is a row at the given postiion,
+ **/
 gboolean
 gtk_tree_view_get_dest_row_at_pos (GtkTreeView             *tree_view,
                                    gint                     drag_x,