<?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-gtktreerowreference">
  <refnamediv>
    <refname>gtk.TreeRowReference</refname>

    <refpurpose>an object maintaining a persistent reference to a <link
linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link>
row (new in PyGTK 2.4)</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>gtk.TreeRowReference</classname></ooclass>
      <ooclass><classname>gobject.GBoxed</classname></ooclass>
      <constructorsynopsis language="python">
	<methodname><link linkend="constructor-gtktreerowreference">gtk.TreeRowReference</link></methodname>
	<methodparam><parameter role="keyword">model</parameter></methodparam>
	<methodparam><parameter role="keyword">path</parameter></methodparam>
      </constructorsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtktreerowreference--get-path">get_path</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtktreerowreference--get-model">get_model</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtktreerowreference--valid">valid</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtktreerowreference--copy">copy</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtktreerowreference--free">free</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
    </classsynopsis>

  </refsect1>

  <refsect1>
    <title>Description</title>

    <note>
      <para>This object is available in PyGTK 2.4 and above.</para>
    </note>

    <para>A <link
linkend="class-gtktreerowreference"><classname>gtk.TreeRowReference</classname></link>
is an object that points to a row in a <link
linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link>
similar to a <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>. A
<link
linkend="class-gtktreerowreference"><classname>gtk.TreeRowReference</classname></link>,
unlike a <link
linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>,
maintains a persistent reference in spite of changes in the model.</para>

  </refsect1>

  <refsect1 id="constructor-gtktreerowreference">
    <title>Constructor</title>

    <programlisting><constructorsynopsis language="python">
	<methodname>gtk.TreeRowReference</methodname>
	<methodparam><parameter role="keyword">model</parameter></methodparam>
	<methodparam><parameter role="keyword">path</parameter></methodparam>
      </constructorsynopsis></programlisting>
    <variablelist>
      <varlistentry>
	<term><parameter role="keyword">model</parameter>&nbsp;:</term>
	<listitem><simpara>a <link
	linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link></simpara></listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter role="keyword">path</parameter>&nbsp;:</term>
	<listitem><simpara>a valid tree path to monitor</simpara></listitem>
      </varlistentry>
      <varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	<listitem><simpara>a <link
	linkend="class-gtktreerowreference"><classname>gtk.TreeRowReference</classname></link>,
	or <literal>None</literal></simpara></listitem>
      </varlistentry>
    </variablelist>

    <note>
      <para>This constructor is available in PyGTK 2.4 and above.</para>
    </note>

    <para>Creates a row reference pointing to the treemodel row specified by
<parameter>model</parameter> and <parameter>path</parameter>. This reference
will continue pointing to the node in spite of changes in
<parameter>model</parameter>. It listens to all signals emitted by
<parameter>model</parameter>, and updates its path appropriately. If
<parameter>path</parameter> isn't a valid path in
<parameter>model</parameter>, <literal>None</literal> is returned.</para>

  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-gtktreerowreference--get-path">
      <title>gtk.TreeRowReference.get_path</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_path</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>A current path, or
<literal>None</literal>.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
	<para>This method is available in PyGTK 2.4 and above.</para>
      </note>

      <para>The <methodname>get_path</methodname>() method returns the path
that the row reference currently points to, or <literal>None</literal> if
the path pointed to is no longer valid.</para>

    </refsect2>

    <refsect2 id="method-gtktreerowreference--get-model">
      <title>gtk.TreeRowReference.get_model</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_model</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the model, or
<literal>None</literal>.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
	<para>This method is available in PyGTK 2.8 and above.</para>
      </note>

      <para>The <methodname>get_model</methodname>() method returns the
model that the row reference currently monitors, or <literal>None</literal>
if the model is not set.</para>

    </refsect2>

    <refsect2 id="method-gtktreerowreference--valid">
      <title>gtk.TreeRowReference.valid</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>valid</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>True</literal> if the row reference
	  points to a valid path.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
	<para>This method is available in PyGTK 2.4 and above.</para>
      </note>

      <para>The <methodname>valid</methodname>() method returns
<literal>True</literal> if the row reference is not <literal>None</literal>
and refers to a current valid path.</para>

    </refsect2>

    <refsect2 id="method-gtktreerowreference--copy">
      <title>gtk.TreeRowReference.copy</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>copy</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a copy of the row reference</simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
	<para>This method is available in PyGTK 2.4 and above.</para>
      </note>

      <para>The <methodname>copy</methodname>() method returns a copy of the
tree row reference.</para>

    </refsect2>

    <refsect2 id="method-gtktreerowreference--free">
      <title>gtk.TreeRowReference.free</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>free</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>

      <note>
	<para>This method is available in PyGTK 2.4 and above.</para>
      </note>

      <warning>
        <para>This method is deprecated and should not be used since it may
crash your application.</para>
      </warning>

      <para>The free() method frees the tree row reference. The row
reference may be <literal>None</literal>.</para>

    </refsect2>

  </refsect1>

</refentry>
