<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
<!ENTITY version SYSTEM "version.xml">
]>
<!--ENTITY index-Objects-Grouped SYSTEM "objects_grouped.sgml"-->
<refentry id="GtkTreeSortable">
<refmeta>
<refentrytitle role="top_of_page" id="GtkTreeSortable.top_of_page">GtkTreeSortable</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GTK Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>GtkTreeSortable</refname>
<refpurpose>The interface for sortable models used by GtkTreeView</refpurpose>
</refnamediv>

<refsynopsisdiv id="GtkTreeSortable.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>

#include &lt;gtk/gtk.h&gt;

                    <link linkend="GtkTreeSortable-struct">GtkTreeSortable</link>;
                    <link linkend="GtkTreeSortableIface">GtkTreeSortableIface</link>;
<link linkend="gint">gint</link>                (<link linkend="GtkTreeIterCompareFunc">*GtkTreeIterCompareFunc</link>)           (<link linkend="GtkTreeModel">GtkTreeModel</link> *model,
                                                         <link linkend="GtkTreeIter">GtkTreeIter</link> *a,
                                                         <link linkend="GtkTreeIter">GtkTreeIter</link> *b,
                                                         <link linkend="gpointer">gpointer</link> user_data);
<link linkend="void">void</link>                <link linkend="gtk-tree-sortable-sort-column-changed">gtk_tree_sortable_sort_column_changed</link>
                                                        (<link linkend="GtkTreeSortable">GtkTreeSortable</link> *sortable);
<link linkend="gboolean">gboolean</link>            <link linkend="gtk-tree-sortable-get-sort-column-id">gtk_tree_sortable_get_sort_column_id</link>
                                                        (<link linkend="GtkTreeSortable">GtkTreeSortable</link> *sortable,
                                                         <link linkend="gint">gint</link> *sort_column_id,
                                                         <link linkend="GtkSortType">GtkSortType</link> *order);
<link linkend="void">void</link>                <link linkend="gtk-tree-sortable-set-sort-column-id">gtk_tree_sortable_set_sort_column_id</link>
                                                        (<link linkend="GtkTreeSortable">GtkTreeSortable</link> *sortable,
                                                         <link linkend="gint">gint</link> sort_column_id,
                                                         <link linkend="GtkSortType">GtkSortType</link> order);
<link linkend="void">void</link>                <link linkend="gtk-tree-sortable-set-sort-func">gtk_tree_sortable_set_sort_func</link>     (<link linkend="GtkTreeSortable">GtkTreeSortable</link> *sortable,
                                                         <link linkend="gint">gint</link> sort_column_id,
                                                         <link linkend="GtkTreeIterCompareFunc">GtkTreeIterCompareFunc</link> sort_func,
                                                         <link linkend="gpointer">gpointer</link> user_data,
                                                         <link linkend="GDestroyNotify">GDestroyNotify</link> destroy);
<link linkend="void">void</link>                <link linkend="gtk-tree-sortable-set-default-sort-func">gtk_tree_sortable_set_default_sort_func</link>
                                                        (<link linkend="GtkTreeSortable">GtkTreeSortable</link> *sortable,
                                                         <link linkend="GtkTreeIterCompareFunc">GtkTreeIterCompareFunc</link> sort_func,
                                                         <link linkend="gpointer">gpointer</link> user_data,
                                                         <link linkend="GDestroyNotify">GDestroyNotify</link> destroy);
<link linkend="gboolean">gboolean</link>            <link linkend="gtk-tree-sortable-has-default-sort-func">gtk_tree_sortable_has_default_sort_func</link>
                                                        (<link linkend="GtkTreeSortable">GtkTreeSortable</link> *sortable);
</synopsis>
</refsynopsisdiv>

<refsect1 id="GtkTreeSortable.object-hierarchy" role="object_hierarchy">
<title role="object_hierarchy.title">Object Hierarchy</title>
<synopsis>
  <link linkend="GInterface">GInterface</link>
   +----GtkTreeSortable
</synopsis>
</refsect1>

<refsect1 id="GtkTreeSortable.prerequisites" role="prerequisites">
<title role="prerequisites.title">Prerequisites</title>
<para>
GtkTreeSortable requires
 <link linkend="GtkTreeModel">GtkTreeModel</link> and  <link linkend="GObject">GObject</link>.</para>
</refsect1>



<refsect1 id="GtkTreeSortable.implementations" role="implementations">
<title role="implementations.title">Known Implementations</title>
<para>
GtkTreeSortable is implemented by
 <link linkend="GtkTreeModelSort">GtkTreeModelSort</link>,  <link linkend="GtkTreeStore">GtkTreeStore</link> and  <link linkend="GtkListStore">GtkListStore</link>.</para>
</refsect1>


<refsect1 id="GtkTreeSortable.signals" role="signal_proto">
<title role="signal_proto.title">Signals</title>
<synopsis>
  &quot;<link linkend="GtkTreeSortable-sort-column-changed">sort-column-changed</link>&quot;                            : Run Last
</synopsis>
</refsect1>


<refsect1 id="GtkTreeSortable.description" role="desc">
<title role="desc.title">Description</title>
<para>
<link linkend="GtkTreeSortable"><type>GtkTreeSortable</type></link> is an interface to be implemented by tree models which
support sorting. The <link linkend="GtkTreeView"><type>GtkTreeView</type></link> uses the methods provided by this interface
to sort the model.
</para>
</refsect1>

<refsect1 id="GtkTreeSortable.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="GtkTreeSortable-struct" role="struct">
<title>GtkTreeSortable</title>
<indexterm zone="GtkTreeSortable-struct"><primary sortas="TreeSortable">GtkTreeSortable</primary></indexterm><programlisting>typedef struct _GtkTreeSortable GtkTreeSortable;</programlisting>
<para>
</para></refsect2>
<refsect2 id="GtkTreeSortableIface" role="struct">
<title>GtkTreeSortableIface</title>
<indexterm zone="GtkTreeSortableIface"><primary sortas="TreeSortableIface">GtkTreeSortableIface</primary></indexterm><programlisting>typedef struct {
  GTypeInterface g_iface;

  /* signals */
  void     (* sort_column_changed)   (GtkTreeSortable        *sortable);

  /* virtual table */
  gboolean (* get_sort_column_id)    (GtkTreeSortable        *sortable,
				      gint                   *sort_column_id,
				      GtkSortType            *order);
  void     (* set_sort_column_id)    (GtkTreeSortable        *sortable,
				      gint                    sort_column_id,
				      GtkSortType             order);
  void     (* set_sort_func)         (GtkTreeSortable        *sortable,
				      gint                    sort_column_id,
				      GtkTreeIterCompareFunc  func,
				      gpointer                data,
				      GDestroyNotify          destroy);
  void     (* set_default_sort_func) (GtkTreeSortable        *sortable,
				      GtkTreeIterCompareFunc  func,
				      gpointer                data,
				      GDestroyNotify          destroy);
  gboolean (* has_default_sort_func) (GtkTreeSortable        *sortable);
} GtkTreeSortableIface;
</programlisting>
<para>
</para></refsect2>
<refsect2 id="GtkTreeIterCompareFunc" role="function">
<title>GtkTreeIterCompareFunc ()</title>
<indexterm zone="GtkTreeIterCompareFunc"><primary sortas="TreeIterCompareFunc">GtkTreeIterCompareFunc</primary></indexterm><programlisting><link linkend="gint">gint</link>                (*GtkTreeIterCompareFunc)           (<link linkend="GtkTreeModel">GtkTreeModel</link> *model,
                                                         <link linkend="GtkTreeIter">GtkTreeIter</link> *a,
                                                         <link linkend="GtkTreeIter">GtkTreeIter</link> *b,
                                                         <link linkend="gpointer">gpointer</link> user_data);</programlisting>
<para>
A GtkTreeIterCompareFunc should return a negative integer, zero, or a positive
integer if <parameter>a</parameter> sorts before <parameter>b</parameter>, <parameter>a</parameter> sorts with <parameter>b</parameter>, or <parameter>a</parameter> sorts after <parameter>b</parameter>
respectively. If two iters compare as equal, their order in the sorted model
is undefined. In order to ensure that the <link linkend="GtkTreeSortable"><type>GtkTreeSortable</type></link> behaves as
expected, the GtkTreeIterCompareFunc must define a partial order on
the model, i.e. it must be reflexive, antisymmetric and transitive.
</para>
<para>
For example, if <parameter>model</parameter> is a product catalogue, then a compare function
for the "price" column could be one which returns
<literal>price_of(<parameter>a</parameter>) - price_of(<parameter>b</parameter>)</literal>.
</para><variablelist role="params">
<varlistentry><term><parameter>model</parameter>&#160;:</term>
<listitem><simpara>The <link linkend="GtkTreeModel"><type>GtkTreeModel</type></link> the comparison is within
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>a</parameter>&#160;:</term>
<listitem><simpara>A <link linkend="GtkTreeIter"><type>GtkTreeIter</type></link> in <parameter>model</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>b</parameter>&#160;:</term>
<listitem><simpara>Another <link linkend="GtkTreeIter"><type>GtkTreeIter</type></link> in <parameter>model</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter>&#160;:</term>
<listitem><simpara>Data passed when the compare func is assigned e.g. by
<link linkend="gtk-tree-sortable-set-sort-func"><function>gtk_tree_sortable_set_sort_func()</function></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a negative integer, zero or a positive integer depending on whether
    <parameter>a</parameter> sorts before, with or after <parameter>b</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-tree-sortable-sort-column-changed" role="function">
<title>gtk_tree_sortable_sort_column_changed ()</title>
<indexterm zone="gtk-tree-sortable-sort-column-changed"><primary sortas="tree_sortable_sort_column_changed">gtk_tree_sortable_sort_column_changed</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_tree_sortable_sort_column_changed
                                                        (<link linkend="GtkTreeSortable">GtkTreeSortable</link> *sortable);</programlisting>
<para>
Emits a <link linkend="GtkTreeSortable-sort-column-changed"><type>"sort-column-changed"</type></link> signal on <parameter>sortable</parameter>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>sortable</parameter>&#160;:</term>
<listitem><simpara> A <link linkend="GtkTreeSortable"><type>GtkTreeSortable</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-tree-sortable-get-sort-column-id" role="function">
<title>gtk_tree_sortable_get_sort_column_id ()</title>
<indexterm zone="gtk-tree-sortable-get-sort-column-id"><primary sortas="tree_sortable_get_sort_column_id">gtk_tree_sortable_get_sort_column_id</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            gtk_tree_sortable_get_sort_column_id
                                                        (<link linkend="GtkTreeSortable">GtkTreeSortable</link> *sortable,
                                                         <link linkend="gint">gint</link> *sort_column_id,
                                                         <link linkend="GtkSortType">GtkSortType</link> *order);</programlisting>
<para>
Fills in <parameter>sort_column_id</parameter> and <parameter>order</parameter> with the current sort column and the
order. It returns <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> unless the <parameter>sort_column_id</parameter> is 
<link linkend="GTK-TREE-SORTABLE-DEFAULT-SORT-COLUMN-ID--CAPS"><literal>GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID</literal></link> or 
<link linkend="GTK-TREE-SORTABLE-UNSORTED-SORT-COLUMN-ID--CAPS"><literal>GTK_TREE_SORTABLE_UNSORTED_SORT_COLUMN_ID</literal></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>sortable</parameter>&#160;:</term>
<listitem><simpara> A <link linkend="GtkTreeSortable"><type>GtkTreeSortable</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>sort_column_id</parameter>&#160;:</term>
<listitem><simpara> The sort column id to be filled in
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>order</parameter>&#160;:</term>
<listitem><simpara> The <link linkend="GtkSortType"><type>GtkSortType</type></link> to be filled in
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the sort column is not one of the special sort
  column ids.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-tree-sortable-set-sort-column-id" role="function">
<title>gtk_tree_sortable_set_sort_column_id ()</title>
<indexterm zone="gtk-tree-sortable-set-sort-column-id"><primary sortas="tree_sortable_set_sort_column_id">gtk_tree_sortable_set_sort_column_id</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_tree_sortable_set_sort_column_id
                                                        (<link linkend="GtkTreeSortable">GtkTreeSortable</link> *sortable,
                                                         <link linkend="gint">gint</link> sort_column_id,
                                                         <link linkend="GtkSortType">GtkSortType</link> order);</programlisting>
<para>
Sets the current sort column to be <parameter>sort_column_id</parameter>. The <parameter>sortable</parameter> will
resort itself to reflect this change, after emitting a
<link linkend="GtkTreeSortable-sort-column-changed"><type>"sort-column-changed"</type></link> signal. <parameter>sortable</parameter> may either be 
a regular column id, or one of the following special values:
<variablelist>
<varlistentry>
  <term><link linkend="GTK-TREE-SORTABLE-DEFAULT-SORT-COLUMN-ID--CAPS"><literal>GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID</literal></link></term>
  <listitem>the default sort function will be used, if it is set</listitem>
</varlistentry>
<varlistentry>
  <term><link linkend="GTK-TREE-SORTABLE-UNSORTED-SORT-COLUMN-ID--CAPS"><literal>GTK_TREE_SORTABLE_UNSORTED_SORT_COLUMN_ID</literal></link></term>
  <listitem>no sorting will occur</listitem>
</varlistentry>
</variablelist></para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>sortable</parameter>&#160;:</term>
<listitem><simpara> A <link linkend="GtkTreeSortable"><type>GtkTreeSortable</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>sort_column_id</parameter>&#160;:</term>
<listitem><simpara> the sort column id to set
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>order</parameter>&#160;:</term>
<listitem><simpara> The sort order of the column
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-tree-sortable-set-sort-func" role="function">
<title>gtk_tree_sortable_set_sort_func ()</title>
<indexterm zone="gtk-tree-sortable-set-sort-func"><primary sortas="tree_sortable_set_sort_func">gtk_tree_sortable_set_sort_func</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_tree_sortable_set_sort_func     (<link linkend="GtkTreeSortable">GtkTreeSortable</link> *sortable,
                                                         <link linkend="gint">gint</link> sort_column_id,
                                                         <link linkend="GtkTreeIterCompareFunc">GtkTreeIterCompareFunc</link> sort_func,
                                                         <link linkend="gpointer">gpointer</link> user_data,
                                                         <link linkend="GDestroyNotify">GDestroyNotify</link> destroy);</programlisting>
<para>
Sets the comparison function used when sorting to be <parameter>sort_func</parameter>. If the
current sort column id of <parameter>sortable</parameter> is the same as <parameter>sort_column_id</parameter>, then 
the model will sort using this function.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>sortable</parameter>&#160;:</term>
<listitem><simpara> A <link linkend="GtkTreeSortable"><type>GtkTreeSortable</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>sort_column_id</parameter>&#160;:</term>
<listitem><simpara> the sort column id to set the function for
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>sort_func</parameter>&#160;:</term>
<listitem><simpara> The comparison function
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter>&#160;:</term>
<listitem><simpara> User data to pass to <parameter>sort_func</parameter>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>destroy</parameter>&#160;:</term>
<listitem><simpara> Destroy notifier of <parameter>user_data</parameter>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-tree-sortable-set-default-sort-func" role="function">
<title>gtk_tree_sortable_set_default_sort_func ()</title>
<indexterm zone="gtk-tree-sortable-set-default-sort-func"><primary sortas="tree_sortable_set_default_sort_func">gtk_tree_sortable_set_default_sort_func</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_tree_sortable_set_default_sort_func
                                                        (<link linkend="GtkTreeSortable">GtkTreeSortable</link> *sortable,
                                                         <link linkend="GtkTreeIterCompareFunc">GtkTreeIterCompareFunc</link> sort_func,
                                                         <link linkend="gpointer">gpointer</link> user_data,
                                                         <link linkend="GDestroyNotify">GDestroyNotify</link> destroy);</programlisting>
<para>
Sets the default comparison function used when sorting to be <parameter>sort_func</parameter>.  
If the current sort column id of <parameter>sortable</parameter> is
<link linkend="GTK-TREE-SORTABLE-DEFAULT-SORT-COLUMN-ID--CAPS"><literal>GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID</literal></link>, then the model will sort using 
this function.
</para>
<para>
If <parameter>sort_func</parameter> is <link linkend="NULL--CAPS"><literal>NULL</literal></link>, then there will be 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 <parameter>sortable</parameter> 
is <link linkend="GTK-TREE-SORTABLE-DEFAULT-SORT-COLUMN-ID--CAPS"><literal>GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID</literal></link>, the model will be unsorted.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>sortable</parameter>&#160;:</term>
<listitem><simpara> A <link linkend="GtkTreeSortable"><type>GtkTreeSortable</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>sort_func</parameter>&#160;:</term>
<listitem><simpara> The comparison function
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter>&#160;:</term>
<listitem><simpara> User data to pass to <parameter>sort_func</parameter>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>destroy</parameter>&#160;:</term>
<listitem><simpara> Destroy notifier of <parameter>user_data</parameter>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-tree-sortable-has-default-sort-func" role="function">
<title>gtk_tree_sortable_has_default_sort_func ()</title>
<indexterm zone="gtk-tree-sortable-has-default-sort-func"><primary sortas="tree_sortable_has_default_sort_func">gtk_tree_sortable_has_default_sort_func</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            gtk_tree_sortable_has_default_sort_func
                                                        (<link linkend="GtkTreeSortable">GtkTreeSortable</link> *sortable);</programlisting>
<para>
Returns <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the model has a default sort function. This is used
primarily by GtkTreeViewColumns in order to determine if a model can 
go back to the default state, or not.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>sortable</parameter>&#160;:</term>
<listitem><simpara> A <link linkend="GtkTreeSortable"><type>GtkTreeSortable</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link>, if the model has a default sort function
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>

<refsect1 id="GtkTreeSortable.signal-details" role="signals">
<title role="signals.title">Signal Details</title>
<refsect2 id="GtkTreeSortable-sort-column-changed" role="signal"><title>The <literal>&quot;sort-column-changed&quot;</literal> signal</title>
<indexterm zone="GtkTreeSortable-sort-column-changed"><primary sortas="TreeSortable::sort-column-changed">GtkTreeSortable::sort-column-changed</primary></indexterm><programlisting><link linkend="void">void</link>                user_function                      (<link linkend="GtkTreeSortable">GtkTreeSortable</link> *sortable,
                                                        <link linkend="gpointer">gpointer</link>         user_data)      : Run Last</programlisting>
<para>
The ::sort-column-changed signal is emitted when the sort column
or sort order of <parameter>sortable</parameter> is changed. The signal is emitted before
the contents of <parameter>sortable</parameter> are resorted.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>sortable</parameter>&#160;:</term>
<listitem><simpara> the object on which the signal is emitted
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter>&#160;:</term>
<listitem><simpara>user data set when the signal handler was connected.</simpara></listitem></varlistentry>
</variablelist></refsect2>
</refsect1>


<refsect1 id="GtkTreeSortable.see-also">
<title>See Also</title>
<para>
<link linkend="GtkTreeModel"><type>GtkTreeModel</type></link>, <link linkend="GtkTreeView"><type>GtkTreeView</type></link>
</para>
</refsect1>

</refentry>
