1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
|
<html><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"><title>gtk.TreeSortable</title><link rel="stylesheet" href="style.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.73.2"><link rel="start" href="index.html" title="PyGTK 2.0 Reference Manual"><link rel="up" href="gtk-class-reference.html" title="The gtk Class Reference"><link rel="prev" href="class-gtktreeselection.html" title="gtk.TreeSelection"><link rel="next" href="class-gtktreestore.html" title="gtk.TreeStore"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">gtk.TreeSortable</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="class-gtktreeselection.html">Prev</a> </td><th width="60%" align="center">The gtk Class Reference</th><td width="20%" align="right"> <a accesskey="n" href="class-gtktreestore.html">Next</a></td></tr></table><hr></div><div class="refentry" lang="en"><a name="class-gtktreesortable"></a><div class="titlepage"></div><div class="refnamediv"><h2>gtk.TreeSortable</h2><p>gtk.TreeSortable — an interface for sorting a <a class="link" href="class-gtktreemodel.html" title="gtk.TreeModel"><code class="classname">gtk.TreeModel</code></a></p></div><div class="refsect1" lang="en"><a name="id3607047"></a><h2>Synopsis</h2><table bgcolor="#D0E0F0" width="100%"><tr><td><pre class="classsynopsis">class <span class="ooclass"><span class="classname">gtk.TreeSortable</span></span>(<span class="ooclass"><span class="classname">gobject.GInterface</span></span>):
<code class="methodsynopsis"> def <span class="methodname"><a class="link" href="class-gtktreesortable.html#method-gtktreesortable--sort-column-changed" title="gtk.TreeSortable.sort_column_changed">sort_column_changed</a></span>(<span class="methodparam"></span>)</code><br><code class="methodsynopsis"> def <span class="methodname"><a class="link" href="class-gtktreesortable.html#method-gtktreesortable--get-sort-column-id" title="gtk.TreeSortable.get_sort_column_id">get_sort_column_id</a></span>(<span class="methodparam"></span>)</code><br><code class="methodsynopsis"> def <span class="methodname"><a class="link" href="class-gtktreesortable.html#method-gtktreesortable--set-sort-column-id" title="gtk.TreeSortable.set_sort_column_id">set_sort_column_id</a></span>(<span class="methodparam"><span class="parameter"><strong class="parameter"><code>sort_column_id</code></strong></span></span>, <span class="methodparam"><span class="parameter"><strong class="parameter"><code>order</code></strong></span></span>)</code><br><code class="methodsynopsis"> def <span class="methodname"><a class="link" href="class-gtktreesortable.html#method-gtktreesortable--set-sort-func" title="gtk.TreeSortable.set_sort_func">set_sort_func</a></span>(<span class="methodparam"><span class="parameter"><em class="parameter"><code>sort_column_id</code></em></span></span>, <span class="methodparam"><span class="parameter"><em class="parameter"><code>sort_func</code></em></span></span>, <span class="methodparam"><span class="parameter"><em class="parameter"><code>user_data</code></em></span><span class="initializer">=None</span></span>)</code><br><code class="methodsynopsis"> def <span class="methodname"><a class="link" href="class-gtktreesortable.html#method-gtktreesortable--set-default-sort-func" title="gtk.TreeSortable.set_default_sort_func">set_default_sort_func</a></span>(<span class="methodparam"><span class="parameter"><em class="parameter"><code>sort_func</code></em></span></span>, <span class="methodparam"><span class="parameter"><em class="parameter"><code>user_data</code></em></span><span class="initializer">=None</span></span>)</code><br><code class="methodsynopsis"> def <span class="methodname"><a class="link" href="class-gtktreesortable.html#method-gtktreesortable--has-default-sort-func" title="gtk.TreeSortable.has_default_sort_func">has_default_sort_func</a></span>(<span class="methodparam"></span>)</code><br></pre></td></tr></table></div><div class="refsect1" lang="en"><a name="signal-prototypes-gtktreesortable"></a><h2>gtk.TreeSortable Signal Prototypes</h2><table border="0" width="100%" bgcolor="#FFECCE"><col align="left" valign="top" width="0*"><tbody><tr><td><p><span class="term">"<a class="link" href="class-gtktreesortable.html#signal-gtktreesortable--sort-column-changed" title='The "sort-column-changed" gtk.TreeSortable Signal'>sort-column-changed</a>"</span></p></td><td><code class="methodsynopsis"> def <span class="methodname">callback</span>(<span class="methodparam"><span class="parameter"><em class="parameter"><code>treesortable</code></em></span></span>, <span class="methodparam"><span class="parameter"><em class="parameter"><code>user_param1</code></em></span></span>, <span class="methodparam"><span class="parameter"><em class="parameter"><code>...</code></em></span></span>)</code></td></tr></tbody></table></div><div class="refsect1" lang="en"><a name="id3607347"></a><h2>Description</h2><p>The <a class="link" href="class-gtktreesortable.html" title="gtk.TreeSortable"><code class="classname">gtk.TreeSortable</code></a>
interface provide the common methods for a <a class="link" href="class-gtktreemodel.html" title="gtk.TreeModel"><code class="classname">gtk.TreeModel</code></a> to
implement a sorted model for a <a class="link" href="class-gtktreeview.html" title="gtk.TreeView"><code class="classname">gtk.TreeView</code></a>. See
the <a class="link" href="class-gtktreemodelsort.html" title="gtk.TreeModelSort"><code class="classname">gtk.TreeModelSort</code></a>
for an example of a treemodel that implements the <a class="link" href="class-gtktreesortable.html" title="gtk.TreeSortable"><code class="classname">gtk.TreeSortable</code></a>
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 <a class="link" href="class-gtktreesortable.html#method-gtktreesortable--set-sort-func" title="gtk.TreeSortable.set_sort_func"><code class="methodname">set_sort_func</code>()</a>
method. The sort column ID can then be used for sorting a <a class="link" href="class-gtkliststore.html" title="gtk.ListStore"><code class="classname">gtk.ListStore</code></a> or
<a class="link" href="class-gtktreestore.html" title="gtk.TreeStore"><code class="classname">gtk.TreeStore</code></a>
using the <a class="link" href="class-gtktreesortable.html#method-gtktreesortable--set-sort-column-id" title="gtk.TreeSortable.set_sort_column_id"><code class="methodname">set_sort_column_id</code>()</a>
method.</p><p>The <a class="link" href="class-gtkliststore.html" title="gtk.ListStore"><code class="classname">gtk.ListStore</code></a> and
<a class="link" href="class-gtktreestore.html" title="gtk.TreeStore"><code class="classname">gtk.TreeStore</code></a>
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:</p><div class="itemizedlist"><ul type="disc"><li>gboolean</li><li>str</li><li>int</li><li>long</li><li>float</li></ul></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Once a sort column ID has been set on a <a class="link" href="class-gtktreemodel.html" title="gtk.TreeModel"><code class="classname">gtk.TreeModel</code></a>
implementing the <a class="link" href="class-gtktreesortable.html" title="gtk.TreeSortable"><code class="classname">gtk.TreeSortable</code></a>
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 <a class="link" href="class-gtktreemodel.html" title="gtk.TreeModel"><code class="classname">gtk.TreeModel</code></a> to
have no sort function.</p></div></div><div class="refsect1" lang="en"><a name="id3607531"></a><h2>Methods</h2><div class="refsect2" lang="en"><a name="method-gtktreesortable--sort-column-changed"></a><h3>gtk.TreeSortable.sort_column_changed</h3><pre class="programlisting"><code class="methodsynopsis"> def <span class="methodname">sort_column_changed</span>(<span class="methodparam"></span>)</code></pre><p>The <code class="methodname">sort_column_changed</code>() method emits
the "sort_column_changed" signal on the treesortable object.</p></div><div class="refsect2" lang="en"><a name="method-gtktreesortable--get-sort-column-id"></a><h3>gtk.TreeSortable.get_sort_column_id</h3><pre class="programlisting"><code class="methodsynopsis"> def <span class="methodname">get_sort_column_id</span>(<span class="methodparam"></span>)</code></pre><table border="0" width="100%" bgcolor="#FFECCE"><col align="left" valign="top" width="0*"><tbody><tr><td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td><td>a tuple containing the sort column id and the
sort type: <code class="literal">gtk.SORT_ASCENDING</code> or
<code class="literal">gtk.SORT_DESCENDING</code></td></tr></tbody></table><p>The <code class="methodname">get_sort_column_id</code>() method returns
a tuple containing the current sort column ID and the sort type (either
<code class="literal">gtk.SORT_ASCENDING</code> or
<code class="literal">gtk.SORT_DESCENDING</code>), if applicable. If the sort column
ID is not set, then the tuple <code class="literal">(-2, 0)</code> is returned. If the
sort column ID is set to -1 indicating the default sort function is to be
used this method returns (<code class="literal">None</code>,
<code class="literal">None</code>)</p></div><div class="refsect2" lang="en"><a name="method-gtktreesortable--set-sort-column-id"></a><h3>gtk.TreeSortable.set_sort_column_id</h3><pre class="programlisting"><code class="methodsynopsis"> def <span class="methodname">set_sort_column_id</span>(<span class="methodparam"><span class="parameter"><strong class="parameter"><code>sort_column_id</code></strong></span></span>, <span class="methodparam"><span class="parameter"><strong class="parameter"><code>order</code></strong></span></span>)</code></pre><table border="0" width="100%" bgcolor="#FFECCE"><col align="left" valign="top" width="0*"><tbody><tr><td><p><span class="term"><strong class="parameter"><code>sort_column_id</code></strong> :</span></p></td><td>the sort column id to set</td></tr><tr><td><p><span class="term"><strong class="parameter"><code>order</code></strong> :</span></p></td><td>the sort order:
<code class="literal">gtk.SORT_ASCENDING</code> or
<code class="literal">gtk.SORT_DESCENDING</code></td></tr></tbody></table><p>The <code class="methodname">set_sort_column_id</code>() method sets
the current sort comparison function to that associated with the sort column
ID specified by <em class="parameter"><code>sort_column_id</code></em> with the sort order
type specified by <em class="parameter"><code>order</code></em>. The value of order must be
either: <code class="literal">gtk.SORT_ASCENDING</code> or
<code class="literal">gtk.SORT_DESCENDING</code>. The treesortable will resort itself
to reflect this change, after emitting a "sort_column_changed" signal.</p><p>If <em class="parameter"><code>sort_column_id</code></em> 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.</p></div><div class="refsect2" lang="en"><a name="method-gtktreesortable--set-sort-func"></a><h3>gtk.TreeSortable.set_sort_func</h3><pre class="programlisting"><code class="methodsynopsis"> def <span class="methodname">set_sort_func</span>(<span class="methodparam"><span class="parameter"><em class="parameter"><code>sort_column_id</code></em></span></span>, <span class="methodparam"><span class="parameter"><em class="parameter"><code>sort_func</code></em></span></span>, <span class="methodparam"><span class="parameter"><em class="parameter"><code>user_data</code></em></span><span class="initializer">=None</span></span>)</code></pre><table border="0" width="100%" bgcolor="#FFECCE"><col align="left" valign="top" width="0*"><tbody><tr><td><p><span class="term"><em class="parameter"><code>sort_column_id</code></em> :</span></p></td><td>the sort column id to set the function
for</td></tr><tr><td><p><span class="term"><em class="parameter"><code>sort_func</code></em> :</span></p></td><td>The sorting function</td></tr><tr><td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td><td>the user data to pass to the sort func, or
<code class="literal">None</code></td></tr></tbody></table><p>The <code class="methodname">set_sort_func</code>() method sets the
comparison function (or method) used when sorting on the sort column ID
specified by <em class="parameter"><code>column_id</code></em> to the value specified by
<em class="parameter"><code>sort_func</code></em>. If the current sort column id of the
treesortable is the same as <em class="parameter"><code>sort_column_id</code></em>, the model
will be resorted. The signature of the comparison function (or method)
is:</p><pre class="programlisting">
<code class="methodsynopsis"> def <span class="methodname">comparefunction</span>(<span class="methodparam"><span class="parameter"><em class="parameter"><code>treemodel</code></em></span></span>, <span class="methodparam"><span class="parameter"><em class="parameter"><code>iter1</code></em></span></span>, <span class="methodparam"><span class="parameter"><em class="parameter"><code>iter2</code></em></span></span>, <span class="methodparam"><span class="parameter"><em class="parameter"><code>user_data</code></em></span></span>)</code><br>
<code class="methodsynopsis"> def <span class="methodname">comparemethod</span>(<span class="methodparam"><span class="parameter"><em class="parameter"><code>self</code></em></span></span>, <span class="methodparam"><span class="parameter"><em class="parameter"><code>treemodel</code></em></span></span>, <span class="methodparam"><span class="parameter"><em class="parameter"><code>iter1</code></em></span></span>, <span class="methodparam"><span class="parameter"><em class="parameter"><code>iter2</code></em></span></span>, <span class="methodparam"><span class="parameter"><em class="parameter"><code>user_data</code></em></span></span>)</code>
</pre><p>where <em class="parameter"><code>treemodel</code></em> is the tree model
implementing the <a class="link" href="class-gtktreesortable.html" title="gtk.TreeSortable"><code class="classname">gtk.TreeSortable</code></a>
interface, <em class="parameter"><code>iter1</code></em> and <em class="parameter"><code>iter2</code></em>
point at the rows to compare and <em class="parameter"><code>user_data</code></em> is the
user data specified in <code class="methodname">set_sort_func</code>() or
<em class="parameter"><code>None</code></em>. If <em class="parameter"><code>sort_func</code></em> is a method
then <em class="parameter"><code>self</code></em> is the object associated with the
method.</p><p>The comparison callback should return -1 if the
<em class="parameter"><code>iter1</code></em> row should come before the
<em class="parameter"><code>iter2</code></em> row, 0 if the rows are equal, or 1 if the
<em class="parameter"><code>iter1</code></em> row should come after the
<em class="parameter"><code>iter2</code></em> row.</p></div><div class="refsect2" lang="en"><a name="method-gtktreesortable--set-default-sort-func"></a><h3>gtk.TreeSortable.set_default_sort_func</h3><pre class="programlisting"><code class="methodsynopsis"> def <span class="methodname">set_default_sort_func</span>(<span class="methodparam"><span class="parameter"><em class="parameter"><code>sort_func</code></em></span></span>, <span class="methodparam"><span class="parameter"><em class="parameter"><code>user_data</code></em></span><span class="initializer">=None</span></span>)</code></pre><table border="0" width="100%" bgcolor="#FFECCE"><col align="left" valign="top" width="0*"><tbody><tr><td><p><span class="term"><em class="parameter"><code>sort_func</code></em> :</span></p></td><td>the sorting function</td></tr><tr><td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td><td>the user data to pass to
<em class="parameter"><code>sort_func</code></em>, or
<code class="literal">None</code></td></tr></tbody></table><p>The <code class="methodname">set_default_sort_func</code>() method sets
the default comparison function (or method) to the value of
<em class="parameter"><code>sort_func</code></em>. If the current sort column id of the
treesortable is -1 (the <a class="link" href="class-gtktreesortable.html#method-gtktreesortable--get-sort-column-id" title="gtk.TreeSortable.get_sort_column_id"><code class="methodname">get_sort_column_id</code>()</a>
method returns (None, None)), then the model will be resorted using the
<em class="parameter"><code>sort_func</code></em>. See the <a class="link" href="class-gtktreesortable.html#method-gtktreesortable--set-sort-func" title="gtk.TreeSortable.set_sort_func"><code class="methodname">set_sort_func</code>()</a>
method for more details on the signature of the comparison function.</p><p>In Pygtk 2.10, <em class="parameter"><code>sort_func</code></em> can be
<code class="literal">None</code> 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.</p></div><div class="refsect2" lang="en"><a name="method-gtktreesortable--has-default-sort-func"></a><h3>gtk.TreeSortable.has_default_sort_func</h3><pre class="programlisting"><code class="methodsynopsis"> def <span class="methodname">has_default_sort_func</span>(<span class="methodparam"></span>)</code></pre><table border="0" width="100%" bgcolor="#FFECCE"><col align="left" valign="top" width="0*"><tbody><tr><td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td><td><code class="literal">True</code>, if the model has a
default sort function</td></tr></tbody></table><p>The <code class="methodname">has_default_sort_func</code>() method
returns <code class="literal">True</code> if the model has a default sort function.
This is used primarily by <a class="link" href="class-gtktreeviewcolumn.html" title="gtk.TreeViewColumn"><code class="classname">gtk.TreeViewColumn</code></a>
to determine if a model can go back to the default state, or not.</p></div></div><div class="refsect1" lang="en"><a name="id3608458"></a><h2>Signals</h2><div class="refsect2" lang="en"><a name="signal-gtktreesortable--sort-column-changed"></a><h3>The "sort-column-changed" gtk.TreeSortable Signal</h3><pre class="programlisting"><code class="methodsynopsis"> def <span class="methodname">callback</span>(<span class="methodparam"><span class="parameter"><em class="parameter"><code>treesortable</code></em></span></span>, <span class="methodparam"><span class="parameter"><em class="parameter"><code>user_param1</code></em></span></span>, <span class="methodparam"><span class="parameter"><em class="parameter"><code>...</code></em></span></span>)</code></pre><table border="0" width="100%" bgcolor="#FFECCE"><col align="left" valign="top" width="0*"><tbody><tr><td><p><span class="term"><em class="parameter"><code>treesortable</code></em> :</span></p></td><td>the treesortable that received the
signal</td></tr><tr><td><p><span class="term"><em class="parameter"><code>user_param1</code></em> :</span></p></td><td>the first user parameter (if any) specified
with the <PYGTKDOCLINK HREF="method-gobject--connect"><code class="methodname">connect</code>()</PYGTKDOCLINK>
method</td></tr><tr><td><p><span class="term"><em class="parameter"><code>...</code></em> :</span></p></td><td>additional user parameters (if
any)</td></tr></tbody></table><p>The "sort-column-changed" signal is emitted when the <a class="link" href="class-gtktreesortable.html#method-gtktreesortable--sort-column-changed" title="gtk.TreeSortable.sort_column_changed"><code class="methodname">sort_column_changed</code>()</a>
method is called or the sort column is changed using the <a class="link" href="class-gtktreesortable.html#method-gtktreesortable--set-sort-column-id" title="gtk.TreeSortable.set_sort_column_id"><code class="methodname">set_sort_column_id</code>()</a>
method.</p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="class-gtktreeselection.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="gtk-class-reference.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="class-gtktreestore.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">gtk.TreeSelection </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> gtk.TreeStore</td></tr></table></div></body></html>
|
