<?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-gtkcellrenderertext">
  <refnamediv>
    <refname>gtk.CellRendererText</refname>

    <refpurpose>an object that renders text into a <link
linkend="class-gtktreeview"><classname>gtk.TreeView</classname></link>
cell</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>gtk.CellRendererText</classname></ooclass>
      <ooclass><classname><link
linkend="class-gtkcellrenderer">gtk.CellRenderer</link></classname></ooclass>
      <constructorsynopsis language="python">
	<methodname><link linkend="constructor-gtkcellrenderertext">gtk.CellRendererText</link></methodname>
	<methodparam></methodparam>  </constructorsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkcellrenderertext--set-fixed-height-from-font">set_fixed_height_from_font</link></methodname>
	<methodparam><parameter
		       role="keyword">number_of_rows</parameter></methodparam>
      </methodsynopsis>
    </classsynopsis>

  </refsect1>

  <refsect1>
    <title>Ancestry</title>

<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link>
  +-- <link linkend="class-gtkobject">gtk.Object</link>
    +-- <link linkend="class-gtkcellrenderer">gtk.CellRenderer</link>
      +-- <link linkend="class-gtkcellrenderertext">gtk.CellRendererText</link>
</synopsis>

  </refsect1>

  <refsect1 id="properties-gtkcellrenderertext">
    <title>gtk.CellRendererText Properties</title>

    <para><link linkend="properties-gtkobject">gtk.Object Properties</link></para>
    <para><link linkend="properties-gtkcellrenderer">gtk.CellRenderer 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="3.5in"/>
	  <tbody>

	<row valign="top">
	  <entry>"alignment"</entry>
	  <entry>Read/Write</entry>
	  <entry>Specifies how to align the lines of text using one of the
	  <xref linkend="pango-alignment-constants"
	  endterm="pango-alignment-constants-title"></xref> Default value:
	  <literal>pango.ALIGN_LEFT</literal>. Note that you probably need the 'xalign' property of
	  <link linked="class-gtkcellrenderer"><classname>gtk.CellRenderer</classname></link>
	  if you want to set the horizontal alignment of the whole text.
	  This property is available in GTK+ 2.10 and above.</entry>
	</row>


	<row valign="top">
	  <entry>"attributes"</entry>
	  <entry>Read/Write</entry>
	  <entry>A list of style attributes to apply to the text of the
renderer.</entry>
	</row>

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

	<row valign="top">
	  <entry>"background-gdk"</entry>
	  <entry>Read/Write</entry>
	  <entry>Background color as a gtk.gdk.Color</entry>
	</row>

	<row valign="top">
	  <entry>"background-set"</entry>
	  <entry>Read/Write</entry>
	  <entry>If <literal>True</literal> this tag affects the background
color. Default: <literal>False</literal></entry>
	</row>

	<row valign="top">
	  <entry>"editable"</entry>
	  <entry>Read/Write</entry>
	  <entry>If <literal>True</literal> the text can be modified by the
user. GTK+ 2.4 and above. Default: <literal>False</literal></entry>
	</row>

	<row valign="top">
	  <entry>"editable-set"</entry>
	  <entry>Read/Write</entry>
	  <entry>If <literal>True</literal> this tag affects the text
editability. GTK+ 2.4 and above. Default: <literal>False</literal></entry>
	</row>

	<row valign="top">
          <entry>"ellipsize"</entry>
	  <entry>Read/Write</entry>
	  <entry>The preferred place to ellipsize the string, if the cell
renderer does not have enough room to display the entire string, if at all.
GTK+ 2.6 and above. Default: <literal>pango.ELLIPSIZE_NONE</literal></entry>
	</row>

	<row valign="top">
	  <entry>"ellipsize-set"</entry>
	  <entry>Read/Write</entry>
	  <entry>If <literal>True</literal> this tag affects the text
editability. Default: <literal>False</literal></entry>
	</row>

	<row valign="top">
	  <entry>"family"</entry>
	  <entry>Read/Write</entry>
	  <entry>Name of the font family, e.g. Sans, Helvetica, Times,
Monospace. Default: <literal>None</literal></entry>
	</row>

	<row valign="top">
	  <entry>"family-set"</entry>
	  <entry>Read/Write</entry>
	  <entry>If <literal>True</literal> this tag affects the font
family. Default: <literal>False</literal></entry>
	</row>

	<row valign="top">
	  <entry>"font"</entry>
	  <entry>Read/Write</entry>
	  <entry>Font description as a string. Default:
<literal>None</literal></entry>
	</row>

	<row valign="top">
	  <entry>"font-desc"</entry>
	  <entry>Read/Write</entry>
	  <entry>Font description as a <link
linkend="class-pangofontdescription"><classname>pango.FontDescription</classname></link></entry>
	</row>

	<row valign="top">
	  <entry>"foreground"</entry>
	  <entry>Write</entry>
	  <entry>Foreground color as a string. Default:
<literal>None</literal></entry>
	</row>

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

	<row valign="top">
	  <entry>"foreground-set"</entry>
	  <entry>Read/Write</entry>
	  <entry>If <literal>True</literal> this tag affects the foreground
color. Default: <literal>False</literal></entry>
	</row>

	<row valign="top">
	  <entry>"language"</entry>
	  <entry>Read/Write</entry>
	  <entry>The language this text is in, as an ISO code. Pango can use
this as a hint when rendering the text. If you don't understand this parameter,
you probably don't need it. GTK+ 2.4 and above. Default:
<literal>None</literal></entry>
	</row>

	<row valign="top">
	  <entry>"language-set"</entry>
	  <entry>Read/Write</entry>
	  <entry>If <literal>True</literal> this tag affects the
language used to render the text. GTK+ 2.4 and above. Default:
<literal>False</literal></entry>
	</row>

	<row valign="top">
	  <entry>"markup"</entry>
	  <entry>Write</entry>
	  <entry>Marked up text to render. Default:
<literal>None</literal></entry>
	</row>

	<row valign="top">
	  <entry>"rise"</entry>
	  <entry>Read/Write</entry>
	  <entry>Offset of text above the baseline (below the baseline if
rise is negative). Default: 0</entry>
	</row>

	<row valign="top">
	  <entry>"rise-set"</entry>
	  <entry>Read/Write</entry>
	  <entry>If <literal>True</literal> this tag affects the
rise. Default: <literal>False</literal></entry>
	</row>

	<row valign="top">
	  <entry>"scale"</entry>
	  <entry>Read/Write</entry>
	  <entry>Font scaling factor. Allowed values &gt;= 0.
Default: 1</entry>
	</row>

	<row valign="top">
	  <entry>"scale-set"</entry>
	  <entry>Read/Write</entry>
	  <entry>If <literal>True</literal> this tag scales the font.
Default: <literal>False</literal></entry>
	</row>

	<row valign="top">
	  <entry>"single-paragraph-mode"</entry>
	  <entry>Read/Write</entry>
	  <entry>If <literal>True</literal>, keep all text in a single
paragraph. GTK+ 2.4 and above. Default: <literal>False</literal></entry>
	</row>

	<row valign="top">
	  <entry>"size"</entry>
	  <entry>Read/Write</entry>
	  <entry>Font size. Allowed values &gt;= 0. Default: 0</entry>
	</row>

	<row valign="top">
	  <entry>"size-points"</entry>
	  <entry>Read/Write</entry>
	  <entry>Font size in points. Allowed values &gt;= 0.
Default: 0</entry>
	</row>

	<row valign="top">
	  <entry>"size-set"</entry>
	  <entry>Read/Write</entry>
	  <entry>If <literal>True</literal> this tag affects the font
size. Default: <literal>False</literal></entry>
	</row>

	<row valign="top">
	  <entry>"stretch"</entry>
	  <entry>Read/Write</entry>
	  <entry>Font stretch. Default:
<literal>pango.STRETCH_NORMAL</literal></entry>
	</row>

	<row valign="top">
	  <entry>"stretch-set"</entry>
	  <entry>Read/Write</entry>
	  <entry>If <literal>True</literal> this tag affects the font
stretch. Default: <literal>False</literal></entry>
	</row>

	<row valign="top">
	  <entry>"strikethrough"</entry>
	  <entry>Read/Write</entry>
	  <entry>If <literal>True</literal> strike through the text.
Default: <literal>False</literal></entry>
	</row>

	<row valign="top">
	  <entry>"strikethrough-set"</entry>
	  <entry>Read/Write</entry>
	  <entry>If <literal>True</literal> this tag affects the
strikethrough. Default: <literal>False</literal></entry>
	</row>

	<row valign="top">
	  <entry>"style"</entry>
	  <entry>Read/Write</entry>
            <entry>Font style. Default:
<literal>pango.STYLE_NORMAL</literal></entry>
	</row>

	<row valign="top">
	  <entry>"style-set"</entry>
	  <entry>Read/Write</entry>
	  <entry>If <literal>True</literal> this tag affects the font
style. Default: <literal>False</literal></entry>
	</row>

        <row valign="top">
          <entry>"text"</entry>
          <entry>Read/Write</entry>
            <entry>Text to render. Default: <literal>None</literal></entry>
	  </row>

	<row valign="top">
	  <entry>"underline"</entry>
	  <entry>Read/Write</entry>
	  <entry>Style of underline for this text.
Default: <literal>pango.UNDERLINE_NONE</literal></entry>
	</row>

	<row valign="top">
	  <entry>"underline-set"</entry>
	  <entry>Read/Write</entry>
	  <entry>If <literal>True</literal> this tag affects the text
underlining. Default: <literal>False</literal></entry>
	</row>

	<row valign="top">
	  <entry>"variant"</entry>
	  <entry>Read/Write</entry>
	  <entry>Font variant. Default:
<literal>pango.VARIANT_NORMAL</literal></entry>
	</row>

	<row valign="top">
	  <entry>"variant-set"</entry>
	  <entry>Read/Write</entry>
	  <entry>If <literal>True</literal> this tag affects the font
variant. Default: <literal>False</literal></entry>
	</row>

	<row valign="top">
	  <entry>"weight"</entry>
	  <entry>Read/Write</entry>
	  <entry>Font weight. Allowed values &gt;= 0. Default value:
400</entry>
	</row>

	<row valign="top">
	  <entry>"weight-set"</entry>
	  <entry>Read/Write</entry>
	  <entry>If <literal>True</literal> this tag affects the font
weight. Default: <literal>False</literal></entry>
	</row>

	<row valign="top">
	  <entry>"width-chars"</entry>
	  <entry>Read/Write</entry> <entry>The desired width of the cell, in
	  characters. If this property is set to -1, the width will be
	  calculated automatically, otherwise the cell will request either 3
	  characters or the property value, whichever is greater. GTK+ 2.6
	  and above.  Allowed values &gt;= -1. Default value: -1</entry>
	</row>

        <row valign="top">
          <entry>"wrap-mode"</entry>
          <entry>Read-Write</entry>
          <entry>Specifies how to break the string into multiple lines, if
          the cell renderer does not have enough room to display the entire
          string.  This property has no effect unless the "wrap-width"
          property is set.  This property is available in GTK+ 2.8 and
          above.</entry>
        </row>

        <row valign="top">
          <entry>"wrap-width"</entry>
          <entry>Read-Write</entry>
          <entry>Specifies the width at which the text is wrapped. The
          "wrap-mode" property can be used to influence at what character
          positions the line breaks can be placed.  Setting "wrap-width" to
          -1 turns wrapping off.  This property is available in GTK+ 2.8 and
          above.</entry>
        </row>

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

  </refsect1>

  <refsect1 id="signal-prototypes-gtkcellrenderertext">
    <title>gtk.CellRendererText 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-gtkcellrenderer">gtk.CellRenderer Signal Prototypes</link></para>

    <variablelist>
      <varlistentry>
        <term>"<link
linkend="signal-gtkcellrenderertext--edited">edited</link>"</term>
        <listitem>
          <methodsynopsis
	    language="python"><methodname>callback</methodname>
            <methodparam><parameter>cellrenderertext</parameter>
            </methodparam>
            <methodparam><parameter>path</parameter>
            </methodparam>
            <methodparam><parameter>new_text</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-gtkcellrenderertext"><classname>gtk.CellRendererText</classname></link>
    manages the rendering of text into a <link
    linkend="class-gtktreeview"><classname>gtk.TreeView</classname></link>
    cell, using the font, color and style information provided by its
    properties. The text will be ellipsized if it is too long and the
    "ellipsize" property allows it.</para>

  </refsect1>

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

    <programlisting><constructorsynopsis language="python">
	<methodname>gtk.CellRendererText</methodname>
	<methodparam></methodparam>  </constructorsynopsis></programlisting>
    <variablelist>
      <varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	<listitem><simpara>the new cell renderer</simpara></listitem>
      </varlistentry>
    </variablelist>

    <para>Creates a new <link
linkend="class-gtkcellrenderertext"><classname>gtk.CellRendererText</classname></link>. 
The way that text is drawn is changed using object properties. The object
properties can be set globally (with <link
linkend="method-gobject--set-property"><methodname>set_property</methodname>()</link>). 
Also, with <link
linkend="class-gtktreeviewcolumn"><classname>gtk.TreeViewColumn</classname></link>, 
you can bind a property to a value in a <link
linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link>.
For example, you can bind the "text" property on the cell renderer to a
string value in the model, thus rendering a different string in each row of
the <link
linkend="class-gtktreeview"><classname>gtk.TreeView</classname></link>.</para>

  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-gtkcellrenderertext--set-fixed-height-from-font">
      <title>gtk.CellRendererText.set_fixed_height_from_font</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_fixed_height_from_font</methodname>
	  <methodparam><parameter
			 role="keyword">number_of_rows</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
role="keyword">number_of_rows</parameter>&nbsp;:</term>
	  <listitem><simpara>Number of rows of text each cell renderer is
allocated, or -1</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_fixed_height_from_font</methodname>() sets
the height of a renderer to explicitly be determined by the "font" and
"ypad" properties set on it.  This method must be called each time these
properties are changed to affect the height.  This function is inflexible,
and should really only be used if calculating the size of a cell is too slow
(i.e. a massive number of cells displayed).  If
<parameter>number_of_rows</parameter> is -1, then the fixed height is unset,
and the height is determined by the properties again.</para>

    </refsect2>

  </refsect1>

  <refsect1>
    <title>Signals</title>

    <refsect2 id="signal-gtkcellrenderertext--edited">
      <title>The "edited" gtk.CellRendererText Signal</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>callback</methodname>
	  <methodparam><parameter>cellrenderertext</parameter></methodparam>
	  <methodparam><parameter>path</parameter></methodparam>
	  <methodparam><parameter>new_text</parameter></methodparam>
	  <methodparam><parameter>user_param1</parameter></methodparam>
	  <methodparam><parameter>...</parameter></methodparam>
	</methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
	  <term><parameter>cellrenderertext</parameter>&nbsp;:</term>
	  <listitem><simpara>the cellrenderertext that received the
"edited" signal</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>path</parameter>&nbsp;:</term>
	  <listitem><simpara>the path string of the
cellrenderertext</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>new_text</parameter>&nbsp;:</term>
	  <listitem><simpara>the new text of the
cellrenderertext</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>user_param1</parameter>&nbsp;:</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>&nbsp;:</term>
	  <listitem><simpara>additional user parameters (if
any)</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The "edited" signal is emitted when the text in the cell has
been edited.</para>

    </refsect2>

  </refsect1>

</refentry>
