path: root/docs/reference/pygtk-gtkcomboboxtext.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-gtkcomboboxtext">
  <refnamediv>
    <refname>gtk.ComboBoxText</refname> <refpurpose>A simple, text-only combo box (new in PyGTK 2.24)</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>gtk.ComboBoxText</classname></ooclass>
      <ooclass><classname><link linkend="class-gtkcombobox">gtk.ComboBox</link></classname></ooclass>
      <constructorsynopsis language="python">
        <methodname><link linkend="constructor-gtkcomboboxtext">gtk.ComboBoxText</link></methodname>
        <methodparam></methodparam>
      </constructorsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkcomboboxtext--append-text">append_text</link></methodname>
        <methodparam><parameter role="keyword">text</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkcomboboxtext--insert-text">insert_text</link></methodname>
        <methodparam><parameter role="keyword">position</parameter></methodparam>
        <methodparam><parameter role="keyword">text</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkcomboboxtext--prepend-text">prepend_text</link></methodname>
        <methodparam><parameter role="keyword">text</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkcomboboxtext--remove">remove</link></methodname>
        <methodparam><parameter role="keyword">position</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkcomboboxtext--get-active-text">get_active_text</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
    </classsynopsis>

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

      <methodsynopsis language="python">
        <methodname><link linkend="function-gtk--combo-box-text-new-with-entry">gtk.combo_box_text_new_with_entry</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-gtkcomboboxtext">gtk.ComboBoxText</link>
</synopsis>
  </refsect1>

  <refsect1>
    <title>Implemented Interfaces</title>
    <para>
      <link linkend="class-gtkcomboboxtext"><classname>gtk.ComboBoxText</classname></link>
      implements 
      <link linkend="class-gtkbuildable"><classname>gtk.Buildable</classname></link>
      <link linkend="class-atkimplementor"><classname>atk.ImplementorIFace</classname></link>
      <link linkend="class-gtkcelleditable"><classname>gtk.CellEditable</classname></link>
      <link linkend="class-gtkcelllayout"><classname>gtk.CellLayout</classname></link>
    </para>
  </refsect1>

  <refsect1 id="properties-gtkcomboboxtext">
    <title>gtk.ComboBoxText 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>

  </refsect1>

  <refsect1 id="style-properties-gtkcomboboxtext">
    <title>gtk.ComboBoxText 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-gtkcomboboxtext">
    <title>gtk.ComboBoxText 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-gtkcelleditable">gtk.CellEditable Signal Prototypes</link></para>
    <para><link linkend="signal-prototypes-gtkcombobox">gtk.ComboBox Signal Prototypes</link></para>

  </refsect1>

  <refsect1>
    <title>Description</title>

    <note>
      <para>This widget is available in GTK+ 2.24 and PyGTK 2.24 and above.</para>
    </note>

    <para>A <link linkend="class-gtkcomboboxtext"><classname>gtk.ComboBoxText</classname></link>
    is a simple variant of <link linkend="class-gtkcombobox"><classname>gtk.ComboBox</classname></link>
    that hides the model-view complexity for simple text-only use cases.</para>

  </refsect1>

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

    <programlisting><constructorsynopsis language="python">
      <methodname>gtk.ComboBox</methodname>
      <methodparam></methodparam>
    </constructorsynopsis></programlisting>
    <variablelist>
      <varlistentry>
        <term><emphasis>Returns</emphasis>&nbsp;:</term>
        <listitem><simpara>A new <link linkend="class-gtkcomboboxtext"><classname>gtk.ComboBoxText</classname></link>.</simpara></listitem>
      </varlistentry>
    </variablelist>

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

    <para>Creates a new <link linkend="class-gtkcomboboxtext"><classname>gtk.ComboBoxText</classname></link>,
    which is a <link linkend="class-gtkcombobox"><classname>gtk.ComboBox</classname></link> just displaying strings.</para>

  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-gtkcomboboxtext--append-text">
      <title>gtk.ComboBoxText.append_text</title>

      <programlisting><methodsynopsis language="python">
        <methodname>append_text</methodname>
        <methodparam><parameter role="keyword">text</parameter></methodparam>
      </methodsynopsis></programlisting>
      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">text</parameter>&nbsp;:</term>
          <listitem><simpara>A string.</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>The <methodname>append_text</methodname>() method appends the string specified
      by <parameter>text</parameter> to the list of strings stored in the combo box
      <link linkend="class-gtkliststore"><classname>gtk.ListStore</classname></link>.</para>

    </refsect2>

    <refsect2 id="method-gtkcomboboxtext--insert-text">
      <title>gtk.ComboBoxText.insert_text</title>

      <programlisting><methodsynopsis language="python">
        <methodname>insert_text</methodname>
        <methodparam><parameter role="keyword">position</parameter></methodparam>
        <methodparam><parameter role="keyword">text</parameter></methodparam>
      </methodsynopsis></programlisting>
      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">position</parameter>&nbsp;:</term>
          <listitem><simpara>A model index where the text should be inserted.</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter role="keyword">text</parameter>&nbsp;:</term>
          <listitem><simpara>A string.</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>The <methodname>insert_text</methodname>() method inserts the string specified
      by <parameter>text</parameter> in the combo box <link linkend="class-gtkliststore"><classname>gtk.ListStore</classname></link>
      at the index specified by <parameter>position</parameter>.</para>

    </refsect2>

    <refsect2 id="method-gtkcomboboxtext--prepend-text">
      <title>gtk.ComboBoxText.prepend_text</title>

      <programlisting><methodsynopsis language="python">
        <methodname>prepend_text</methodname>
        <methodparam><parameter role="keyword">text</parameter></methodparam>
      </methodsynopsis></programlisting>
      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">text</parameter>&nbsp;:</term>
          <listitem><simpara>A string.</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>The <methodname>prepend_text</methodname>() method prepends the string specified
      by <parameter>text</parameter> to the list of strings stored in the
      <link linkend="class-gtkliststore"><classname>gtk.ListStore</classname></link>
      associated with the combo_box.</para>

    </refsect2>

    <refsect2 id="method-gtkcomboboxtext--remove">
      <title>gtk.ComboBoxText.remove</title>

      <programlisting><methodsynopsis language="python">
        <methodname>remove</methodname>
        <methodparam><parameter role="keyword">position</parameter></methodparam>
      </methodsynopsis></programlisting>
      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">position</parameter>&nbsp;:</term>
          <listitem><simpara>Index of the item to remove.</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>The <methodname>remove_text</methodname>() method removes the string at
      the index specified by <parameter>position</parameter> in the associated
      <link linkend="class-gtkliststore"><classname>gtk.ListStore</classname></link>.</para>

    </refsect2>

    <refsect2 id="method-gtkcomboboxtext--get-active-text">
      <title>gtk.ComboBoxText.get_active_text</title>

      <programlisting><methodsynopsis language="python">
        <methodname>get_active_text</methodname>
        <methodparam></methodparam>
      </methodsynopsis></programlisting>
      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>The currently active text.</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>The <methodname>get_active_text</methodname>() method returns
      the currently active string or <literal>None</literal> if no entry is
      selected.</para>

    </refsect2>

  </refsect1>

  <refsect1>
    <title>Functions</title>

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

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

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

      <para>The <function>gtk.combo_box_new_text</function>() function  creates a new
      <link linkend="class-gtkcomboboxtext"><classname>gtk.ComboBoxText</classname></link>,
      which is a <link linkend="class-gtkcombobox"><classname>gtk.ComboBox</classname></link>
      just displaying strings. The combo box created by this function has an entry.</para>

    </refsect2>

  </refsect1>

</refentry>