<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
<!ENTITY version SYSTEM "version.xml">
]>
<!--ENTITY index-Objects-Grouped SYSTEM "objects_grouped.sgml"-->
<refentry id="GtkComboBoxEntry">
<refmeta>
<refentrytitle role="top_of_page" id="GtkComboBoxEntry.top_of_page">GtkComboBoxEntry</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GTK Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>GtkComboBoxEntry</refname>
<refpurpose>A text entry field with a dropdown list</refpurpose>
</refnamediv>

<refsynopsisdiv id="GtkComboBoxEntry.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>

#include &lt;gtk/gtk.h&gt;

                    <link linkend="GtkComboBoxEntry-struct">GtkComboBoxEntry</link>;
<link linkend="GtkWidget">GtkWidget</link> *         <link linkend="gtk-combo-box-entry-new">gtk_combo_box_entry_new</link>             (void);
<link linkend="GtkWidget">GtkWidget</link> *         <link linkend="gtk-combo-box-entry-new-with-model">gtk_combo_box_entry_new_with_model</link>  (<link linkend="GtkTreeModel">GtkTreeModel</link> *model,
                                                         <link linkend="gint">gint</link> text_column);
<link linkend="GtkWidget">GtkWidget</link> *         <link linkend="gtk-combo-box-entry-new-text">gtk_combo_box_entry_new_text</link>        (void);
<link linkend="void">void</link>                <link linkend="gtk-combo-box-entry-set-text-column">gtk_combo_box_entry_set_text_column</link> (<link linkend="GtkComboBoxEntry">GtkComboBoxEntry</link> *entry_box,
                                                         <link linkend="gint">gint</link> text_column);
<link linkend="gint">gint</link>                <link linkend="gtk-combo-box-entry-get-text-column">gtk_combo_box_entry_get_text_column</link> (<link linkend="GtkComboBoxEntry">GtkComboBoxEntry</link> *entry_box);
</synopsis>
</refsynopsisdiv>

<refsect1 id="GtkComboBoxEntry.object-hierarchy" role="object_hierarchy">
<title role="object_hierarchy.title">Object Hierarchy</title>
<synopsis>
  <link linkend="GObject">GObject</link>
   +----<link linkend="GInitiallyUnowned">GInitiallyUnowned</link>
         +----<link linkend="GtkObject">GtkObject</link>
               +----<link linkend="GtkWidget">GtkWidget</link>
                     +----<link linkend="GtkContainer">GtkContainer</link>
                           +----<link linkend="GtkBin">GtkBin</link>
                                 +----<link linkend="GtkComboBox">GtkComboBox</link>
                                       +----GtkComboBoxEntry
</synopsis>
</refsect1>



<refsect1 id="GtkComboBoxEntry.implemented-interfaces" role="impl_interfaces">
<title role="impl_interfaces.title">Implemented Interfaces</title>
<para>
GtkComboBoxEntry implements
 <link linkend="AtkImplementorIface">AtkImplementorIface</link>,  <link linkend="GtkBuildable">GtkBuildable</link>,  <link linkend="GtkCellEditable">GtkCellEditable</link> and  <link linkend="GtkCellLayout">GtkCellLayout</link>.</para>
</refsect1>


<refsect1 id="GtkComboBoxEntry.properties" role="properties">
<title role="properties.title">Properties</title>
<synopsis>
  &quot;<link linkend="GtkComboBoxEntry--text-column">text-column</link>&quot;              <link linkend="gint">gint</link>                  : Read / Write
</synopsis>
</refsect1>



<refsect1 id="GtkComboBoxEntry.description" role="desc">
<title role="desc.title">Description</title>
<para>
A <link linkend="GtkComboBoxEntry"><type>GtkComboBoxEntry</type></link> is a widget that allows the user to choose from a
list of valid choices or enter a different value. It is very similar
to a <link linkend="GtkComboBox"><type>GtkComboBox</type></link>, but it displays the selected value in an entry to
allow modifying it.
</para>
<para>
In contrast to a <link linkend="GtkComboBox"><type>GtkComboBox</type></link>, the underlying model of a <link linkend="GtkComboBoxEntry"><type>GtkComboBoxEntry</type></link>
must always have a text column (see <link linkend="gtk-combo-box-entry-set-text-column"><function>gtk_combo_box_entry_set_text_column()</function></link>),
and the entry will show the content of the text column in the selected row.
To get the text from the entry, use <link linkend="gtk-combo-box-get-active-text"><function>gtk_combo_box_get_active_text()</function></link>.
</para>
<para>
The changed signal will be emitted while typing into a GtkComboBoxEntry,
as well as when selecting an item from the GtkComboBoxEntry's list. Use
<link linkend="gtk-combo-box-get-active"><function>gtk_combo_box_get_active()</function></link> or <link linkend="gtk-combo-box-get-active-iter"><function>gtk_combo_box_get_active_iter()</function></link> to discover
whether an item was actually selected from the list.
</para>
<para>
Connect to the activate signal of the GtkEntry (use <link linkend="gtk-bin-get-child"><function>gtk_bin_get_child()</function></link>)
to detect when the user actually finishes entering text.
</para>
<para>
The convenience API to construct simple text-only <link linkend="GtkComboBox"><type>GtkComboBox</type></link><!-- -->es
can also be used with <link linkend="GtkComboBoxEntry"><type>GtkComboBoxEntry</type></link><!-- -->s which have been constructed
with <link linkend="gtk-combo-box-entry-new-text"><function>gtk_combo_box_entry_new_text()</function></link>.
</para>
<para>
If you have special needs that go beyond a simple entry (e.g. input validation),
it is possible to replace the child entry by a different widget using
<link linkend="gtk-container-remove"><function>gtk_container_remove()</function></link> and <link linkend="gtk-container-add"><function>gtk_container_add()</function></link>.
</para>
<refsect2 id="GtkComboBoxEntry-BUILDER-UI">
<title>GtkComboBoxEntry as GtkBuildable</title>
<para>
Beyond the &lt;attributes&gt; support that is shared by all
<link linkend="GtkCellLayout-BUILDER-UI">GtkCellLayout</link> implementation,
GtkComboBoxEntry makes the entry available in UI definitions as an internal
child with name "entry".
</para>
</refsect2>
</refsect1>

<refsect1 id="GtkComboBoxEntry.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="GtkComboBoxEntry-struct" role="struct">
<title>GtkComboBoxEntry</title>
<indexterm zone="GtkComboBoxEntry-struct"><primary sortas="ComboBoxEntry">GtkComboBoxEntry</primary></indexterm><programlisting>typedef struct _GtkComboBoxEntry GtkComboBoxEntry;</programlisting>
<para>
</para></refsect2>
<refsect2 id="gtk-combo-box-entry-new" role="function" condition="since:2.4">
<title>gtk_combo_box_entry_new ()</title>
<indexterm zone="gtk-combo-box-entry-new" role="2.4"><primary sortas="combo_box_entry_new">gtk_combo_box_entry_new</primary></indexterm><programlisting><link linkend="GtkWidget">GtkWidget</link> *         gtk_combo_box_entry_new             (void);</programlisting>
<para>
Creates a new <link linkend="GtkComboBoxEntry"><type>GtkComboBoxEntry</type></link> which has a <link linkend="GtkEntry"><type>GtkEntry</type></link> as child. After
construction, you should set a model using <link linkend="gtk-combo-box-set-model"><function>gtk_combo_box_set_model()</function></link> and a
text column using <link linkend="gtk-combo-box-entry-set-text-column"><function>gtk_combo_box_entry_set_text_column()</function></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> A new <link linkend="GtkComboBoxEntry"><type>GtkComboBoxEntry</type></link>.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.4</para></refsect2>
<refsect2 id="gtk-combo-box-entry-new-with-model" role="function" condition="since:2.4">
<title>gtk_combo_box_entry_new_with_model ()</title>
<indexterm zone="gtk-combo-box-entry-new-with-model" role="2.4"><primary sortas="combo_box_entry_new_with_model">gtk_combo_box_entry_new_with_model</primary></indexterm><programlisting><link linkend="GtkWidget">GtkWidget</link> *         gtk_combo_box_entry_new_with_model  (<link linkend="GtkTreeModel">GtkTreeModel</link> *model,
                                                         <link linkend="gint">gint</link> text_column);</programlisting>
<para>
Creates a new <link linkend="GtkComboBoxEntry"><type>GtkComboBoxEntry</type></link> which has a <link linkend="GtkEntry"><type>GtkEntry</type></link> as child and a list
of strings as popup. You can get the <link linkend="GtkEntry"><type>GtkEntry</type></link> from a <link linkend="GtkComboBoxEntry"><type>GtkComboBoxEntry</type></link>
using GTK_ENTRY (GTK_BIN (combo_box_entry)->child). To add and remove
strings from the list, just modify <parameter>model</parameter> using its data manipulation
API.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>model</parameter>&#160;:</term>
<listitem><simpara> A <link linkend="GtkTreeModel"><type>GtkTreeModel</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>text_column</parameter>&#160;:</term>
<listitem><simpara> A column in <parameter>model</parameter> to get the strings from.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> A new <link linkend="GtkComboBoxEntry"><type>GtkComboBoxEntry</type></link>.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.4</para></refsect2>
<refsect2 id="gtk-combo-box-entry-new-text" role="function" condition="since:2.4">
<title>gtk_combo_box_entry_new_text ()</title>
<indexterm zone="gtk-combo-box-entry-new-text" role="2.4"><primary sortas="combo_box_entry_new_text">gtk_combo_box_entry_new_text</primary></indexterm><programlisting><link linkend="GtkWidget">GtkWidget</link> *         gtk_combo_box_entry_new_text        (void);</programlisting>
<para>
Convenience function which constructs a new editable text combo box, which 
is a <link linkend="GtkComboBoxEntry"><type>GtkComboBoxEntry</type></link> just displaying strings. If you use this function to
create a text combo box, you should only manipulate its data source with
the following convenience functions: <link linkend="gtk-combo-box-append-text"><function>gtk_combo_box_append_text()</function></link>,
<link linkend="gtk-combo-box-insert-text"><function>gtk_combo_box_insert_text()</function></link>, <link linkend="gtk-combo-box-prepend-text"><function>gtk_combo_box_prepend_text()</function></link> and
<link linkend="gtk-combo-box-remove-text"><function>gtk_combo_box_remove_text()</function></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> A new text <link linkend="GtkComboBoxEntry"><type>GtkComboBoxEntry</type></link>.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.4</para></refsect2>
<refsect2 id="gtk-combo-box-entry-set-text-column" role="function" condition="since:2.4">
<title>gtk_combo_box_entry_set_text_column ()</title>
<indexterm zone="gtk-combo-box-entry-set-text-column" role="2.4"><primary sortas="combo_box_entry_set_text_column">gtk_combo_box_entry_set_text_column</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_combo_box_entry_set_text_column (<link linkend="GtkComboBoxEntry">GtkComboBoxEntry</link> *entry_box,
                                                         <link linkend="gint">gint</link> text_column);</programlisting>
<para>
Sets the model column which <parameter>entry_box</parameter> should use to get strings from
to be <parameter>text_column</parameter>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>entry_box</parameter>&#160;:</term>
<listitem><simpara> A <link linkend="GtkComboBoxEntry"><type>GtkComboBoxEntry</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>text_column</parameter>&#160;:</term>
<listitem><simpara> A column in <parameter>model</parameter> to get the strings from.
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.4</para></refsect2>
<refsect2 id="gtk-combo-box-entry-get-text-column" role="function" condition="since:2.4">
<title>gtk_combo_box_entry_get_text_column ()</title>
<indexterm zone="gtk-combo-box-entry-get-text-column" role="2.4"><primary sortas="combo_box_entry_get_text_column">gtk_combo_box_entry_get_text_column</primary></indexterm><programlisting><link linkend="gint">gint</link>                gtk_combo_box_entry_get_text_column (<link linkend="GtkComboBoxEntry">GtkComboBoxEntry</link> *entry_box);</programlisting>
<para>
Returns the column which <parameter>entry_box</parameter> is using to get the strings from.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>entry_box</parameter>&#160;:</term>
<listitem><simpara> A <link linkend="GtkComboBoxEntry"><type>GtkComboBoxEntry</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> A column in the data source model of <parameter>entry_box</parameter>.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.4</para></refsect2>

</refsect1>
<refsect1 id="GtkComboBoxEntry.property-details" role="property_details">
<title role="property_details.title">Property Details</title>
<refsect2 id="GtkComboBoxEntry--text-column" role="property"><title>The <literal>&quot;text-column&quot;</literal> property</title>
<indexterm zone="GtkComboBoxEntry--text-column"><primary sortas="ComboBoxEntry:text-column">GtkComboBoxEntry:text-column</primary></indexterm><programlisting>  &quot;text-column&quot;              <link linkend="gint">gint</link>                  : Read / Write</programlisting>
<para>A column in the data source model to get the strings from.</para><para>Allowed values: &gt;= G_MAXULONG</para>
<para>Default value: -1</para>
</refsect2>
</refsect1>



<refsect1 id="GtkComboBoxEntry.see-also">
<title>See Also</title>
<para>
<link linkend="GtkComboBox"><type>GtkComboBox</type></link>
</para>
</refsect1>

</refentry>
