path: root/docs/reference/pygtk-gtkcellrenderertext.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-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>
    <title>Properties</title>

    <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>"text"</entry>
	      <entry>Read/Write</entry>
	<entry>Text to render</entry>
	  </row>

	<row valign="top">
	  <entry>"markup"</entry>
	  <entry>Read/Write</entry>
	  <entry>Marked up text to render</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</entry>
	</row>

	<row valign="top">
	  <entry>"foreground"</entry>
	  <entry>Write</entry>
	  <entry>Foreground color as a string</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>"foreground-gdk"</entry>
	  <entry>Read/Write</entry>
	  <entry>Foreground color as a gtk.gdk.Color</entry>
	</row>

	<row valign="top">
	  <entry>"font"</entry>
	  <entry>Read/Write</entry>
	  <entry>Font description as a string</entry>
	</row>

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

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

	<row valign="top">
	  <entry>"style"</entry>
	  <entry>Read/Write</entry>
	  <entry>Font style</entry>
	</row>

	<row valign="top">
	  <entry>"variant"</entry>
	  <entry>Read/Write</entry>
	  <entry>Font variant</entry>
	</row>

	<row valign="top">
	  <entry>"weight"</entry>
	  <entry>Read/Write</entry>
	  <entry>Font weight</entry>
	</row>

	<row valign="top">
	  <entry>"stretch"</entry>
	  <entry>Read/Write</entry>
	  <entry>Font stretch</entry>
	</row>

	<row valign="top">
	  <entry>"size"</entry>
	  <entry>Read/Write</entry>
	  <entry>Font size</entry>
	</row>

	<row valign="top">
	  <entry>"size-points"</entry>
	  <entry>Read/Write</entry>
	  <entry>Font size in points</entry>
	</row>

	<row valign="top">
	  <entry>"scale"</entry>
	  <entry>Read/Write</entry>
	  <entry>Font scaling factor</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</entry>
	</row>

	<row valign="top">
	  <entry>"strikethrough"</entry>
	  <entry>Read/Write</entry>
	  <entry>If <literal>TRUE</literal> strike through the text</entry>
	</row>

	<row valign="top">
	  <entry>"underline"</entry>
	  <entry>Read/Write</entry>
	  <entry>Style of underline for this text</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)</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.</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.</entry>
	</row>

	<row valign="top">
	  <entry>"background-set"</entry>
	  <entry>Read/Write</entry>
	  <entry>If <literal>TRUE</literal> this tag affects the background
color</entry>
	</row>

	<row valign="top">
	  <entry>"foreground-set"</entry>
	  <entry>Read/Write</entry>
	  <entry>If <literal>TRUE</literal> this tag affects the foreground
color</entry>
	</row>

	<row valign="top">
	  <entry>"family-set"</entry>
	  <entry>Read/Write</entry>
	  <entry>If <literal>TRUE</literal> this tag affects the font
family</entry>
	</row>

	<row valign="top">
	  <entry>"style-set"</entry>
	  <entry>Read/Write</entry>
	  <entry>If <literal>TRUE</literal> this tag affects the font
style</entry>
	</row>

	<row valign="top">
	  <entry>"variant-set"</entry>
	  <entry>Read/Write</entry>
	  <entry>If <literal>TRUE</literal> this tag affects the font
variant</entry>
	</row>

	<row valign="top">
	  <entry>"weight-set"</entry>
	  <entry>Read/Write</entry>
	  <entry>If <literal>TRUE</literal> this tag affects the font
weight</entry>
	</row>

	<row valign="top">
	  <entry>"stretch-set"</entry>
	  <entry>Read/Write</entry>
	  <entry>If <literal>TRUE</literal> this tag affects the font
stretch</entry>
	</row>

	<row valign="top">
	  <entry>"size-set"</entry>
	  <entry>Read/Write</entry>
	  <entry>If <literal>TRUE</literal> this tag affects the font
size</entry>
	</row>

	<row valign="top">
	  <entry>"scale-set"</entry>
	  <entry>Read/Write</entry>
	  <entry>If <literal>TRUE</literal> this tag scales the font</entry>
	</row>

	<row valign="top">
	  <entry>"editable-set"</entry>
	  <entry>Read/Write</entry>
	  <entry>If <literal>TRUE</literal> this tag affects the text
editability</entry>
	</row>

	<row valign="top">
	  <entry>"strikethrough-set"</entry>
	  <entry>Read/Write</entry>
	  <entry>If <literal>TRUE</literal> this tag affects the
strikethrough</entry>
	</row>

	<row valign="top">
	  <entry>"underline-set"</entry>
	  <entry>Read/Write</entry>
	  <entry>If <literal>TRUE</literal> this tag affects the text
underlining</entry>
	</row>

	<row valign="top">
	  <entry>"rise-set"</entry>
	  <entry>Read/Write</entry>
	  <entry>If <literal>TRUE</literal> this tag affects the
rise</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.</entry>
	</row>

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

  </refsect1>

  <refsect1>
    <title>Signal Prototypes</title>

    <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.</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>