[pygtk] Reword the description of the use of the new_order list in the

[John Finlay <finlay src gnome org>]

commit ca098328aaf0e3f48ddb08a24b58391e42484837
Author: John Finlay <finlay moeraki com>
Date:   Mon Jul 20 00:27:12 2009 -0700

    Reword the description of the use of the new_order list in the
    gtk.TreeModel.rows_reordered, gtk.TreeStore.reorder and gtk.ListStore.reorder
    methods.

 docs/reference/pygtk-gtkliststore.xml |   26 ++++++++++++++++++--------
 docs/reference/pygtk-gtktreemodel.xml |   33 +++++++++++++++++++--------------
 docs/reference/pygtk-gtktreestore.xml |   24 ++++++++++++++++--------
 3 files changed, 53 insertions(+), 30 deletions(-)
---
diff --git a/docs/reference/pygtk-gtkliststore.xml b/docs/reference/pygtk-gtkliststore.xml
index 6f5aeec..46b2dc5 100644
--- a/docs/reference/pygtk-gtkliststore.xml
+++ b/docs/reference/pygtk-gtkliststore.xml
@@ -747,10 +747,14 @@ linkend="class-gtkliststore"><classname>gtk.ListStore</classname></link>.</para>
       <variablelist>
 	<varlistentry>
 	  <term><parameter>new_order</parameter>&nbsp;:</term>
-	  <listitem><simpara>a list of integers mapping the new position of
-	  each child to its old position before the re-ordering,
-	  i.e. <parameter>new_order</parameter><literal>[newpos] =
-	  oldpos</literal>.</simpara></listitem>
+	  <listitem><simpara>a list of integers. The <link
+	  linkend="class-gtkliststore"><classname>gtk.ListStore</classname></link>
+	  nodes will be rearranged so that the <link
+	  linkend="class-gtkliststore"><classname>gtk.ListStore</classname></link>
+	  node that is at position index
+	  <parameter>new_order</parameter><literal>[i]</literal> will be
+	  located at position index
+	  <literal>i</literal>.</simpara></listitem>
 	</varlistentry>
       </variablelist>
 
@@ -759,10 +763,16 @@ linkend="class-gtkliststore"><classname>gtk.ListStore</classname></link>.</para>
       </note>
 
       <para>The <methodname>reorder</methodname>() method reorders the <link
-linkend="class-gtkliststore"><classname>gtk.ListStore</classname></link>
-items to follow the order indicated by
-<parameter>new_order</parameter>. Note that this method only works with
-unsorted stores.</para>
+      linkend="class-gtkliststore"><classname>gtk.ListStore</classname></link>
+      items to follow the order indicated by
+      <parameter>new_order</parameter>. The <link
+      linkend="class-gtkliststore"><classname>gtk.ListStore</classname></link>
+      nodes will be rearranged so that the <link
+      linkend="class-gtkliststore"><classname>gtk.ListStore</classname></link>
+      node that is at position index
+      <parameter>new_order</parameter><literal>[i]</literal> will be located
+      at position index <literal>i</literal>. Note that this method only
+      works with unsorted stores.</para>
 
     </refsect2>
 
diff --git a/docs/reference/pygtk-gtktreemodel.xml b/docs/reference/pygtk-gtktreemodel.xml
index 66b4a1b..9abc3ae 100644
--- a/docs/reference/pygtk-gtktreemodel.xml
+++ b/docs/reference/pygtk-gtktreemodel.xml
@@ -1207,10 +1207,12 @@ at. It may not be a valid location anymore.</para>
 	<varlistentry>
 	  <term><parameter
 role="keyword">new_order</parameter>&nbsp;:</term>
-	  <listitem><simpara>a sequence of integers containing the new
-indexes of the children, i.e. the former child <literal>n</literal> is now
-at the position specified by
-<parameter>new_order</parameter><literal>[n]</literal>.</simpara></listitem>
+	  <listitem><simpara>a sequence of integers containing the old
+	  indexes of the children in the new order, i.e. the child nodes
+	  have been rearranged so that the <parameter>treemodel</parameter>
+	  node that was at position index
+	  <parameter>new_order</parameter><literal>[i]</literal> is now at
+	  position index <literal>i</literal>.</simpara></listitem>
 	</varlistentry>
       </variablelist>
 
@@ -1565,16 +1567,19 @@ any)</simpara></listitem>
       </variablelist>
 
       <para>The "rows-reordered" signal is emitted when the
-<parameter>treemodel</parameter> child rows of the row specified by
-<parameter>path</parameter> and pointed to by <parameter>iter</parameter>
-are reordered. <parameter>new_order</parameter> is an array of node index
-numbers representing the new order of the rows. The value of
-<parameter>new_order</parameter> cannot be retrieved in PyGTK because it is
-passed as an opaque pointer (<link
-linkend="class-gobjectgpointer"><classname>gobject.GPointer</classname></link>)
-value. <parameter>iter</parameter> may be <literal>None</literal> and
-<parameter>path</parameter> an empty tuple to indicate that the top level
-rows were reordered.</para>
+      <parameter>treemodel</parameter> child rows of the row specified by
+      <parameter>path</parameter> and pointed to by
+      <parameter>iter</parameter> are reordered. The child nodes have been
+      rearranged so that the <parameter>treemodel</parameter> node that was
+      at position index
+      <parameter>new_order</parameter><literal>[i]</literal> is now at
+      position index <literal>i</literal>. The value of
+      <parameter>new_order</parameter> cannot be directly retrieved in PyGTK
+      because it is passed as an opaque pointer (<link
+      linkend="class-gobjectgpointer"><classname>gobject.GPointer</classname></link>)
+      value. <parameter>iter</parameter> may be <literal>None</literal> and
+      <parameter>path</parameter> an empty tuple to indicate that the top
+      level rows were reordered.</para>
 
     </refsect2>
 
diff --git a/docs/reference/pygtk-gtktreestore.xml b/docs/reference/pygtk-gtktreestore.xml
index 6c7eef9..d19f128 100644
--- a/docs/reference/pygtk-gtktreestore.xml
+++ b/docs/reference/pygtk-gtktreestore.xml
@@ -763,10 +763,13 @@ testing purposes.</para>
 	<varlistentry>
 	  <term><parameter
 	  role="keyword">new_order</parameter>&nbsp;:</term>
-	  <listitem><simpara>a list of integers mapping the new position of
-	  each child to its old position before the re-ordering,
-	  i.e. <parameter>new_order</parameter><literal>[newpos] =
-	  oldpos</literal>.</simpara></listitem>
+	  <listitem><simpara>a list of integers. The child nodes will be
+	  rearranged so that the <link
+	  linkend="class-gtktreestore"><classname>gtk.TreeStore</classname></link>
+	  node that is at position index
+	  <parameter>new_order</parameter><literal>[i]</literal> will be
+	  located at position index
+	  <literal>i</literal>.</simpara></listitem>
 	</varlistentry>
       </variablelist>
 
@@ -775,10 +778,15 @@ testing purposes.</para>
       </note>
 
       <para>The <methodname>reorder</methodname>() method reorders the
-children of the tree store node pointed to by <parameter>parent</parameter>
-to match the order of the list of row numbers contained in
-<parameter>new_order</parameter>. Note that this method only works with
-unsorted stores.</para>
+      children of the tree store node pointed to by
+      <parameter>parent</parameter> to match the order of the list of row
+      numbers contained in <parameter>new_order</parameter>. The child nodes
+      will be rearranged so that the <link
+      linkend="class-gtktreestore"><classname>gtk.TreeStore</classname></link>
+      node that is at position index
+      <parameter>new_order</parameter><literal>[i]</literal> will be located
+      at position index <literal>i</literal>. Note that this method only
+      works with unsorted stores.</para>
 
     </refsect2>