path: root/docs/reference/pygtk-gtkcombo.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-gtkcombo">
  <refnamediv>
    <refname>gtk.Combo</refname>
    <refpurpose>a text entry field with a dropdown list.</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>gtk.Combo</classname></ooclass>
      <ooclass><classname><link
linkend="class-gtkhbox">gtk.HBox</link></classname></ooclass>
      <constructorsynopsis language="python">
	<methodname><link
linkend="constructor-gtkcombo">gtk.Combo</link></methodname>
	<methodparam></methodparam>  </constructorsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkcombo--set-value-in-list">set_value_in_list</link></methodname>
	<methodparam><parameter role="keyword">val</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">ok_if_empty</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkcombo--set-use-arrows">set_use_arrows</link></methodname>
	<methodparam><parameter role="keyword">val</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkcombo--set-use-arrows-always">set_use_arrows_always</link></methodname>
	<methodparam><parameter role="keyword">val</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkcombo--set-case-sensitive">set_case_sensitive</link></methodname>
	<methodparam><parameter role="keyword">val</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkcombo--set-item-string">set_item_string</link></methodname>
	<methodparam><parameter
		       role="keyword">item</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">item_value</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkcombo--set-popdown-strings">set_popdown_strings</link></methodname>
	<methodparam><parameter
		       role="keyword">strings</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkcombo--disable-activate">disable_activate</link></methodname>
	<methodparam></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-gtkwidget">gtk.Widget</link>
      +-- <link linkend="class-gtkcontainer">gtk.Container</link>
        +-- <link linkend="class-gtkbox">gtk.Box</link>
          +-- <link linkend="class-gtkhbox">gtk.HBox</link>
            +-- <link linkend="class-gtkcombo">gtk.Combo</link>
</synopsis>

  </refsect1>
  
  <refsect1>
		<title>Implemented Interfaces</title>
		<para>
			<link linkend="class-gtkcombo"><classname>gtk.Combo</classname></link>
			implements 
			<link linkend="class-gtkbuildable"><classname>gtk.Buildable</classname></link>
		</para>
	</refsect1>


  <refsect1 id="properties-gtkcombo">
    <title>gtk.Combo 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-gtkbox">gtk.Box 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>"allow-empty"</entry>
              <entry>Read/Write</entry>
              <entry>If <literal>True</literal>, an empty value may be entered
              in this field</entry>
            </row>
            <row valign="top">
              <entry>"case-sensitive"</entry>
              <entry>Read/Write</entry>
              <entry>If <literal>True</literal>, list item matching is case
              sensitive</entry>
            </row>
            <row valign="top">
              <entry>"enable-arrow-keys"</entry>
              <entry>Read/Write</entry>
              <entry>If <literal>True</literal>, the arrow keys move through the
              list of items</entry>
            </row>
            <row valign="top">
              <entry>"enable-arrows-always"</entry>
              <entry>Read/Write</entry>
              <entry>If <literal>True</literal>, the arrow keys work, even if
              the entry contents are not in the list</entry>
            </row>
            <row valign="top">
              <entry>"value-in-list"</entry>
              <entry>Read/Write</entry>
              <entry>If <literal>True</literal>, entered values must already be
              present in the list</entry>
            </row>

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

  </refsect1>

  <refsect1 id="style-properties-gtkcombo">
    <title>gtk.Combo Style Properties</title>

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

  </refsect1>

  <refsect1 id="child-properties-gtkcombo">
    <title>gtk.Combo Child Properties</title>

    <para><link linkend="child-properties-gtkbox">gtk.Box Child Properties</link></para>

  </refsect1>

  <refsect1>
    <title>Attributes</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>"entry"</entry>
	      <entry>Read</entry>
	      <entry>the text entry widget</entry>
	    </row>

	    <row valign="top">
	      <entry>"list"</entry>
	      <entry>Read</entry>
	      <entry>the list shown in the drop-down window</entry>
	    </row>

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

  </refsect1>

  <refsect1 id="signal-prototypes-gtkcombo">
    <title>gtk.Combo 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>
  </refsect1>

  <refsect1>
    <title>Description</title>

    <note>
      <para>The <link
      linkend="class-gtkcombo"><classname>gtk.Combo</classname></link> is
      deprecated in GTK+ 2.4 and PyGTK 2.4 in favor of the <link
      linkend="class-gtkcombobox"><classname>gtk.ComboBox</classname></link>.</para>
    </note>

    <para>The <link
linkend="class-gtkcombo"><classname>gtk.Combo</classname></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. The drop-down list is a
<classname>gtk.List</classname> widget and can be accessed using the list
attribute of the <link
linkend="class-gtkcombo"><classname>gtk.Combo</classname></link>. List
elements can contain arbitrary widgets, but if an element is not a plain
label, then you must use the
<methodname>gtk.List.set_item_string</methodname>() method. 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 behavior can be turned off with the
<link
linkend="method-gtkcombo--set-use-arrows"><methodname>set_use_arrows</methodname>()</link> 
method. Normally the arrow keys are only active when the contents of the
text entry field matches one of the items in the list. If the contents of
the entry field do not match any of the list items, then pressing the arrow
keys does nothing. However, by calling <link
linkend="method-gtkcombo--set-use-arrows"><methodname>set_use_arrows_always</methodname>()</link> 
you can specify that the arrow keys are always active. If the contents of
the entry field does not match any of the items in the list, then pressing
the up or down arrow key will set the entry field to the last or first item
in the list, respectively.</para>

    <para>Note the list attribute references a gtk.List which is a
deprecated widget so the combo widget may be changed or deprecated in the
future.</para>

  </refsect1>

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

    <programlisting><constructorsynopsis language="python">
	<methodname>gtk.Combo</methodname>
	<methodparam></methodparam>  </constructorsynopsis></programlisting>
    <variablelist>
      <varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	<listitem><simpara>a combo object*</simpara></listitem>
      </varlistentry>
    </variablelist>

    <para>Creates an new <link
linkend="class-gtkcombo"><classname>gtk.Combo</classname></link>
object.</para>

  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-gtkcombo--set-value-in-list">
      <title>gtk.Combo.set_value_in_list</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_value_in_list</methodname>
	  <methodparam><parameter
			 role="keyword">val</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">ok_if_empty</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">val</parameter>&nbsp;:</term>
	  <listitem><simpara>If True the value entered must match one of the
values in the list.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter
role="keyword">ok_if_empty</parameter>&nbsp;:</term>
	  <listitem><simpara>If True an empty value is considered
valid.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_value_in_list</methodname>() method
specifies whether the value entered in the text entry field must match one
of the values in the list. This method sets the "value-in-list" property to
the value of <parameter>val</parameter> and the "allow-empty" property to
the value of <parameter>ok_if_empty</parameter>.</para>

      <para>If <parameter>val</parameter> is True the user will not be able
to perform any other action (the widget grabs the focus) until a valid value
has been entered. If <parameter>ok_if_empty</parameter> is True an empty
field is considered an acceptable value.</para>

    </refsect2>

    <refsect2 id="method-gtkcombo--set-use-arrows">
      <title>gtk.Combo.set_use_arrows</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_use_arrows</methodname>
	  <methodparam><parameter
			 role="keyword">val</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">val</parameter>&nbsp;:</term>
	  <listitem><simpara>If True can be used to navigate through the
list items</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_use_arrows</methodname>() method sets the
"enable-use-arrows" property to the value of <parameter>val</parameter>. If
<parameter>val</parameter> is True the arrows keys can be used to navigate
through the list items.</para>

    </refsect2>

    <refsect2 id="method-gtkcombo--set-use-arrows-always">
      <title>gtk.Combo.set_use_arrows_always</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_use_arrows_always</methodname>
	  <methodparam><parameter
			 role="keyword">val</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">val</parameter>&nbsp;:</term>
	  <listitem><simpara>If True the arrow keys will still work even if
the text entry field does not match any of the list
items.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_use_arrows_always</methodname>() method sets
the "enable-arrows-always" property to the values of
<parameter>val</parameter>. If <parameter>val</parameter> is True the arrow
keys will work even if the text entry field does not match any of the list
items.</para>

    </refsect2>

    <refsect2 id="method-gtkcombo--set-case-sensitive">
      <title>gtk.Combo.set_case_sensitive</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_case_sensitive</methodname>
	  <methodparam><parameter
			 role="keyword">val</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">val</parameter>&nbsp;:</term>
	  <listitem><simpara>If True the text in the list items is case
sensitive.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_case_sensitive</methodname>() method sets
the "case-sensitive" property to the value of <parameter>val</parameter>. If
<parameter>val</parameter> is True the text in the combo list items and the
text entry field are case sensitive. The default value of
"set-case-sensitive" is False.</para>

    </refsect2>


    <refsect2 id="method-gtkcombo--set-item-string">
      <title>gtk.Combo.set_item_string</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_item_string</methodname>
	  <methodparam><parameter
			 role="keyword">item</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">item_value</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">item</parameter>&nbsp;:</term>
	  <listitem><simpara>a list item</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter
role="keyword">item_value</parameter>&nbsp;:</term>
	  <listitem><simpara>a string to place in the entry field when
<parameter>item</parameter> is selected</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_item_string</methodname>() method sets the
string (from <parameter>item_value</parameter>) to place in the combo text
entry field when the <parameter>item</parameter> is selected. This method is
only needed if the list item is other than a simple label (e.g. a
pixmap).</para>

    </refsect2>


    <refsect2 id="method-gtkcombo--set-popdown-strings">
      <title>gtk.Combo.set_popdown_strings</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_popdown_strings</methodname>
	  <methodparam><parameter
			 role="keyword">strings</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">strings</parameter>&nbsp;:</term>
	  <listitem><simpara>a list of strings to populate the
list</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_popdown_strings</methodname>() method is a
convenience method that sets the strings used in the popdown list from.
<parameter>strings</parameter> (a Python list or tuple object).</para>

    </refsect2>


    <refsect2 id="method-gtkcombo--disable-activate">
      <title>gtk.Combo.disable_activate</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>disable_activate</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>

      <para>The <methodname>disable_activate</methodname>() method prevents
the combo from showing the popup list when the entry emits the "activate"
signal, i.e. when the <keycap>Return</keycap> key is pressed. This may be
useful if, for example, you want the <keycap>Return</keycap> key to close a
dialog instead. </para>

    </refsect2>

  </refsect1>

</refentry>