<?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="GtkCombo">
<refmeta>
<refentrytitle role="top_of_page" id="GtkCombo.top_of_page">GtkCombo</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GTK Library</refmiscinfo>
</refmeta>

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

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

<synopsis>

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

                    <link linkend="GtkCombo-struct">GtkCombo</link>;
<link linkend="GtkWidget">GtkWidget</link>*          <link linkend="gtk-combo-new">gtk_combo_new</link>                       (void);
<link linkend="void">void</link>                <link linkend="gtk-combo-set-popdown-strings">gtk_combo_set_popdown_strings</link>       (<link linkend="GtkCombo">GtkCombo</link> *combo,
                                                         <link linkend="GList">GList</link> *strings);
<link linkend="void">void</link>                <link linkend="gtk-combo-set-value-in-list">gtk_combo_set_value_in_list</link>         (<link linkend="GtkCombo">GtkCombo</link> *combo,
                                                         <link linkend="gboolean">gboolean</link> val,
                                                         <link linkend="gboolean">gboolean</link> ok_if_empty);
<link linkend="void">void</link>                <link linkend="gtk-combo-set-use-arrows">gtk_combo_set_use_arrows</link>            (<link linkend="GtkCombo">GtkCombo</link> *combo,
                                                         <link linkend="gboolean">gboolean</link> val);
<link linkend="void">void</link>                <link linkend="gtk-combo-set-use-arrows-always">gtk_combo_set_use_arrows_always</link>     (<link linkend="GtkCombo">GtkCombo</link> *combo,
                                                         <link linkend="gboolean">gboolean</link> val);
<link linkend="void">void</link>                <link linkend="gtk-combo-set-case-sensitive">gtk_combo_set_case_sensitive</link>        (<link linkend="GtkCombo">GtkCombo</link> *combo,
                                                         <link linkend="gboolean">gboolean</link> val);
<link linkend="void">void</link>                <link linkend="gtk-combo-set-item-string">gtk_combo_set_item_string</link>           (<link linkend="GtkCombo">GtkCombo</link> *combo,
                                                         <link linkend="GtkItem">GtkItem</link> *item,
                                                         const <link linkend="gchar">gchar</link> *item_value);
<link linkend="void">void</link>                <link linkend="gtk-combo-disable-activate">gtk_combo_disable_activate</link>          (<link linkend="GtkCombo">GtkCombo</link> *combo);
</synopsis>
</refsynopsisdiv>

<refsect1 id="GtkCombo.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="GtkBox">GtkBox</link>
                                 +----<link linkend="GtkHBox">GtkHBox</link>
                                       +----GtkCombo
</synopsis>
</refsect1>



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


<refsect1 id="GtkCombo.properties" role="properties">
<title role="properties.title">Properties</title>
<synopsis>
  &quot;<link linkend="GtkCombo--allow-empty">allow-empty</link>&quot;              <link linkend="gboolean">gboolean</link>              : Read / Write
  &quot;<link linkend="GtkCombo--case-sensitive">case-sensitive</link>&quot;           <link linkend="gboolean">gboolean</link>              : Read / Write
  &quot;<link linkend="GtkCombo--enable-arrow-keys">enable-arrow-keys</link>&quot;        <link linkend="gboolean">gboolean</link>              : Read / Write
  &quot;<link linkend="GtkCombo--enable-arrows-always">enable-arrows-always</link>&quot;     <link linkend="gboolean">gboolean</link>              : Read / Write
  &quot;<link linkend="GtkCombo--value-in-list">value-in-list</link>&quot;            <link linkend="gboolean">gboolean</link>              : Read / Write
</synopsis>
</refsect1>



<refsect1 id="GtkCombo.description" role="desc">
<title role="desc.title">Description</title>
<para>
The <link linkend="GtkCombo"><type>GtkCombo</type></link> widget consists of a single-line text entry field and a drop-down
list. The drop-down list is displayed when the user clicks on a small arrow
button to the right of the entry field.
</para>
<para>
The drop-down list is a <link linkend="GtkList"><type>GtkList</type></link> widget and can be accessed using the
<structfield>list</structfield> member of the <link linkend="GtkCombo-struct"><type>GtkCombo</type></link>.
List elements can contain arbitrary widgets, but if an element is not a
plain label, then you must use the <link linkend="gtk-list-set-item-string"><function>gtk_list_set_item_string()</function></link> function.
This sets the string which will be placed in the text entry field when the
item is selected.
</para>
<para>
By default, the user can step through the items in the list using the
arrow (cursor) keys, though this behaviour can be turned off with
<link linkend="gtk-combo-set-use-arrows"><function>gtk_combo_set_use_arrows()</function></link>.
</para>
<para>
As of GTK+ 2.4, <link linkend="GtkCombo"><type>GtkCombo</type></link> has been deprecated in favor of <link linkend="GtkComboBoxEntry"><type>GtkComboBoxEntry</type></link>.
</para>
<example id="gtkcombo-simple-example">
<title>Creating a <structname>GtkCombo</structname> widget with simple text
items.</title>
<programlisting>
  GtkWidget *combo;
  GList *items = NULL;
  items = g_list_append (items, "First Item");
  items = g_list_append (items, "Second Item");
  items = g_list_append (items, "Third Item");
  items = g_list_append (items, "Fourth Item");
  items = g_list_append (items, "Fifth Item");
  combo = gtk_combo_new (<!-- -->);
  gtk_combo_set_popdown_strings (GTK_COMBO (combo), items);
</programlisting>
</example>
<example>
<title>Creating a <structname>GtkCombo</structname> widget with a complex item.</title>
<programlisting>
  GtkWidget *combo, *item, *hbox, *arrow, *label;
  combo = gtk_combo_new (<!-- -->);
  item = gtk_list_item_new (<!-- -->);
  gtk_widget_show (item);
  /* You can put almost anything into the GtkListItem widget. Here we will use
     a horizontal box with an arrow and a label in it. */
  hbox = gtk_hbox_new (FALSE, 3);
  gtk_container_add (GTK_CONTAINER (item), hbox);
  gtk_widget_show (hbox);
  arrow = gtk_arrow_new (GTK_ARROW_RIGHT, GTK_SHADOW_OUT);
  gtk_widget_show (arrow);
  gtk_box_pack_start (GTK_BOX (hbox), arrow, FALSE, FALSE, 0);
  label = gtk_label_new ("First Item");
  gtk_widget_show (label);
  gtk_box_pack_start (GTK_BOX (hbox), label, FALSE, FALSE, 0);
  /* You must set the string to display in the entry field when the item is
     selected. */
  gtk_combo_set_item_string (GTK_COMBO (combo), GTK_ITEM (item), "1st Item");
  /* Now we simply add the item to the combo's list. */
  gtk_container_add (GTK_CONTAINER (GTK_COMBO (combo)->list), item);
</programlisting>
</example>
</refsect1>

<refsect1 id="GtkCombo.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="GtkCombo-struct" role="struct">
<title>GtkCombo</title>
<indexterm zone="GtkCombo-struct" role="deprecated"><primary sortas="Combo">GtkCombo</primary></indexterm><programlisting>typedef struct {
	GtkWidget *entry;
	
	GtkWidget *list;
} GtkCombo;
</programlisting>
<warning><para><literal>GtkCombo</literal> has been deprecated since version 2.4 and should not be used in newly-written code. Use <link linkend="GtkComboBox"><type>GtkComboBox</type></link> instead.</para></warning>
<para>
The <link linkend="GtkCombo-struct"><type>GtkCombo</type></link> struct contains the following fields.
(These fields should be considered read-only. They should never be set by
an application.)
</para><variablelist role="struct">
<varlistentry>
<term><link linkend="GtkWidget">GtkWidget</link>&#160;*<structfield>entry</structfield>;</term>
<listitem><simpara>the text entry field.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><link linkend="GtkWidget">GtkWidget</link>&#160;*<structfield>list</structfield>;</term>
<listitem><simpara>the list shown in the drop-down window.
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-combo-new" role="function" condition="deprecated:2.4: Use #GtkComboBox instead.">
<title>gtk_combo_new ()</title>
<indexterm zone="gtk-combo-new" role="deprecated"><primary sortas="combo_new">gtk_combo_new</primary></indexterm><programlisting><link linkend="GtkWidget">GtkWidget</link>*          gtk_combo_new                       (void);</programlisting>
<warning><para><literal>gtk_combo_new</literal> has been deprecated since version 2.4 and should not be used in newly-written code. Use <link linkend="GtkComboBox"><type>GtkComboBox</type></link> instead.</para></warning>
<para>
Creates a new <link linkend="GtkCombo"><type>GtkCombo</type></link>.
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a new <link linkend="GtkCombo"><type>GtkCombo</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-combo-set-popdown-strings" role="function" condition="deprecated:2.4: Use #GtkComboBox instead.">
<title>gtk_combo_set_popdown_strings ()</title>
<indexterm zone="gtk-combo-set-popdown-strings" role="deprecated"><primary sortas="combo_set_popdown_strings">gtk_combo_set_popdown_strings</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_combo_set_popdown_strings       (<link linkend="GtkCombo">GtkCombo</link> *combo,
                                                         <link linkend="GList">GList</link> *strings);</programlisting>
<warning><para><literal>gtk_combo_set_popdown_strings</literal> has been deprecated since version 2.4 and should not be used in newly-written code. Use <link linkend="GtkComboBox"><type>GtkComboBox</type></link> instead.</para></warning>
<para>
Convenience function to set all of the items in the popup list.
(See the <link linkend="gtkcombo-simple-example">example</link> above.)
</para><variablelist role="params">
<varlistentry><term><parameter>combo</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GtkCombo"><type>GtkCombo</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>strings</parameter>&#160;:</term>
<listitem><simpara>a list of strings, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> to clear the popup list
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-combo-set-value-in-list" role="function" condition="deprecated:2.4: Use #GtkComboBox instead.">
<title>gtk_combo_set_value_in_list ()</title>
<indexterm zone="gtk-combo-set-value-in-list" role="deprecated"><primary sortas="combo_set_value_in_list">gtk_combo_set_value_in_list</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_combo_set_value_in_list         (<link linkend="GtkCombo">GtkCombo</link> *combo,
                                                         <link linkend="gboolean">gboolean</link> val,
                                                         <link linkend="gboolean">gboolean</link> ok_if_empty);</programlisting>
<warning><para><literal>gtk_combo_set_value_in_list</literal> has been deprecated since version 2.4 and should not be used in newly-written code. Use <link linkend="GtkComboBox"><type>GtkComboBox</type></link> instead.</para></warning>
<para>
Specifies whether the value entered in the text entry field must match one of
the values in the list. If this is set then the user will not be able to
perform any other action until a valid value has been entered.
</para>
<para>
If an empty field is acceptable, the <parameter>ok_if_empty</parameter> parameter should be <link linkend="TRUE--CAPS"><literal>TRUE</literal></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>combo</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GtkCombo"><type>GtkCombo</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>val</parameter>&#160;:</term>
<listitem><simpara>%TRUE if the value entered must match one of the values in the list.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>ok_if_empty</parameter>&#160;:</term>
<listitem><simpara>%TRUE if an empty value is considered valid.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-combo-set-use-arrows" role="function" condition="deprecated:2.4: Use #GtkComboBox instead.">
<title>gtk_combo_set_use_arrows ()</title>
<indexterm zone="gtk-combo-set-use-arrows" role="deprecated"><primary sortas="combo_set_use_arrows">gtk_combo_set_use_arrows</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_combo_set_use_arrows            (<link linkend="GtkCombo">GtkCombo</link> *combo,
                                                         <link linkend="gboolean">gboolean</link> val);</programlisting>
<warning><para><literal>gtk_combo_set_use_arrows</literal> has been deprecated since version 2.4 and should not be used in newly-written code. Use <link linkend="GtkComboBox"><type>GtkComboBox</type></link> instead.</para></warning>
<para>
Specifies if the arrow (cursor) keys can be used to step through the items in
the list. This is on by default.
</para><variablelist role="params">
<varlistentry><term><parameter>combo</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GtkCombo"><type>GtkCombo</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>val</parameter>&#160;:</term>
<listitem><simpara>%TRUE if the arrow keys can be used to step through the items in 
     the list.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-combo-set-use-arrows-always" role="function" condition="deprecated:2.4: Use #GtkComboBox instead.">
<title>gtk_combo_set_use_arrows_always ()</title>
<indexterm zone="gtk-combo-set-use-arrows-always" role="deprecated"><primary sortas="combo_set_use_arrows_always">gtk_combo_set_use_arrows_always</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_combo_set_use_arrows_always     (<link linkend="GtkCombo">GtkCombo</link> *combo,
                                                         <link linkend="gboolean">gboolean</link> val);</programlisting>
<warning><para><literal>gtk_combo_set_use_arrows_always</literal> has been deprecated since version 2.4 and should not be used in newly-written code. Use <link linkend="GtkComboBox"><type>GtkComboBox</type></link> instead.</para></warning>
<para>
Obsolete function, does nothing.
</para><variablelist role="params">
<varlistentry><term><parameter>combo</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GtkCombo"><type>GtkCombo</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>val</parameter>&#160;:</term>
<listitem><simpara>unused
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-combo-set-case-sensitive" role="function" condition="deprecated:2.4: Use #GtkComboBox instead.">
<title>gtk_combo_set_case_sensitive ()</title>
<indexterm zone="gtk-combo-set-case-sensitive" role="deprecated"><primary sortas="combo_set_case_sensitive">gtk_combo_set_case_sensitive</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_combo_set_case_sensitive        (<link linkend="GtkCombo">GtkCombo</link> *combo,
                                                         <link linkend="gboolean">gboolean</link> val);</programlisting>
<warning><para><literal>gtk_combo_set_case_sensitive</literal> has been deprecated since version 2.4 and should not be used in newly-written code. Use <link linkend="GtkComboBox"><type>GtkComboBox</type></link> instead.</para></warning>
<para>
Specifies whether the text entered into the <link linkend="GtkEntry"><type>GtkEntry</type></link> field and the text in
the list items is case sensitive.
</para>
<para>
This may be useful, for example, when you have called
<link linkend="gtk-combo-set-value-in-list"><function>gtk_combo_set_value_in_list()</function></link> to limit the values entered, but you are not
worried about differences in case.
</para><variablelist role="params">
<varlistentry><term><parameter>combo</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GtkCombo"><type>GtkCombo</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>val</parameter>&#160;:</term>
<listitem><simpara>%TRUE if the text in the list items is case sensitive.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-combo-set-item-string" role="function" condition="deprecated:2.4: Use #GtkComboBox instead.">
<title>gtk_combo_set_item_string ()</title>
<indexterm zone="gtk-combo-set-item-string" role="deprecated"><primary sortas="combo_set_item_string">gtk_combo_set_item_string</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_combo_set_item_string           (<link linkend="GtkCombo">GtkCombo</link> *combo,
                                                         <link linkend="GtkItem">GtkItem</link> *item,
                                                         const <link linkend="gchar">gchar</link> *item_value);</programlisting>
<warning><para><literal>gtk_combo_set_item_string</literal> has been deprecated since version 2.4 and should not be used in newly-written code. Use <link linkend="GtkComboBox"><type>GtkComboBox</type></link> instead.</para></warning>
<para>
Sets the string to place in the <link linkend="GtkEntry"><type>GtkEntry</type></link> field when a particular list item is
selected. This is needed if the list item is not a simple label.
</para><variablelist role="params">
<varlistentry><term><parameter>combo</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GtkCombo"><type>GtkCombo</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>item</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GtkItem"><type>GtkItem</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>item_value</parameter>&#160;:</term>
<listitem><simpara>the string to place in the <link linkend="GtkEntry"><type>GtkEntry</type></link> when <parameter>item</parameter> is selected.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gtk-combo-disable-activate" role="function" condition="deprecated:2.4: Use #GtkComboBox instead.">
<title>gtk_combo_disable_activate ()</title>
<indexterm zone="gtk-combo-disable-activate" role="deprecated"><primary sortas="combo_disable_activate">gtk_combo_disable_activate</primary></indexterm><programlisting><link linkend="void">void</link>                gtk_combo_disable_activate          (<link linkend="GtkCombo">GtkCombo</link> *combo);</programlisting>
<warning><para><literal>gtk_combo_disable_activate</literal> has been deprecated since version 2.4 and should not be used in newly-written code. Use <link linkend="GtkComboBox"><type>GtkComboBox</type></link> instead.</para></warning>
<para>
Stops the <link linkend="GtkCombo"><type>GtkCombo</type></link> widget from showing the popup list when the <link linkend="GtkEntry"><type>GtkEntry</type></link>
emits the "activate" signal, i.e. when the Return key is pressed.
This may be useful if, for example, you want the Return key to close a dialog
instead.
</para><variablelist role="params">
<varlistentry><term><parameter>combo</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GtkCombo"><type>GtkCombo</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>
<refsect1 id="GtkCombo.property-details" role="property_details">
<title role="property_details.title">Property Details</title>
<refsect2 id="GtkCombo--allow-empty" role="property"><title>The <literal>&quot;allow-empty&quot;</literal> property</title>
<indexterm zone="GtkCombo--allow-empty"><primary sortas="Combo:allow-empty">GtkCombo:allow-empty</primary></indexterm><programlisting>  &quot;allow-empty&quot;              <link linkend="gboolean">gboolean</link>              : Read / Write</programlisting>
<para>Whether an empty value may be entered in this field.</para><para>Default value: TRUE</para>
</refsect2>
<refsect2 id="GtkCombo--case-sensitive" role="property"><title>The <literal>&quot;case-sensitive&quot;</literal> property</title>
<indexterm zone="GtkCombo--case-sensitive"><primary sortas="Combo:case-sensitive">GtkCombo:case-sensitive</primary></indexterm><programlisting>  &quot;case-sensitive&quot;           <link linkend="gboolean">gboolean</link>              : Read / Write</programlisting>
<para>Whether list item matching is case sensitive.</para><para>Default value: FALSE</para>
</refsect2>
<refsect2 id="GtkCombo--enable-arrow-keys" role="property"><title>The <literal>&quot;enable-arrow-keys&quot;</literal> property</title>
<indexterm zone="GtkCombo--enable-arrow-keys"><primary sortas="Combo:enable-arrow-keys">GtkCombo:enable-arrow-keys</primary></indexterm><programlisting>  &quot;enable-arrow-keys&quot;        <link linkend="gboolean">gboolean</link>              : Read / Write</programlisting>
<para>Whether the arrow keys move through the list of items.</para><para>Default value: TRUE</para>
</refsect2>
<refsect2 id="GtkCombo--enable-arrows-always" role="property"><title>The <literal>&quot;enable-arrows-always&quot;</literal> property</title>
<indexterm zone="GtkCombo--enable-arrows-always"><primary sortas="Combo:enable-arrows-always">GtkCombo:enable-arrows-always</primary></indexterm><programlisting>  &quot;enable-arrows-always&quot;     <link linkend="gboolean">gboolean</link>              : Read / Write</programlisting>
<para>Obsolete property, ignored.</para><para>Default value: TRUE</para>
</refsect2>
<refsect2 id="GtkCombo--value-in-list" role="property"><title>The <literal>&quot;value-in-list&quot;</literal> property</title>
<indexterm zone="GtkCombo--value-in-list"><primary sortas="Combo:value-in-list">GtkCombo:value-in-list</primary></indexterm><programlisting>  &quot;value-in-list&quot;            <link linkend="gboolean">gboolean</link>              : Read / Write</programlisting>
<para>Whether entered values must already be present in the list.</para><para>Default value: FALSE</para>
</refsect2>
</refsect1>




</refentry>
