diff options
Diffstat (limited to 'docs/reference/pygtk-gtktreesortable.xml')
| -rw-r--r-- | docs/reference/pygtk-gtktreesortable.xml | 402 |
1 files changed, 0 insertions, 402 deletions
diff --git a/docs/reference/pygtk-gtktreesortable.xml b/docs/reference/pygtk-gtktreesortable.xml deleted file mode 100644 index e8b2a2bd..00000000 --- a/docs/reference/pygtk-gtktreesortable.xml +++ /dev/null @@ -1,402 +0,0 @@ -<?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-gtktreesortable"> - <refnamediv> - <refname>gtk.TreeSortable</refname> - <refpurpose>an interface for sorting a <link -linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link></refpurpose> - </refnamediv> - - <refsect1> - <title>Synopsis</title> - - <classsynopsis language="python"> - <ooclass><classname>gtk.TreeSortable</classname></ooclass> - <ooclass><classname>gobject.GInterface</classname></ooclass> - <methodsynopsis language="python"> - <methodname><link -linkend="method-gtktreesortable--sort-column-changed">sort_column_changed</link></methodname> - <methodparam></methodparam> </methodsynopsis> - <methodsynopsis language="python"> - <methodname><link -linkend="method-gtktreesortable--get-sort-column-id">get_sort_column_id</link></methodname> - <methodparam></methodparam> - </methodsynopsis> - <methodsynopsis language="python"> - <methodname><link -linkend="method-gtktreesortable--set-sort-column-id">set_sort_column_id</link></methodname> - <methodparam><parameter - role="keyword">sort_column_id</parameter></methodparam> - <methodparam><parameter - role="keyword">order</parameter></methodparam> - </methodsynopsis> - <methodsynopsis language="python"> - <methodname><link -linkend="method-gtktreesortable--set-sort-func">set_sort_func</link></methodname> - <methodparam><parameter>sort_column_id</parameter></methodparam> - <methodparam><parameter>sort_func</parameter></methodparam> - <methodparam><parameter>user_data</parameter> - <initializer>None</initializer></methodparam> - </methodsynopsis> - <methodsynopsis language="python"> - <methodname><link -linkend="method-gtktreesortable--set-default-sort-func">set_default_sort_func</link></methodname> - <methodparam><parameter>sort_func</parameter></methodparam> - <methodparam><parameter>user_data</parameter> - <initializer>None</initializer></methodparam> - </methodsynopsis> - <methodsynopsis language="python"> - <methodname><link -linkend="method-gtktreesortable--has-default-sort-func">has_default_sort_func</link></methodname> - <methodparam></methodparam> </methodsynopsis> - </classsynopsis> - - </refsect1> - - <refsect1 id="signal-prototypes-gtktreesortable"> - <title>gtk.TreeSortable Signal Prototypes</title> - - <variablelist> - <varlistentry> - <term>"<link -linkend="signal-gtktreesortable--sort-column-changed">sort-column-changed</link>"</term> - <listitem> - <methodsynopsis - language="python"><methodname>callback</methodname> - <methodparam><parameter>treesortable</parameter></methodparam> - <methodparam><parameter>user_param1</parameter></methodparam> - <methodparam><parameter>...</parameter></methodparam> - </methodsynopsis> - </listitem> - </varlistentry> - </variablelist> - - </refsect1> - - <refsect1> - <title>Description</title> - - <para>The <link -linkend="class-gtktreesortable"><classname>gtk.TreeSortable</classname></link> -interface provide the common methods for a <link -linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link> to -implement a sorted model for a <link -linkend="class-gtktreeview"><classname>gtk.TreeView</classname></link>. See -the <link -linkend="class-gtktreemodelsort"><classname>gtk.TreeModelSort</classname></link> -for an example of a treemodel that implements the <link -linkend="class-gtktreesortable"><classname>gtk.TreeSortable</classname></link> -interface. The key element of the interface is a "sort column ID" which is -an arbitrary integer value referring to a sort function and associated user -data. A sort column ID must be greater than or equal to zero. A usable sort -column ID is created by using the <link -linkend="method-gtktreesortable--set-sort-func"><methodname>set_sort_func</methodname>()</link> -method. The sort column ID can then be used for sorting a <link -linkend="class-gtkliststore"><classname>gtk.ListStore</classname></link> or -<link -linkend="class-gtktreestore"><classname>gtk.TreeStore</classname></link> -using the <link -linkend="method-gtktreesortable--set-sort-column-id"><methodname>set_sort_column_id</methodname>()</link> -method.</para> - - <para>The <link -linkend="class-gtkliststore"><classname>gtk.ListStore</classname></link> and -<link -linkend="class-gtktreestore"><classname>gtk.TreeStore</classname></link> -objects automatically setup sort column IDs corresponding to the columns in -the store. These sort column IDs are associated with an internal comparison -function that handles the fundamental types:</para> - - <itemizedlist> - <listitem> - <simpara>gboolean</simpara> - </listitem> - <listitem> - <simpara>str</simpara> - </listitem> - <listitem> - <simpara>int</simpara> - </listitem> - <listitem> - <simpara>long</simpara> - </listitem> - <listitem> - <simpara>float</simpara> - </listitem> - </itemizedlist> - - <note> - <para>Once a sort column ID has been set on a <link -linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link> -implementing the <link -linkend="class-gtktreesortable"><classname>gtk.TreeSortable</classname></link> -interface it cannot be returned to the original unsorted state. You can -change the sort function or use a default sort function but you cannot set -the <link -linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link> to -have no sort function.</para> - </note> - - </refsect1> - - <refsect1> - <title>Methods</title> - - <refsect2 id="method-gtktreesortable--sort-column-changed"> - <title>gtk.TreeSortable.sort_column_changed</title> - - <programlisting><methodsynopsis language="python"> - <methodname>sort_column_changed</methodname> - <methodparam></methodparam> </methodsynopsis></programlisting> - - <para>The <methodname>sort_column_changed</methodname>() method emits -the "sort_column_changed" signal on the treesortable object.</para> - - </refsect2> - - <refsect2 id="method-gtktreesortable--get-sort-column-id"> - <title>gtk.TreeSortable.get_sort_column_id</title> - - <programlisting><methodsynopsis language="python"> - <methodname>get_sort_column_id</methodname> - <methodparam></methodparam> - </methodsynopsis></programlisting> - <variablelist> - <varlistentry> - <term><emphasis>Returns</emphasis> :</term> - <listitem><simpara>a tuple containing the sort column id and the -sort type: <literal>gtk.SORT_ASCENDING</literal> or -<literal>gtk.SORT_DESCENDING</literal></simpara></listitem> - </varlistentry> - </variablelist> - - <para>The <methodname>get_sort_column_id</methodname>() method returns -a tuple containing the current sort column ID and the sort type (either -<literal>gtk.SORT_ASCENDING</literal> or -<literal>gtk.SORT_DESCENDING</literal>), if applicable. If the sort column -ID is not set, then the tuple <literal>(-2, 0)</literal> is returned. If the -sort column ID is set to -1 indicating the default sort function is to be -used this method returns (<literal>None</literal>, -<literal>None</literal>)</para> - - </refsect2> - - <refsect2 id="method-gtktreesortable--set-sort-column-id"> - <title>gtk.TreeSortable.set_sort_column_id</title> - - <programlisting><methodsynopsis language="python"> - <methodname>set_sort_column_id</methodname> - <methodparam><parameter - role="keyword">sort_column_id</parameter></methodparam> - <methodparam><parameter - role="keyword">order</parameter></methodparam> - </methodsynopsis></programlisting> - <variablelist> - <varlistentry> - <term><parameter -role="keyword">sort_column_id</parameter> :</term> - <listitem><simpara>the sort column id to set</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter role="keyword">order</parameter> :</term> - <listitem><simpara>the sort order: - <literal>gtk.SORT_ASCENDING</literal> or - <literal>gtk.SORT_DESCENDING</literal></simpara></listitem> - </varlistentry> - </variablelist> - - <para>The <methodname>set_sort_column_id</methodname>() method sets -the current sort comparison function to that associated with the sort column -ID specified by <parameter>sort_column_id</parameter> with the sort order -type specified by <parameter>order</parameter>. The value of order must be -either: <literal>gtk.SORT_ASCENDING</literal> or -<literal>gtk.SORT_DESCENDING</literal>. The treesortable will resort itself -to reflect this change, after emitting a "sort_column_changed" signal.</para> - - <para>If <parameter>sort_column_id</parameter> is -1, then the default -sort function will be used, if it is set. If a default sort function is not -set then the sort column ID is not changed.</para> - - </refsect2> - - <refsect2 id="method-gtktreesortable--set-sort-func"> - <title>gtk.TreeSortable.set_sort_func</title> - - <programlisting><methodsynopsis language="python"> - <methodname>set_sort_func</methodname> - <methodparam><parameter>sort_column_id</parameter></methodparam> - <methodparam><parameter>sort_func</parameter></methodparam> - <methodparam><parameter>user_data</parameter> - <initializer>None</initializer></methodparam> - </methodsynopsis></programlisting> - <variablelist> - <varlistentry> - <term><parameter>sort_column_id</parameter> :</term> - <listitem><simpara>the sort column id to set the function -for</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>sort_func</parameter> :</term> - <listitem><simpara>The sorting function</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>the user data to pass to the sort func, or -<literal>None</literal></simpara></listitem> - </varlistentry> - </variablelist> - - <para>The <methodname>set_sort_func</methodname>() method sets the -comparison function (or method) used when sorting on the sort column ID -specified by <parameter>column_id</parameter> to the value specified by -<parameter>sort_func</parameter>. If the current sort column id of the -treesortable is the same as <parameter>sort_column_id</parameter>, the model -will be resorted. The signature of the comparison function (or method) -is:</para> - - <programlisting> -<methodsynopsis language="python"> - <methodname>comparefunction</methodname> - <methodparam><parameter>treemodel</parameter></methodparam> - <methodparam><parameter>iter1</parameter></methodparam> - <methodparam><parameter>iter2</parameter></methodparam> - <methodparam><parameter>user_data</parameter></methodparam> - </methodsynopsis> -<methodsynopsis language="python"> - <methodname>comparemethod</methodname> - <methodparam><parameter>self</parameter></methodparam> - <methodparam><parameter>treemodel</parameter></methodparam> - <methodparam><parameter>iter1</parameter></methodparam> - <methodparam><parameter>iter2</parameter></methodparam> - <methodparam><parameter>user_data</parameter></methodparam> - </methodsynopsis> -</programlisting> - - <para>where <parameter>treemodel</parameter> is the tree model -implementing the <link -linkend="class-gtktreesortable"><classname>gtk.TreeSortable</classname></link> -interface, <parameter>iter1</parameter> and <parameter>iter2</parameter> -point at the rows to compare and <parameter>user_data</parameter> is the -user data specified in <methodname>set_sort_func</methodname>() or -<parameter>None</parameter>. If <parameter>sort_func</parameter> is a method -then <parameter>self</parameter> is the object associated with the -method.</para> - - <para>The comparison callback should return -1 if the -<parameter>iter1</parameter> row should come before the -<parameter>iter2</parameter> row, 0 if the rows are equal, or 1 if the -<parameter>iter1</parameter> row should come after the -<parameter>iter2</parameter> row.</para> - - </refsect2> - - <refsect2 id="method-gtktreesortable--set-default-sort-func"> - <title>gtk.TreeSortable.set_default_sort_func</title> - - <programlisting><methodsynopsis language="python"> - <methodname>set_default_sort_func</methodname> - <methodparam><parameter>sort_func</parameter></methodparam> - <methodparam><parameter>user_data</parameter> - <initializer>None</initializer></methodparam> - </methodsynopsis></programlisting> - <variablelist> - <varlistentry> - <term><parameter>sort_func</parameter> :</term> - <listitem><simpara>the sorting function</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>the user data to pass to -<parameter>sort_func</parameter>, or -<literal>None</literal></simpara></listitem> - </varlistentry> - </variablelist> - - <para>The <methodname>set_default_sort_func</methodname>() method sets -the default comparison function (or method) to the value of -<parameter>sort_func</parameter>. If the current sort column id of the -treesortable is -1 (the <link -linkend="method-gtktreesortable--get-sort-column-id"><methodname>get_sort_column_id</methodname>()</link> -method returns (None, None)), then the model will be resorted using the -<parameter>sort_func</parameter>. See the <link -linkend="method-gtktreesortable--set-sort-func"><methodname>set_sort_func</methodname>()</link> -method for more details on the signature of the comparison function.</para> - -<para>In Pygtk 2.10, <parameter>sort_func</parameter> can be -<literal>None</literal> to have no default comparison function. This means -that once the model has been sorted, it can't go back to the default -state. In this case, when the current sort column id of sortable is -1, the -model will be unsorted.</para> - - </refsect2> - - <refsect2 id="method-gtktreesortable--has-default-sort-func"> - <title>gtk.TreeSortable.has_default_sort_func</title> - - <programlisting><methodsynopsis language="python"> - <methodname>has_default_sort_func</methodname> - <methodparam></methodparam> </methodsynopsis></programlisting> - <variablelist> - <varlistentry> - <term><emphasis>Returns</emphasis> :</term> - <listitem><simpara><literal>True</literal>, if the model has a -default sort function</simpara></listitem> - </varlistentry> - </variablelist> - - <para>The <methodname>has_default_sort_func</methodname>() method -returns <literal>True</literal> if the model has a default sort function. -This is used primarily by <link -linkend="class-gtktreeviewcolumn"><classname>gtk.TreeViewColumn</classname></link> -to determine if a model can go back to the default state, or not.</para> - - </refsect2> - - </refsect1> - - <refsect1> - <title>Signals</title> - - <refsect2 id="signal-gtktreesortable--sort-column-changed"> - <title>The "sort-column-changed" gtk.TreeSortable Signal</title> - - <programlisting><methodsynopsis language="python"> - <methodname>callback</methodname> - <methodparam><parameter>treesortable</parameter></methodparam> - <methodparam><parameter>user_param1</parameter></methodparam> - <methodparam><parameter>...</parameter></methodparam> - </methodsynopsis></programlisting> - - <variablelist> - <varlistentry> - <term><parameter>treesortable</parameter> :</term> - <listitem><simpara>the treesortable that received the -signal</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_param1</parameter> :</term> - <listitem><simpara>the first user parameter (if any) specified -with the <link -linkend="method-gobject--connect"><methodname>connect</methodname>()</link> -method</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>...</parameter> :</term> - <listitem><simpara>additional user parameters (if -any)</simpara></listitem> - </varlistentry> - </variablelist> - - <para>The "sort-column-changed" signal is emitted when the <link -linkend="method-gtktreesortable--sort-column-changed"><methodname>sort_column_changed</methodname>()</link> -method is called or the sort column is changed using the <link -linkend="method-gtktreesortable--set-sort-column-id"><methodname>set_sort_column_id</methodname>()</link> -method.</para> - - </refsect2> - - </refsect1> - -</refentry> |