path: root/docs/reference/pygtk-gtkcomboboxentry.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-gtkcomboboxentry">
  <refnamediv>
    <refname>gtk.ComboBoxEntry</refname> <refpurpose>a text entry field with
    a dropdown list (new in PyGTK 2.4)</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>gtk.ComboBoxEntry</classname></ooclass>
      <ooclass><classname><link linkend="class-gtkcombobox">gtk.ComboBox</link></classname></ooclass>
      <ooclass><classname><link linkend="class-gtkcelllayout">gtk.CellLayout</link></classname></ooclass>
      <constructorsynopsis language="python">
	<methodname><link linkend="constructor-gtkcomboboxentry">gtk.ComboBoxEntry</link></methodname>
	<methodparam><parameter role="keyword">model</parameter><initializer>None</initializer></methodparam>
	<methodparam><parameter role="keyword">column</parameter><initializer>-1</initializer></methodparam>
      </constructorsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkcomboboxentry--set-text-column">set_text_column</link></methodname>
	<methodparam><parameter role="keyword">text_column</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkcomboboxentry--get-text-column">get_text_column</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
    </classsynopsis>

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

<methodsynopsis language="python">
	<methodname><link linkend="function-gtk--combo-box-entry-new-text">gtk.combo_box_entry_new_text</link></methodname>
	<methodparam></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-gtkcontainer">gtk.Container</link>
        +-- <link linkend="class-gtkbin">gtk.Bin</link>
          +-- <link linkend="class-gtkcombobox">gtk.ComboBox</link>
            +-- <link linkend="class-gtkcomboboxentry">gtk.ComboBoxEntry</link>
</synopsis>

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


  <refsect1 id="properties-gtkcomboboxentry">
    <title>gtk.ComboBoxEntry Properties</title>

    <para><link linkend="properties-gtkobject">gtk.Object Properties</link></para>
    <para><link linkend="properties-gtkwidget">gtk.Widget Properties</link></para>
    <para><link linkend="properties-gtkcontainer">gtk.Container Properties</link></para>
    <para><link linkend="properties-gtkcombobox">gtk.ComboBox 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>"text-column"</entry>
	      <entry>Read-Write</entry>
	      <entry>The column in the <link
	      linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link>
	      to get the strings from.</entry>
	    </row>

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

  </refsect1>

  <refsect1 id="style-properties-gtkcomboboxentry">
    <title>gtk.ComboBoxEntry Style Properties</title>

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

  </refsect1>

  <refsect1 id="signal-prototypes-gtkcomboboxentry">
    <title>gtk.ComboBoxEntry 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>
    <para><link linkend="signal-prototypes-gtkcontainer">gtk.Container Signal Prototypes</link></para>
    <para><link linkend="signal-prototypes-gtkcombobox">gtk.ComboBox Signal Prototypes</link></para>
    <para><link linkend="signal-prototypes-gtkcelleditable">gtk.CellEditable Signal Prototypes</link></para>
  </refsect1>

  <refsect1>
    <title>Description</title>

    <note>
      <para>This widget is available in GTK+ 2.4 and PyGTK 2.4 and
      above.</para> </note>
 
    <para>The <link
linkend="class-gtkcomboboxentry"><classname>gtk.ComboBoxEntry</classname></link>
is a replacement for the <link
linkend="class-gtkcombo"><classname>gtk.Combo</classname></link>. The <link
linkend="class-gtkcomboboxentry"><classname>gtk.ComboBoxEntry</classname></link>
is subclassed from <link
linkend="class-gtkcombobox"><classname>gtk.ComboBox</classname></link> and
implements the <link
linkend="class-gtkcelllayout"><classname>gtk.CellLayout</classname></link>
interface; refer to their descriptions for a number of useful methods and
properties for managing the contents of a combo box entry. A <link
linkend="class-gtkcomboboxentry"><classname>gtk.ComboBoxEntry</classname></link>
also contains a child <link
linkend="class-gtkentry"><classname>gtk.Entry</classname></link> accessed by
using the child attribute of the combo box entry:</para>

    <programlisting>
  entry = comboboxentry.child
</programlisting>

    <para>A <link
linkend="class-gtkcomboboxentry"><classname>gtk.ComboBoxEntry</classname></link>
is created with the <link
linkend="constructor-gtkcomboboxentry">gtk.ComboBoxEntry()</link>
constructor. The constructor can also be called with the optional parameters
<parameter>model</parameter> (a <link
linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link> -
default <literal>None</literal>) and <parameter>column</parameter> (a number
of a column in <parameter>model</parameter> - default 0). If no <link
linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link> is
specified it can be added later with the <link
linkend="method-gtkcombobox--set-model"><methodname>set_model</methodname>()</link>
method. The text column can be changed using the <link
linkend="method-gtkcomboboxentry--set-text-column"><methodname>set_text_column</methodname>()</link>
method. A new combo box entry is created and packed with a <link
linkend="class-gtkcellrenderertext"><classname>gtk.CellRendererText</classname></link>
but no attribute mappings are set on the cell renderer.</para>
 
    <para>Alternatively, the <link
linkend="function-gtk--combo-box-entry-new-text"><function>gtk.combo_box_entry_new_text</function>()</link>
function creates a <link
linkend="class-gtkcomboboxentry"><classname>gtk.ComboBoxEntry</classname></link>
with an associated <link
linkend="class-gtkliststore"><classname>gtk.ListStore</classname></link>
model and the text column attribute mapping set to 0. In this combo box
entry each list item is a text string that can be selected.  The convenience
methods <link
linkend="method-gtkcombobox--append-text"><methodname>gtk.ComboBox.append_text</methodname>()</link>,
<link
linkend="method-gtkcombobox--prepend-text"><methodname>gtk.ComboBox.prepend_text</methodname>()</link>,
<link
linkend="method-gtkcombobox--insert-text"><methodname>gtk.ComboBox.insert_text</methodname>()</link>
and <link
linkend="method-gtkcombobox--remove-text"><methodname>gtk.ComboBox.remove_text</methodname>()</link>
can be used to manage the contents of the <link
linkend="class-gtkcomboboxentry"><classname>gtk.ComboBoxEntry</classname></link>. Using
the <link
linkend="function-gtk--combo-box-entry-new-text"><function>gtk.combo_box_entry_new_text</function>()</link>
function is equivalent to:</para>
                                                                                
    <programlisting>
  liststore = gtk.ListStore(gobject.TYPE_STRING)
  comboboxentry = gtk.ComboBoxEntry(liststore, 0)
</programlisting>

  </refsect1>

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

    <programlisting><constructorsynopsis language="python">
	<methodname>gtk.ComboBoxEntry</methodname>
	<methodparam><parameter role="keyword">model</parameter><initializer>None</initializer></methodparam>
	<methodparam><parameter role="keyword">column</parameter><initializer>-1</initializer></methodparam>
      </constructorsynopsis></programlisting>
    <variablelist>
      <varlistentry>
	<term><parameter role="keyword">model</parameter>&nbsp;:</term>
	<listitem><simpara>The <link
	linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link>
	to associate with the combo box entry, or
	<literal>None</literal></simpara></listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter role="keyword">column</parameter>&nbsp;:</term>
	<listitem><simpara>The number of the column to use for setting the
	strings of the combo box entry.</simpara></listitem>
      </varlistentry>
      <varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	<listitem><simpara>A new <link
	linkend="class-gtkcomboboxentry"><classname>gtk.ComboBoxEntry</classname></link>.</simpara></listitem>
      </varlistentry>
    </variablelist>

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

    <para>Creates a new <link
linkend="class-gtkcomboboxentry"><classname>gtk.ComboBoxEntry</classname></link>
that has a <link
linkend="class-gtkentry"><classname>gtk.Entry</classname></link> as child
and associated with the <link
linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link>
specified by <parameter>model</parameter> and using the column of
<parameter>model</parameter> specified by <parameter>column</parameter> to
retrieve strings. If <parameter>model</parameter> was not specified it
defaults to <literal>None</literal> but you can change the model using the
<link
linkend="method-gtkcombobox--set-model"><methodname>gtk.ComboBox.set_model()</methodname></link>
method. If <parameter>column</parameter> was not specified it defaults to -1
meaning the text column is unset but you can change it using the <link
linkend="method-gtkcomboboxentry--set-text-column"><methodname>set_text_column</methodname>()</link>
method. Once the text column is set either in the constructor or using the
<link
linkend="method-gtkcomboboxentry--set-text-column"><methodname>set_text_column</methodname>()</link>
method it cannot be changed. A ValueError exception is thrown if
<parameter>column</parameter> is outside the range of column numbers for
<parameter>model</parameter>.</para>

  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-gtkcomboboxentry--set-text-column">
      <title>gtk.ComboBoxEntry.set_text_column</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_text_column</methodname>
	  <methodparam><parameter role="keyword">text_column</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
	  role="keyword">text_column</parameter>&nbsp;:</term>
	  <listitem><simpara>A column in the associated <link
	  linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link>
	  to use as the data source for the strings.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>set_text_column</methodname>() method sets the
"text-column" property to the value of <parameter>tree_column</parameter>
only if the text column has not been set (that is, "text-column" is -1). The
value of <parameter>tree_column</parameter> is the number of the tree model
column used as the data source for the strings of the combo box
entry.</para>

    </refsect2>

    <refsect2 id="method-gtkcomboboxentry--get-text-column">
      <title>gtk.ComboBoxEntry.get_text_column</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_text_column</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>The number of the column in the associated
	  <link
	  linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link>
	  used as the data source for the combo box
	  entry.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>get_text_column</methodname>() method returns
the number of the <link
linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link>
column that is used as the data source for the strings of the combo box
entry.</para>

    </refsect2>

  </refsect1>

  <refsect1>
    <title>Functions</title>

    <refsect2 id="function-gtk--combo-box-entry-new-text">
      <title>gtk.combo_box_entry_new_text</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>gtk.combo_box_entry_new_text</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>A new <link
	  linkend="class-gtkcomboboxentry"><classname>gtk.ComboBoxEntry</classname></link>
	  widget.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <function>gtk.combo_box_entry_new_text</function>() function
is a convenience function which constructs a new <link
linkend="class-gtkcomboboxentry"><classname>gtk.ComboBoxEntry</classname></link>,
just displaying strings. If you use this function to create a combo box
entry, you should only manipulate its <link
linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link>
data source with the following <link
linkend="class-gtkcombobox"><classname>gtk.ComboBox</classname></link>
convenience methods: <link
linkend="method-gtkcombobox--append-text"><methodname>gtk.ComboBox.append_text</methodname>()</link>,
<link
linkend="method-gtkcombobox--insert-text"><methodname>gtk.ComboBox.insert_text</methodname>()</link>,
<link
linkend="method-gtkcombobox--prepend-text"><methodname>gtk.ComboBox.prepend_text</methodname>()</link>
and <link
linkend="method-gtkcombobox--remove-text"><methodname>gtk.ComboBox.remove_text</methodname>()</link>.</para>

    </refsect2>

  </refsect1>

</refentry>