path: root/docs/reference/pygtk-gtkcellview.xml

<?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-gtkcellview">
  <refnamediv>
    <refname>gtk.CellView</refname>
    <refpurpose>a widget displaying a single row of a <link
linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link>
(new in PyGTK 2.6).</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

<classsynopsis language="python">
  <ooclass><classname>gtk.CellView</classname></ooclass>
  <ooclass><classname><link linkend="class-gtkwidget">gtk.Widget</link></classname></ooclass>
      <ooclass><classname><link linkend="class-gtkcelllayout">gtk.CellLayout</link></classname></ooclass>
<constructorsynopsis language="python">
    <methodname><link
linkend="constructor-gtkcellview">gtk.CellView</link></methodname>
    <methodparam></methodparam>
  </constructorsynopsis>
<methodsynopsis language="python">
    <methodname><link linkend="method-gtkcellview--get-cell-renderers">get_cell_renderers</link></methodname>
    <methodparam></methodparam>
  </methodsynopsis>
<methodsynopsis language="python">
    <methodname><link linkend="method-gtkcellview--get-displayed-row">get_displayed_row</link></methodname>
    <methodparam></methodparam>
  </methodsynopsis>
<methodsynopsis language="python">
    <methodname><link linkend="method-gtkcellview--get-model">get_model</link></methodname>
    <methodparam></methodparam>
  </methodsynopsis>
<methodsynopsis language="python">
    <methodname><link linkend="method-gtkcellview--get-size-of-row">get_size_of_row</link></methodname>
    <methodparam><parameter role="keyword">path</parameter></methodparam>
    <methodparam><parameter role="keyword">requisition</parameter></methodparam>
  </methodsynopsis>
<methodsynopsis language="python">
    <methodname><link linkend="method-gtkcellview--set-background-color">set_background_color</link></methodname>
    <methodparam><parameter role="keyword">color</parameter></methodparam>
  </methodsynopsis>
<methodsynopsis language="python">
    <methodname><link linkend="method-gtkcellview--set-displayed-row">set_displayed_row</link></methodname>
    <methodparam><parameter role="keyword">path</parameter></methodparam>
  </methodsynopsis>
<methodsynopsis language="python">
    <methodname><link linkend="method-gtkcellview--set-model">set_model</link></methodname>
    <methodparam><parameter role="keyword">model</parameter></methodparam>
  </methodsynopsis>
</classsynopsis>

<programlisting>
<emphasis role="bold">Functions</emphasis>

<methodsynopsis language="python">
    <methodname><link linkend="function-gtk--cell-view-new-with-text">gtk.cell_view_new_with_text</link></methodname>
    <methodparam><parameter role="keyword">text</parameter></methodparam>
  </methodsynopsis><methodsynopsis language="python">
    <methodname><link linkend="function-gtk--cell-view-new-with-markup">gtk.cell_view_new_with_markup</link></methodname>
    <methodparam><parameter role="keyword">markup</parameter></methodparam>
  </methodsynopsis><methodsynopsis language="python">
    <methodname><link linkend="function-gtk--cell-view-new-with-pixbuf">gtk.cell_view_new_with_pixbuf</link></methodname>
    <methodparam><parameter role="keyword">pixbuf</parameter></methodparam>
  </methodsynopsis></programlisting>

</refsect1>

  <refsect1>
    <title>Ancestry</title>

<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link>
  +-- <link linkend="class-gtkobject">gtk.Object</link>
    +-- <link linkend="class-gtkwidget">gtk.Widget</link>
      +-- <link linkend="class-gtkcellview">gtk.CellView</link>
</synopsis>

  </refsect1>
  
  <refsect1>
		<title>Implemented Interfaces</title>
		<para>
			<link linkend="class-gtkcellview"><classname>gtk.CellView</classname></link>
			implements 
			<link linkend="class-gtkbuildable"><classname>gtk.Buildable</classname></link>
            <link linkend="class-gtkcelllayout">gtk.CellLayout</link>
		</para>
	</refsect1>


  <refsect1 id="properties-gtkcellview">
    <title>gtk.CellView Properties</title>

    <para><link linkend="properties-gtkobject">gtk.Object Properties</link></para>
    <para><link linkend="properties-gtkwidget">gtk.Widget Properties</link></para>

    <blockquote role="properties">
      <informaltable pgwide="1" frame="none">
	<tgroup cols="3">
	  <colspec column="1" colwidth="1in"/>
	  <colspec column="2" colwidth="1in"/>
	  <colspec column="3" colwidth="4in"/>
	  <tbody>

	    <row valign="top">
	      <entry>"background"</entry>
	      <entry>Write</entry>
	      <entry>The background color as a string. Default value:
<literal>None</literal></entry>
	    </row>

	    <row valign="top">
	      <entry>"background-gdk"</entry>
	      <entry>Read-Write</entry>
	      <entry>The background color as a <link
linkend="class-gdkcolor"><classname>gtk.gdk.Color</classname></link>.</entry>
	    </row>

	    <row valign="top">
	      <entry>"background-set"</entry>
	      <entry>Read-Write</entry>
	      <entry>If <literal>True</literal>, use the "background-gdk"
property to set the background color.</entry>
	    </row>

            <row valign="top">
              <entry>"model"</entry>
              <entry>Read-Write</entry>
              <entry>The model for cell view. Available in GTK+ 2.10 and
              above.</entry>
            </row>

	  </tbody>
	</tgroup>
      </informaltable>
    </blockquote>

  </refsect1>

  <refsect1 id="style-properties-gtkcellview">
    <title>gtk.CellView Style Properties</title>

    <para><link linkend="style-properties-gtkwidget">gtk.Widget Style Properties</link></para>

  </refsect1>

  <refsect1 id="signal-prototypes-gtkcellview">
    <title>gtk.CellView Signal Prototypes</title>

    <para><link linkend="signal-prototypes-gobject">gobject.GObject Signal Prototypes</link></para>
    <para><link linkend="signal-prototypes-gtkobject">gtk.Object Signal Prototypes</link></para>
    <para><link linkend="signal-prototypes-gtkwidget">gtk.Widget Signal Prototypes</link></para>
</refsect1>

  <refsect1>
    <title>Description</title>

    <note>
      <para>This widget is available in PyGTK 2.6 and above.</para>
    </note>

    <para>The <link
linkend="class-gtkcellview"><classname>gtk.CellView</classname></link> is a
widget that displays one row of a <link
linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link>. <link
linkend="class-gtkcellview"><classname>gtk.CellView</classname></link>
implements the <link
linkend="class-gtkcelllayout"><classname>gtk.CellLayout</classname></link>
interface that provides for the addition and management of <link
linkend="class-gtkcellrenderer"><classname>gtk.CellRenderer</classname></link>
objects.</para>
  </refsect1>

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

    <programlisting><constructorsynopsis language="python">
	<methodname>gtk.CellView</methodname>
	<methodparam></methodparam>
      </constructorsynopsis></programlisting>
    <variablelist>
      <varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	<listitem><simpara>a new <link
linkend="class-gtkcellview"><classname>gtk.CellView</classname></link></simpara></listitem>
      </varlistentry>
    </variablelist>

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

    <para>Creates a new <link
linkend="class-gtkcellview"><classname>gtk.CellView</classname></link>
widget.</para>

  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-gtkcellview--get-model">
      <title>gtk.CellView.get_displayed_row</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_model</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a <link linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link>
	  used or <literal>None</literal>. 
	  </simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>
	The <methodname>get_model</methodname>() method returns the model for cell_view.
	If no model is used <literal>None</literal> is returned.
      </para>

    </refsect2>

    <refsect2 id="method-gtkcellview--set-model">
      <title>gtk.CellView.set_model</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_model</methodname>
	  <methodparam><parameter
			 role="keyword">model</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">model</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link> or <literal>None</literal></simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>set_model</methodname>() method sets the <link
linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link>
used by the cell view to that specified by <parameter>model</parameter>. If
<parameter>model</parameter> is <literal>None</literal> the cell view's
model will be unset.</para>

    </refsect2>

    <refsect2 id="method-gtkcellview--set-displayed-row">
      <title>gtk.CellView.set_displayed_row</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_displayed_row</methodname>
	  <methodparam><parameter
			 role="keyword">path</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">path</parameter>&nbsp;:</term>
	  <listitem><simpara>a tree path or <literal>None</literal> to unset
the row</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>set_displayed_row</methodname>() method sets the
row of the model that is currently displayed to the path specified by
<parameter>path</parameter>. If <parameter>path</parameter> is
<literal>None</literal> the display row will be unset, and the contents of
the cell view "stick" at their last value. This is not normally a desired
result, but may be a needed intermediate state if say, the model for the
cell view becomes temporarily empty.</para>

    </refsect2>

    <refsect2 id="method-gtkcellview--get-displayed-row">
      <title>gtk.CellView.get_displayed_row</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_displayed_row</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the path of the currently displayed row in the
cell view's model</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>get_displayed_row</methodname>() method returns
the path of the currently displayed row as set by the <link
linkend="method-gtkcellview--set-displayed-row"><methodname>set-displayed_row</methodname>()</link>
method.</para>

    </refsect2>

    <refsect2 id="method-gtkcellview--get-size-of-row">
      <title>gtk.CellView.get_size_of_row</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_size_of_row</methodname>
	  <methodparam><parameter
			 role="keyword">path</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">path</parameter>&nbsp;:</term>
	  <listitem><simpara>the path of a row</simpara></listitem>
	</varlistentry>
	<varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-gtkrequisition"><classname>gtk.Requisition</classname></link>
containing the required size data</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>get_size_of_row</methodname>() method returns a
<link
linkend="class-gtkrequisition"><classname>gtk.Requisition</classname></link>
containing the size required for displaying the row with the tree path
specified by <parameter>path</parameter>.</para>

    </refsect2>

    <refsect2 id="method-gtkcellview--set-background-color">
      <title>gtk.CellView.set_background_color</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_background_color</methodname>
	  <methodparam><parameter
			 role="keyword">color</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">color</parameter>&nbsp;:</term>
	  <listitem><simpara></simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>set_background_color</methodname>() method sets
the background color of the cell view to the <link
linkend="class-gdkcolor"><classname>gtk.gdk.Color</classname></link>
specified by <parameter>color</parameter>.</para>

    </refsect2>

    <refsect2 id="method-gtkcellview--get-cell-renderers">
      <title>gtk.CellView.get_cell_renderers</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_cell_renderers</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a list of the <link
linkend="class-gtkcellrenderer"><classname>gtk.CellRenderer</classname></link>
objects of the cell view.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <warning>
        <para>This method is deprecated since PyGTK 2.18 and should not be used in newly-written code.
        Use "<link linkend="method-gtkcelllayout--get-cells">gtk.CellLayout.get_cells</link>()"
        instead.</para>
      </warning>

      <para>The <methodname>get_cell_renderers</methodname>() method returns
a list containing the <link
linkend="class-gtkcellrenderer"><classname>gtk.CellRenderer</classname></link>
objects used by the cell view.</para>

    </refsect2>

  </refsect1>

  <refsect1>
    <title>Functions</title>

    <refsect2 id="function-gtk--cell-view-new-with-text">
      <title>gtk.cell_view_new_with_text</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.cell_view_new_with_text</methodname>
	  <methodparam><parameter
			 role="keyword">text</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">text</parameter>&nbsp;:</term>
	  <listitem><simpara>a string</simpara></listitem>
	</varlistentry>
	<varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a new <link
linkend="class-gtkcellview"><classname>gtk.CellView</classname></link></simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
        <para>This function is available in PyGTK 2.6 and above.</para>
      </note>

      <para>The <function>gtk.cell_view_new_with_text</function>() function
creates a new <link
linkend="class-gtkcellview"><classname>gtk.CellView</classname></link> with
a <link
linkend="class-gtkcellrenderertext"><classname>gtk.CellRendererText</classname></link>
displaying the string specified by <parameter>text</parameter>.</para>

    </refsect2>

    <refsect2 id="function-gtk--cell-view-new-with-markup">
      <title>gtk.cell_view_new_with_markup</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.cell_view_new_with_markup</methodname>
	  <methodparam><parameter
			 role="keyword">markup</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">markup</parameter>&nbsp;:</term>
	  <listitem><simpara>a string containing Pango markup to be
displayed.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a new <link linkend="class-gtkcellview"><classname>gtk.CellView</classname></link></simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
        <para>This function is available in PyGTK 2.6 and above.</para>
      </note>

      <para>The <function>gtk.cell_view_new_with_markup</function>()
function creates a new <link
linkend="class-gtkcellview"><classname>gtk.CellView</classname></link> with
a <link
linkend="class-gtkcellrenderertext"><classname>gtk.CellRendererText</classname></link>
displaying the Pango markup specified by
<parameter>markup</parameter>.</para>

    </refsect2>

    <refsect2 id="function-gtk--cell-view-new-with-pixbuf">
      <title>gtk.cell_view_new_with_pixbuf</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.cell_view_new_with_pixbuf</methodname>
	  <methodparam><parameter
			 role="keyword">pixbuf</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">pixbuf</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link linkend="class-gdkpixbuf"><classname>gtk.gdk.Pixbuf</classname></link></simpara></listitem>
	</varlistentry>
	<varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a new <link linkend="class-gtkcellview"><classname>gtk.CellView</classname></link></simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
        <para>This function is available in PyGTK 2.6 and above.</para>
      </note>

      <para>The <function>gtk.cell_view_new_with_pixbuf</function>()
function creates a new <link
linkend="class-gtkcellview"><classname>gtk.CellView</classname></link> with
a <link
linkend="class-gtkcellrendererpixbuf"><classname>gtk.CellRendererPixbuf</classname></link>
displaying the <link
linkend="class-gdkpixbuf"><classname>gtk.gdk.Pixbuf</classname></link>
specified by <parameter>pixbuf</parameter>.</para>

    </refsect2>

  </refsect1>

</refentry>