source: pkg/pygtk/branches/upstream/current/docs/reference/pygtk-gtkcombobox.xml @ 4

Revision 4, 48.4 KB checked in by alanbach-guest, 6 years ago (diff)

[svn-inject] Installing original source of pygtk
Line 
1<?xml version="1.0" standalone="no"?>
2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
4
5<refentry id="class-gtkcombobox">
6  <refnamediv>
7    <refname>gtk.ComboBox</refname> <refpurpose>a widget used to choose from
8    a list of items (new in PyGTK 2.4)</refpurpose>
9  </refnamediv>
10
11  <refsect1>
12    <title>Synopsis</title>
13
14    <classsynopsis language="python">
15      <ooclass><classname>gtk.ComboBox</classname></ooclass>
16      <ooclass><classname><link linkend="class-gtkbin">gtk.Bin</link></classname></ooclass>
17      <ooclass><classname><link linkend="class-gtkcelllayout">gtk.CellLayout</link></classname></ooclass>
18      <constructorsynopsis language="python">
19        <methodname><link linkend="constructor-gtkcombobox">gtk.ComboBox</link></methodname>
20        <methodparam><parameter role="keyword">model</parameter><initializer>None</initializer></methodparam>  </constructorsynopsis>
21      <methodsynopsis language="python">
22        <methodname><link linkend="method-gtkcombobox--get-wrap-width">get_wrap_width</link></methodname>
23        <methodparam></methodparam>
24      </methodsynopsis>
25      <methodsynopsis language="python">
26        <methodname><link linkend="method-gtkcombobox--set-wrap-width">set_wrap_width</link></methodname>
27        <methodparam><parameter role="keyword">width</parameter></methodparam>
28      </methodsynopsis>
29      <methodsynopsis language="python">
30        <methodname><link linkend="method-gtkcombobox--get-row-span-column">get_row_span_column</link></methodname>
31        <methodparam></methodparam>
32      </methodsynopsis>
33      <methodsynopsis language="python">
34        <methodname><link linkend="method-gtkcombobox--set-row-span-column">set_row_span_column</link></methodname>
35        <methodparam><parameter role="keyword">row_span</parameter></methodparam>
36      </methodsynopsis>
37      <methodsynopsis language="python">
38        <methodname><link linkend="method-gtkcombobox--get-column-span-column">get_column_span_column</link></methodname>
39        <methodparam></methodparam>
40      </methodsynopsis>
41      <methodsynopsis language="python">
42        <methodname><link linkend="method-gtkcombobox--set-column-span-column">set_column_span_column</link></methodname>
43        <methodparam><parameter role="keyword">column_span</parameter></methodparam>
44      </methodsynopsis>
45      <methodsynopsis language="python">
46        <methodname><link linkend="method-gtkcombobox--get-active">get_active</link></methodname>
47        <methodparam></methodparam>  </methodsynopsis>
48      <methodsynopsis language="python">
49        <methodname><link linkend="method-gtkcombobox--set-active">set_active</link></methodname>
50        <methodparam><parameter role="keyword">index</parameter></methodparam>
51      </methodsynopsis>
52      <methodsynopsis language="python">
53        <methodname><link linkend="method-gtkcombobox--get-active-iter">get_active_iter</link></methodname>
54        <methodparam></methodparam>
55      </methodsynopsis>
56      <methodsynopsis language="python">
57        <methodname><link linkend="method-gtkcombobox--set-active-iter">set_active_iter</link></methodname>
58        <methodparam><parameter role="keyword">iter</parameter></methodparam>
59      </methodsynopsis>
60      <methodsynopsis language="python">
61        <methodname><link linkend="method-gtkcombobox--set-model">set_model</link></methodname>
62        <methodparam><parameter role="keyword">model</parameter><initializer>None</initializer></methodparam>
63      </methodsynopsis>
64      <methodsynopsis language="python">
65        <methodname><link linkend="method-gtkcombobox--get-model">get_model</link></methodname>
66        <methodparam></methodparam>  </methodsynopsis>
67      <methodsynopsis language="python">
68        <methodname><link linkend="method-gtkcombobox--append-text">append_text</link></methodname>
69        <methodparam><parameter role="keyword">text</parameter></methodparam>
70      </methodsynopsis>
71      <methodsynopsis language="python">
72        <methodname><link linkend="method-gtkcombobox--insert-text">insert_text</link></methodname>
73        <methodparam><parameter role="keyword">position</parameter></methodparam>
74        <methodparam><parameter role="keyword">text</parameter></methodparam>
75      </methodsynopsis>
76      <methodsynopsis language="python">
77        <methodname><link linkend="method-gtkcombobox--prepend-text">prepend_text</link></methodname>
78        <methodparam><parameter role="keyword">text</parameter></methodparam>
79      </methodsynopsis>
80      <methodsynopsis language="python">
81        <methodname><link linkend="method-gtkcombobox--remove-text">remove_text</link></methodname>
82        <methodparam><parameter role="keyword">position</parameter></methodparam>
83      </methodsynopsis>
84      <methodsynopsis language="python">
85        <methodname><link linkend="method-gtkcombobox--get-active-text">get_active_text</link></methodname>
86        <methodparam></methodparam>
87      </methodsynopsis>
88      <methodsynopsis language="python">
89        <methodname><link linkend="method-gtkcombobox--popup">popup</link></methodname>
90        <methodparam></methodparam>  </methodsynopsis>
91      <methodsynopsis language="python">
92        <methodname><link linkend="method-gtkcombobox--popdown">popdown</link></methodname>
93        <methodparam></methodparam>  </methodsynopsis>
94      <methodsynopsis language="python">
95        <methodname><link linkend="method-gtkcombobox--get-popup-accessible">get_popup_accessible</link></methodname>
96        <methodparam></methodparam>  </methodsynopsis>
97
98<!-- NOT IMPLEMENTED
99      <methodsynopsis language="python">
100        <methodname><link linkend="method-gtkcombobox- -get-row-separator-func">get_row_separator_func</link></methodname>
101        <methodparam></methodparam>
102      </methodsynopsis>
103END NOT IMPLEMENTED -->
104
105      <methodsynopsis language="python">
106        <methodname><link linkend="method-gtkcombobox--set-row-separator-func">set_row_separator_func</link></methodname>
107        <methodparam><parameter role="keyword">func</parameter><initializer>None</initializer></methodparam>
108        <methodparam><parameter role="keyword">data</parameter><initializer>None</initializer></methodparam>
109      </methodsynopsis>
110      <methodsynopsis language="python">
111        <methodname><link linkend="method-gtkcombobox--get-add-tearoffs">get_add_tearoffs</link></methodname>
112        <methodparam></methodparam>
113      </methodsynopsis>
114      <methodsynopsis language="python">
115        <methodname><link linkend="method-gtkcombobox--set-add-tearoffs">set_add_tearoffs</link></methodname>
116        <methodparam><parameter role="keyword">add_tearoffs</parameter></methodparam>
117      </methodsynopsis>
118      <methodsynopsis language="python">
119        <methodname><link linkend="method-gtkcombobox--get-focus-on-click">get_focus_on_click</link></methodname>
120        <methodparam></methodparam>
121      </methodsynopsis>
122      <methodsynopsis language="python">
123        <methodname><link linkend="method-gtkcombobox--set-focus-on-click">set_focus_on_click</link></methodname>
124        <methodparam><parameter role="keyword">focus_on_click</parameter></methodparam>
125      </methodsynopsis>
126      <methodsynopsis language="python">
127        <methodname><link linkend="method-gtkcombobox--get-title">get_title</link></methodname>
128        <methodparam></methodparam>
129      </methodsynopsis>
130      <methodsynopsis language="python">
131        <methodname><link linkend="method-gtkcombobox--set-title">set_title</link></methodname>
132        <methodparam><parameter role="keyword">title</parameter></methodparam>
133      </methodsynopsis>
134    </classsynopsis>
135
136    <programlisting>
137<emphasis role="bold">Functions</emphasis>
138
139<methodsynopsis language="python">
140        <methodname><link linkend="function-gtk--combo-box-new-text">gtk.combo_box_new_text</link></methodname>
141        <methodparam></methodparam>
142      </methodsynopsis></programlisting>
143
144  </refsect1>
145
146  <refsect1>
147    <title>Ancestry</title>
148
149<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link>
150  +-- <link linkend="class-gtkobject">gtk.Object</link>
151    +-- <link linkend="class-gtkwidget">gtk.Widget</link>
152      +-- <link linkend="class-gtkcontainer">gtk.Container</link>
153        +-- <link linkend="class-gtkbin">gtk.Bin</link>
154          +-- <link linkend="class-gtkcombobox">gtk.ComboBox</link> (implements <link linkend="class-gtkcelllayout"><classname>gtk.CellLayout</classname></link>)
155</synopsis>
156
157  </refsect1>
158
159  <refsect1 id="properties-gtkcombobox">
160    <title>gtk.ComboBox Properties</title>
161
162    <para><link linkend="properties-gtkobject">gtk.Object Properties</link></para>
163    <para><link linkend="properties-gtkwidget">gtk.Widget Properties</link></para>
164    <para><link linkend="properties-gtkcontainer">gtk.Container Properties</link></para>
165
166    <blockquote role="properties">
167      <informaltable pgwide="1" frame="none">
168        <tgroup cols="3">
169          <colspec column="1" colwidth="1in"/>
170          <colspec column="2" colwidth="1in"/>
171          <colspec column="3" colwidth="4in"/>
172          <tbody>
173
174            <row valign="top">
175              <entry>"active"</entry>
176              <entry>Read-Write</entry>
177              <entry>The index of the item that is currently active.. If the
178              model is a non-flat treemodel, and the active item is not an
179              immediate child of the root of the tree, this property has the
180              value of the first index of the path of the item. This
181              property is available in GTK+ 2.4 and above.</entry>
182            </row>
183
184            <row valign="top">
185              <entry>"add-tearoffs"</entry>
186              <entry>Read-Write</entry>
187              <entry>If <literal>True</literal> generated menus have tearoff
188              menu items. Note that this only affects menu style combo
189              boxes.  Default value: <literal>False</literal>. Available in
190              GTK+ 2.6 and above.</entry>
191            </row>
192
193            <row valign="top">
194              <entry>"column-span-column"</entry>
195              <entry>Read-Write</entry>
196              <entry>The TreeModel column containing the column span values.
197              This property is available in GTK+ 2.4 and above</entry>
198            </row>
199
200            <row valign="top">
201              <entry>"focus-on-click"</entry>
202              <entry>Read-Write</entry>
203              <entry>If <literal>True</literal> the combo box grabs focus
204              when it is clicked with the mouse. Default value:
205              <literal>True</literal></entry>
206            </row>
207
208            <row valign="top">
209              <entry>"has-frame"</entry>
210              <entry>Read-Write</entry>
211              <entry>If <literal>True</literal> the combo box grabs focus
212              when it is clicked with the mouse. Default value:
213              <literal>True</literal>.  Available in GTK+ 2.6 and
214              above.</entry>
215            </row>
216
217            <row valign="top">
218              <entry>"model"</entry>
219              <entry>Read-Write</entry>
220              <entry>The TreeModel for the combo box. This property is
221              available in GTK+ 2.4 and above.</entry>
222            </row>
223
224            <row valign="top">
225              <entry>"popup-shown"</entry>
226              <entry>Read-Write</entry>
227              <entry>If <literal>True</literal> the dropdown menu of the
228              combobox is popped up. Note that this property is mainly
229              useful, because it allows you to connect to the
230              "notify::popup-shown" signal. Available in GTK+ 2.10 and
231              above.</entry>
232            </row>
233
234            <row valign="top">
235              <entry>"row-span-column"</entry>
236              <entry>Read-Write</entry>
237              <entry>The TreeModel column containing the row span
238              values. This property is available in GTK+ 2.4 and
239              above.</entry>
240            </row>
241
242            <row valign="top">
243              <entry>"tearoff-title"</entry>
244              <entry>Read-Write</entry>
245              <entry>A title that may be displayed by the window manager
246              when the popup is torn-off.  Default value: "". Available in
247              GTK+ 2.10 and above</entry>
248            </row>
249
250            <row valign="top">
251              <entry>"wrap-width"</entry>
252              <entry>Read-Write</entry>
253              <entry>The number of columns to use to lay out the popup
254              items. This property is available in GTK+ 2.4 and
255              above.</entry>
256            </row>
257
258          </tbody>
259        </tgroup>
260      </informaltable>
261    </blockquote>
262
263  </refsect1>
264
265  <refsect1 id="style-properties-gtkcombobox">
266    <title>gtk.ComboBox Style Properties</title>
267
268    <para><link linkend="style-properties-gtkwidget">gtk.Widget Style Properties</link></para>
269
270    <blockquote role="properties">
271      <informaltable pgwide="1" frame="none">
272        <tgroup cols="3">
273          <colspec column="1" colwidth="1in"/>
274          <colspec column="2" colwidth="1in"/>
275          <colspec column="3" colwidth="4in"/>
276          <tbody>
277
278            <row valign="top">
279              <entry>"appears-as-list"</entry>
280              <entry>Read-Write</entry>
281              <entry>If <literal>True</literal>, the combo box dropdowns
282              should look like lists rather than menus.</entry>
283            </row>
284
285          </tbody>
286        </tgroup>
287      </informaltable>
288    </blockquote>
289
290  </refsect1>
291
292  <refsect1 id="signal-prototypes-gtkcombobox">
293    <title>gtk.ComboBox Signal Prototypes</title>
294
295    <para><link linkend="signal-prototypes-gobject">gobject.GObject Signal Prototypes</link></para>
296    <para><link linkend="signal-prototypes-gtkobject">gtk.Object Signal Prototypes</link></para>
297    <para><link linkend="signal-prototypes-gtkwidget">gtk.Widget Signal Prototypes</link></para>
298    <para><link linkend="signal-prototypes-gtkcontainer">gtk.Container Signal Prototypes</link></para>
299    <para><link linkend="signal-prototypes-gtkcelleditable">gtk.CellEditable Signal Prototypes</link></para>
300
301    <variablelist>
302      <varlistentry>
303        <term>"<link linkend="signal-gtkcombobox--changed">changed</link>"</term>
304        <listitem>
305          <methodsynopsis language="python"><methodname>callback</methodname>
306            <methodparam><parameter>combobox</parameter></methodparam>
307            <methodparam><parameter>user_param1</parameter></methodparam>
308            <methodparam><parameter>...</parameter></methodparam>
309          </methodsynopsis>
310        </listitem>
311      </varlistentry>
312    </variablelist>
313
314  </refsect1>
315
316  <refsect1>
317    <title>Description</title>
318
319    <note>
320      <para>This widget is available in GTK+ 2.4 and PyGTK 2.4 and above.</para>
321    </note>
322
323    <para>The <link
324    linkend="class-gtkcombobox"><classname>gtk.ComboBox</classname></link>
325    is a replacement for the <link
326    linkend="class-gtkoptionmenu"><classname>gtk.OptionMenu</classname></link>. The
327    <link
328    linkend="class-gtkcombobox"><classname>gtk.ComboBox</classname></link>
329    implements the <link
330    linkend="class-gtkcelllayout"><classname>gtk.CellLayout</classname></link>
331    interface that provides a number of useful methods for managing the
332    contents. A <link
333    linkend="class-gtkcombobox"><classname>gtk.ComboBox</classname></link>
334    is created with the <link
335    linkend="constructor-gtkcombobox">gtk.ComboBox()</link> constructor that
336    is associated with the optional <link
337    linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link>. If
338    no <link
339    linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link>
340    is specified it can be added later with the <link
341    linkend="method-gtkcombobox--set-model"><methodname>set_model</methodname>()</link>
342    method.</para>
343
344    <para>Alternatively, the <link
345    linkend="function-gtk--combo-box-new-text"><function>gtk.combo_box_new_text</function>()</link>
346    function creates a simple <link
347    linkend="class-gtkcombobox"><classname>gtk.ComboBox</classname></link>
348    and associated <link
349    linkend="class-gtkliststore"><classname>gtk.ListStore</classname></link>
350    model. A <link
351    linkend="class-gtkcellrenderertext"><classname>gtk.CellRendererText</classname></link>
352    is also created and packed in the new combo box. In this simple combo
353    box each list item is a text string that can be selected.  The
354    convenience methods <link
355    linkend="method-gtkcombobox--append-text"><methodname>append_text</methodname>()</link>,
356    <link
357    linkend="method-gtkcombobox--prepend-text"><methodname>prepend_text</methodname>()</link>,
358    <link
359    linkend="method-gtkcombobox--insert-text"><methodname>insert_text</methodname>()</link>
360    and <link
361    linkend="method-gtkcombobox--remove-text"><methodname>remove_text</methodname>()</link>
362    can be used to manage the contents of the <link
363    linkend="class-gtkcombobox"><classname>gtk.ComboBox</classname></link>. Using
364    the <link
365    linkend="function-gtk--combo-box-new-text"><function>gtk.combo_box_new_text</function>()</link>
366    function is equivalent to:</para>
367
368    <programlisting>
369  liststore = gtk.ListStore(gobject.TYPE_STRING)
370  combobox = gtk.ComboBox(liststore)
371  cell = gtk.CellRendererText()
372  combobox.pack_start(cell, True)
373  combobox.add_attribute(cell, 'text', 0)
374</programlisting>
375
376  </refsect1>
377
378  <refsect1 id="constructor-gtkcombobox">
379    <title>Constructor</title>
380
381    <programlisting><constructorsynopsis language="python">
382    <methodname>gtk.ComboBox</methodname>
383    <methodparam><parameter role="keyword">model</parameter><initializer>None</initializer></methodparam>
384      </constructorsynopsis></programlisting>
385    <variablelist>
386      <varlistentry>
387        <term><parameter role="keyword">model</parameter>&nbsp;:</term>
388        <listitem><simpara>A valid <link linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link>.</simpara></listitem>
389      </varlistentry>
390      <varlistentry>
391        <term><emphasis>Returns</emphasis>&nbsp;:</term>
392        <listitem><simpara>A new <link linkend="class-gtkcombobox"><classname>gtk.ComboBox</classname></link>.</simpara></listitem>
393      </varlistentry>
394    </variablelist>
395
396    <note>
397      <para>This constructor is available in PyGTK 2.4 and above.</para>
398    </note>
399
400    <para>Creates a new <link
401    linkend="class-gtkcombobox"><classname>gtk.ComboBox</classname></link>
402    associated with the optional <link
403    linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link>
404    specified by <parameter>model</parameter>. If
405    <parameter>model</parameter> is not specified the combo box will not
406    have an associated tree model.</para>
407
408  </refsect1>
409
410  <refsect1>
411    <title>Methods</title>
412
413    <refsect2 id="method-gtkcombobox--get-wrap-width">
414      <title>gtk.ComboBox.get_wrap_width</title>
415
416      <programlisting><methodsynopsis language="python">
417          <methodname>get_wrap_width</methodname>
418          <methodparam></methodparam>
419        </methodsynopsis></programlisting>
420      <variablelist>
421        <varlistentry>
422          <term><emphasis>Returns</emphasis>&nbsp;:</term>
423          <listitem><simpara>The wrap width.</simpara></listitem>
424        </varlistentry>
425      </variablelist>
426
427      <note>
428        <para>This method is available in PyGTK 2.6 and above.</para>
429      </note>
430
431      <para>The <methodname>get_wrap_width</methodname>() method returns the
432value of the "wrap-width" property of the combo box as set by the <link
433linkend="method-gtkcombobox--set-wrap-width"><methodname>set_wrap_width</methodname>()</link>
434method. The wrap width is basically the preferred number of columns to use
435to lay out the popup i.e. lays out the popup items in a table with
436<parameter>width</parameter> columns.</para>
437
438    </refsect2>
439
440    <refsect2 id="method-gtkcombobox--set-wrap-width">
441      <title>gtk.ComboBox.set_wrap_width</title>
442
443      <programlisting><methodsynopsis language="python">
444          <methodname>set_wrap_width</methodname>
445          <methodparam><parameter role="keyword">width</parameter></methodparam>
446        </methodsynopsis></programlisting>
447      <variablelist>
448        <varlistentry>
449          <term><parameter role="keyword">width</parameter>&nbsp;:</term>
450          <listitem><simpara>The preferred number of columns of
451width.</simpara></listitem>
452        </varlistentry>
453      </variablelist>
454
455      <note>
456        <para>This method is available in PyGTK 2.4 and above.</para>
457      </note>
458
459      <para>The <methodname>set_wrap_width</methodname>() method sets the
460wrap width (and the "wrap-width" property) of the combo box to the value
461specified by <parameter>width</parameter>. The wrap width is basically the
462preferred number of columns to use to lay out the popup i.e. lays out the
463popup items in a table with <parameter>width</parameter> columns.</para>
464
465    </refsect2>
466
467    <refsect2 id="method-gtkcombobox--get-row-span-column">
468      <title>gtk.ComboBox.get_row_span_column</title>
469
470      <programlisting><methodsynopsis language="python">
471          <methodname>get_row_span_column</methodname>
472          <methodparam></methodparam>
473        </methodsynopsis></programlisting>
474      <variablelist>
475        <varlistentry>
476          <term><emphasis>Returns</emphasis>&nbsp;:</term>
477          <listitem><simpara>The row span column.</simpara></listitem>
478        </varlistentry>
479      </variablelist>
480
481      <note>
482        <para>This method is available in PyGTK 2.6 and above.</para>
483      </note>
484
485      <para>The <methodname>get_row_span_column</methodname>() method
486returns the value of the "row-span-column" property. The "row-span-column"
487property indicates the column in the associated <link
488linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link> row
489that contains an integer that indicates how many rows the item should
490span.</para>
491
492    </refsect2>
493
494    <refsect2 id="method-gtkcombobox--set-row-span-column">
495      <title>gtk.ComboBox.set_row_span_column</title>
496
497      <programlisting><methodsynopsis language="python">
498          <methodname>set_row_span_column</methodname>
499          <methodparam><parameter role="keyword">row_span</parameter></methodparam>
500        </methodsynopsis></programlisting>
501      <variablelist>
502        <varlistentry>
503          <term><parameter role="keyword">row_span</parameter>&nbsp;:</term>
504          <listitem><simpara>A column in the model passed during construction.</simpara></listitem>
505        </varlistentry>
506      </variablelist>
507
508      <note>
509        <para>This method is available in PyGTK 2.4 and above.</para>
510      </note>
511
512      <para>The <methodname>set_row_span_column</methodname>() method sets
513the "row-span-column" property to the value specified by
514<parameter>row_span</parameter>. The "row-span-column" property indicates
515the column in the associated <link
516linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link> row
517that contains an integer that indicates how many rows the item should
518span.</para>
519
520    </refsect2>
521
522    <refsect2 id="method-gtkcombobox--get-column-span-column">
523      <title>gtk.ComboBox.get_column_span_column</title>
524
525      <programlisting><methodsynopsis language="python">
526          <methodname>get_column_span_column</methodname>
527          <methodparam></methodparam>
528        </methodsynopsis></programlisting>
529      <variablelist>
530        <varlistentry>
531          <term><emphasis>Returns</emphasis>&nbsp;:</term>
532          <listitem><simpara>The column span column.</simpara></listitem>
533        </varlistentry>
534      </variablelist>
535
536      <note>
537        <para>This method is available in PyGTK 2.6 and above.</para>
538      </note>
539
540      <para>The <methodname>get_column_span_column</methodname>() method
541returns the value of the "column-span-column" property. The
542"column-span-column" property indicates the column in the associated <link
543linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link> row
544that contains an integer that indicates how many columns the item should
545span.</para>
546
547    </refsect2>
548
549    <refsect2 id="method-gtkcombobox--set-column-span-column">
550      <title>gtk.ComboBox.set_column_span_column</title>
551
552      <programlisting><methodsynopsis language="python">
553          <methodname>set_column_span_column</methodname>
554          <methodparam><parameter role="keyword">column_span</parameter></methodparam>
555        </methodsynopsis></programlisting>
556      <variablelist>
557        <varlistentry>
558          <term><parameter role="keyword">column_span</parameter>&nbsp;:</term>
559          <listitem><simpara>A column in the model passed during construction.</simpara></listitem>
560        </varlistentry>
561      </variablelist>
562
563      <note>
564        <para>This method is available in PyGTK 2.4 and above.</para>
565      </note>
566
567      <para>The <methodname>set_column_span_column</methodname>() method
568sets the "column-span-column" property to the value specified by
569<parameter>column_span</parameter>. The "column-span-column" property
570indicates the column in the associated <link
571linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link> row
572that contains an integer that indicates how many columns the item should
573span.</para>
574
575    </refsect2>
576
577    <refsect2 id="method-gtkcombobox--get-active">
578      <title>gtk.ComboBox.get_active</title>
579
580      <programlisting><methodsynopsis language="python">
581          <methodname>get_active</methodname>
582          <methodparam></methodparam>  </methodsynopsis></programlisting>
583      <variablelist>
584        <varlistentry>
585          <term><emphasis>Returns</emphasis>&nbsp;:</term>
586          <listitem><simpara>An integer which is the model index of the
587          currently active item, or -1 if there's no active
588          item.</simpara></listitem>
589        </varlistentry>
590      </variablelist>
591
592      <note>
593        <para>This method is available in PyGTK 2.4 and above.</para>
594      </note>
595
596      <para>The <methodname>get_active</methodname>() method returns the
597      value of the "active" property which is the index in the model of the
598      currently active item, or -1 if there's no active item. If the model
599      is a non-flat treemodel, and the active item is not an immediate child
600      of the root of the tree, this method returns the first path index of
601      the active item. For example if the path of the active item is (1, 0,
602      2) this method will return 1.</para>
603
604    </refsect2>
605
606    <refsect2 id="method-gtkcombobox--set-active">
607      <title>gtk.ComboBox.set_active</title>
608
609      <programlisting><methodsynopsis language="python">
610          <methodname>set_active</methodname>
611          <methodparam><parameter role="keyword">index</parameter></methodparam>
612        </methodsynopsis></programlisting>
613      <variablelist>
614        <varlistentry>
615          <term><parameter role="keyword">index</parameter>&nbsp;:</term>
616          <listitem><simpara>An index in the model passed during
617          construction, or -1 to have no active item.</simpara></listitem>
618        </varlistentry>
619      </variablelist>
620
621      <note>
622        <para>This method is available in PyGTK 2.4 and above.</para>
623      </note>
624
625      <para>The <methodname>set_active</methodname>() method sets the active
626item of the combo_box to the item with the model index specified by
627<parameter>index</parameter>. If <parameter>index</parameter> is -1 the
628combo box will have no active item. The "active" property is also set to the
629value of <parameter>index</parameter>.</para>
630
631    </refsect2>
632
633    <refsect2 id="method-gtkcombobox--get-active-iter">
634      <title>gtk.ComboBox.get_active_iter</title>
635
636      <programlisting><methodsynopsis language="python">
637          <methodname>get_active_iter</methodname>
638          <methodparam></methodparam>
639        </methodsynopsis></programlisting>
640      <variablelist>
641        <varlistentry>
642          <term><emphasis>Returns</emphasis>&nbsp;:</term>
643          <listitem><simpara>A <link
644          linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>
645          that points at the active item or <literal>None</literal> if there
646          is no active item.</simpara></listitem>
647        </varlistentry>
648      </variablelist>
649
650      <note>
651        <para>This method is available in PyGTK 2.4 and above.</para>
652      </note>
653
654      <para>The <methodname>get_active_iter</methodname>() method returns a
655      <link
656      linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>
657      that points to the current active item or <literal>None</literal> if
658      there is no active item.</para>
659
660    </refsect2>
661
662    <refsect2 id="method-gtkcombobox--set-active-iter">
663      <title>gtk.ComboBox.set_active_iter</title>
664
665      <programlisting><methodsynopsis language="python">
666          <methodname>set_active_iter</methodname>
667          <methodparam><parameter role="keyword">iter</parameter></methodparam>
668        </methodsynopsis></programlisting>
669      <variablelist>
670        <varlistentry>
671          <term><parameter role="keyword">iter</parameter>&nbsp;:</term>
672          <listitem><simpara>A valid <link
673          linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>
674          pointing at an item in the associated <link
675          linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link>.</simpara></listitem>
676        </varlistentry>
677      </variablelist>
678
679      <note>
680        <para>This method is available in PyGTK 2.4 and above.</para>
681      </note>
682
683      <para>The <methodname>set_active_iter</methodname>() method sets the
684current active item to be the one referenced by <parameter>iter</parameter>
685in the associated <link
686linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link>.
687<parameter>iter</parameter> must correspond to a path of depth one. The
688"active" property is also set by this method.</para>
689
690    </refsect2>
691
692    <refsect2 id="method-gtkcombobox--set-model">
693      <title>gtk.ComboBox.set_model</title>
694
695      <programlisting><methodsynopsis language="python">
696          <methodname>set_model</methodname>
697          <methodparam><parameter role="keyword">model</parameter><initializer>None</initializer></methodparam>
698        </methodsynopsis></programlisting>
699      <variablelist>
700        <varlistentry>
701          <term><parameter role="keyword">model</parameter>&nbsp;:</term>
702          <listitem><simpara>A <link linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link>.</simpara></listitem>
703        </varlistentry>
704      </variablelist>
705
706      <note>
707        <para>This method is available in PyGTK 2.4 and above.</para>
708      </note>
709
710      <para>The <methodname>set_model</methodname>() method sets the model
711used by the combo box to the value specified by
712<parameter>model</parameter>. The "model" property will also be set to the
713value of <parameter>model</parameter>. A previously set model will be
714unset. If <parameter>model</parameter> is <literal>None</literal> or not
715specified, the old model will be unset.</para>
716
717      <note>
718        <para>In PyGTK 2.4.0 the model could not be <literal>None</literal>
719and did not default to <literal>None</literal>.</para>
720      </note>
721
722    </refsect2>
723
724    <refsect2 id="method-gtkcombobox--get-model">
725      <title>gtk.ComboBox.get_model</title>
726
727      <programlisting><methodsynopsis language="python">
728          <methodname>get_model</methodname>
729          <methodparam></methodparam>  </methodsynopsis></programlisting>
730      <variablelist>
731        <varlistentry>
732          <term><emphasis>Returns</emphasis>&nbsp;:</term>
733          <listitem><simpara>A <link
734          linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link>
735          or <literal>None</literal>.</simpara></listitem>
736        </varlistentry>
737      </variablelist>
738
739      <note>
740        <para>This method is available in PyGTK 2.4 and above.</para>
741      </note>
742
743      <para>The <methodname>get_model</methodname>() method returns the
744value of the "model" property which contains the <link
745linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link>
746that is acting as data source for the combo_box or <literal>None</literal>
747if no <link
748linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link> is
749associated with the combo box.</para>
750
751    </refsect2>
752
753    <refsect2 id="method-gtkcombobox--append-text">
754      <title>gtk.ComboBox.append_text</title>
755
756      <programlisting><methodsynopsis language="python">
757          <methodname>append_text</methodname>
758          <methodparam><parameter role="keyword">text</parameter></methodparam>
759        </methodsynopsis></programlisting>
760      <variablelist>
761        <varlistentry>
762          <term><parameter role="keyword">text</parameter>&nbsp;:</term>
763          <listitem><simpara>A string.</simpara></listitem>
764        </varlistentry>
765      </variablelist>
766
767      <note>
768        <para>This method is available in PyGTK 2.4 and above.</para>
769      </note>
770
771      <para>The <methodname>append_text</methodname>() method appends the
772string specified by <parameter>text</parameter> to the list of strings
773stored in the combo box <link
774linkend="class-gtkliststore"><classname>gtk.ListStore</classname></link>. Note
775that you can only use this method with combo boxes constructed with the
776<link
777linkend="function-gtk--combo-box-new-text"><function>gtk.combo_box_new_text</function>()</link>
778function.</para>
779
780    </refsect2>
781
782    <refsect2 id="method-gtkcombobox--insert-text">
783      <title>gtk.ComboBox.insert_text</title>
784
785      <programlisting><methodsynopsis language="python">
786          <methodname>insert_text</methodname>
787          <methodparam><parameter role="keyword">position</parameter></methodparam>
788          <methodparam><parameter role="keyword">text</parameter></methodparam>
789        </methodsynopsis></programlisting>
790      <variablelist>
791        <varlistentry>
792          <term><parameter role="keyword">position</parameter>&nbsp;:</term>
793          <listitem><simpara>A model index where the
794          <parameter>text</parameter> should be
795          inserted.</simpara></listitem>
796        </varlistentry>
797        <varlistentry>
798          <term><parameter role="keyword">text</parameter>&nbsp;:</term>
799          <listitem><simpara>A string.</simpara></listitem>
800        </varlistentry>
801      </variablelist>
802
803      <note>
804        <para>This method is available in PyGTK 2.4 and above.</para>
805      </note>
806
807      <para>The <methodname>insert_text</methodname>() method inserts the
808string specified by <parameter>text</parameter> in the combo box <link
809linkend="class-gtkliststore"><classname>gtk.ListStore</classname></link> at
810the index specified by <parameter>position</parameter>. Note that you can
811only use this method with combo boxes constructed with the <link
812linkend="function-gtk--combo-box-new-text"><function>gtk.combo_box_new_text</function>()</link>
813function.</para>
814
815    </refsect2>
816
817    <refsect2 id="method-gtkcombobox--prepend-text">
818      <title>gtk.ComboBox.prepend_text</title>
819
820      <programlisting><methodsynopsis language="python">
821          <methodname>prepend_text</methodname>
822          <methodparam><parameter role="keyword">text</parameter></methodparam>
823        </methodsynopsis></programlisting>
824      <variablelist>
825        <varlistentry>
826          <term><parameter role="keyword">text</parameter>&nbsp;:</term>
827          <listitem><simpara>A string.</simpara></listitem>
828        </varlistentry>
829      </variablelist>
830
831      <note>
832        <para>This method is available in PyGTK 2.4 and above.</para>
833      </note>
834
835      <para>The <methodname>prepend_text</methodname>() method prepends the
836string specified by <parameter>text</parameter> to the list of strings
837stored in the <link
838linkend="class-gtkliststore"><classname>gtk.ListStore</classname></link>
839associated with the combo_box. Note that you can only use this method with
840combo boxes constructed with the <link
841linkend="function-gtk--combo-box-new-text"><function>gtk.combo_box_new_text</function>()</link>
842function.</para>
843
844    </refsect2>
845
846    <refsect2 id="method-gtkcombobox--remove-text">
847      <title>gtk.ComboBox.remove_text</title>
848
849      <programlisting><methodsynopsis language="python">
850          <methodname>remove_text</methodname>
851          <methodparam><parameter role="keyword">position</parameter></methodparam>
852        </methodsynopsis></programlisting>
853      <variablelist>
854        <varlistentry>
855          <term><parameter role="keyword">position</parameter>&nbsp;:</term>
856          <listitem><simpara>Index of the item to remove.</simpara></listitem>
857        </varlistentry>
858      </variablelist>
859
860      <note>
861        <para>This method is available in PyGTK 2.4 and above.</para>
862      </note>
863
864      <para>The <methodname>remove_text</methodname>() method removes the
865string at the index specified by <parameter>position</parameter> in the
866associated <link
867linkend="class-gtkliststore"><classname>gtk.ListStore</classname></link>. Note
868that you can only use this function with combo boxes constructed with the
869<link
870linkend="function-gtk--combo-box-new-text"><function>gtk.combo_box_new_text</function>()</link>
871function.</para>
872
873    </refsect2>
874
875    <refsect2 id="method-gtkcombobox--get-active-text">
876      <title>gtk.ComboBox.get_active_text</title>
877
878      <programlisting><methodsynopsis language="python">
879          <methodname>get_active_text</methodname>
880          <methodparam></methodparam>
881        </methodsynopsis></programlisting>
882      <variablelist>
883        <varlistentry>
884          <term><emphasis>Returns</emphasis>&nbsp;:</term>
885          <listitem><simpara>The currently active text.</simpara></listitem>
886        </varlistentry>
887      </variablelist>
888
889      <note>
890        <para>This method is available in PyGTK 2.6 and above.</para>
891      </note>
892
893      <para>The <methodname>get_active_text</methodname>() method returns
894the currently active string or <literal>None</literal> if no entry is
895selected. Note that you can only use this function with combo boxes
896constructed with the <link
897linkend="function-gtk--combo-box-new-text"><function>gtk.combo_box_new_text</function>()</link>
898function.</para>
899
900    </refsect2>
901
902    <refsect2 id="method-gtkcombobox--popup">
903      <title>gtk.ComboBox.popup</title>
904
905      <programlisting><methodsynopsis language="python">
906          <methodname>popup</methodname>
907          <methodparam></methodparam>  </methodsynopsis></programlisting>
908
909      <note>
910        <para>This method is available in PyGTK 2.4 and above.</para>
911      </note>
912
913      <para>The <methodname>popup</methodname>() method pops up the menu or
914      dropdown list of the combo box. This method is mostly intended for use
915      by accessibility technologies; applications should have little use for
916      it.</para>
917
918    </refsect2>
919
920    <refsect2 id="method-gtkcombobox--popdown">
921      <title>gtk.ComboBox.popdown</title>
922
923      <programlisting><methodsynopsis language="python">
924          <methodname>popdown</methodname>
925          <methodparam></methodparam>  </methodsynopsis></programlisting>
926
927      <note>
928        <para>This method is available in PyGTK 2.4 and above.</para>
929      </note>
930
931      <para>The <methodname>popdown</methodname>() method hides the menu or
932dropdown list of the combo box. This method is mostly intended for use by
933accessibility technologies; applications should have little use for
934it.</para>
935
936    </refsect2>
937
938    <refsect2 id="method-gtkcombobox--get-popup-accessible">
939      <title>gtk.ComboBox.get_popup_accessible</title>
940
941      <programlisting><methodsynopsis language="python">
942          <methodname>get_popup_accessible</methodname>
943          <methodparam></methodparam>
944        </methodsynopsis></programlisting>
945      <variablelist>
946        <varlistentry>
947          <term><emphasis>Returns</emphasis>&nbsp;:</term>
948          <listitem><simpara>the accessible object corresponding to the
949popup.</simpara></listitem>
950        </varlistentry>
951      </variablelist>
952
953      <note>
954        <para>This method is available in PyGTK 2.6 and above.</para>
955      </note>
956
957      <para>The <methodname>get_popup_accessible</methodname>() method gets
958the accessible object corresponding to the popup. This method is mostly
959intended for use by accessibility technologies; applications should have
960little use for it.</para>
961
962    </refsect2>
963
964<!-- NOT IMPLEMENTED
965    <refsect2 id="method-gtkcombobox- -get-row-separator-func">
966      <title>gtk.ComboBox.get_row_separator_func</title>
967
968      <programlisting><methodsynopsis language="python">
969          <methodname>get_row_separator_func</methodname>
970          <methodparam></methodparam>
971        </methodsynopsis></programlisting>
972      <variablelist>
973        <varlistentry>
974          <term><emphasis>Returns</emphasis>&nbsp;:</term>
975          <listitem><simpara> the current row separator
976function.</simpara></listitem>
977        </varlistentry>
978      </variablelist>
979
980      <note>
981        <para>This method is available in PyGTK 2.6 and above.</para>
982      </note>
983
984      <para>The <methodname>get_row_separator_func</methodname>() method
985returns the current row separator function as set by the <link
986linkend="method-gtkcombobo- -set-row-separator-func"><methodname>set_row_separator_func</methodname>()</link>
987method.</para>
988
989    </refsect2>
990END NOT IMPLEMENTED -->
991
992    <refsect2 id="method-gtkcombobox--set-row-separator-func">
993      <title>gtk.ComboBox.set_row_separator_func</title>
994
995      <programlisting><methodsynopsis language="python">
996          <methodname>set_row_separator_func</methodname>
997          <methodparam><parameter role="keyword">func</parameter><initializer>None</initializer></methodparam>
998          <methodparam><parameter role="keyword">data</parameter><initializer>None</initializer></methodparam>
999        </methodsynopsis></programlisting>
1000      <variablelist>
1001        <varlistentry>
1002          <term><parameter role="keyword">func</parameter>&nbsp;:</term>
1003          <listitem><simpara>a function or
1004<literal>None</literal></simpara></listitem>
1005        </varlistentry>
1006        <varlistentry>
1007          <term><parameter role="keyword">data</parameter>&nbsp;:</term>
1008      <listitem><simpara>user data to pass to
1009<parameter>func</parameter></simpara></listitem>
1010        </varlistentry>
1011      </variablelist>
1012
1013      <note>
1014        <para>This method is available in PyGTK 2.6 and above.</para>
1015      </note>
1016
1017      <para>The <methodname>set_row_separator_func</methodname>() method
1018sets the row separator function to <parameter>func</parameter>, which is
1019used to determine if a row should be drawn as a separator. If func is
1020<literal>None</literal>, no separators are drawn. This is the default
1021value.</para>
1022
1023      <para>The signature of <parameter>func</parameter> is:</para>
1024
1025      <programlisting>
1026  def func(model, iter, user_data):
1027</programlisting>
1028
1029      <para>where <parameter>model</parameter> is the <link
1030linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link>
1031used by the combo box, <parameter>iter</parameter> is a <link
1032linkend="class-gtktreeiter"><classname>gtk.TreeIter</classname></link>
1033pointing at a row in <parameter>model</parameter> and
1034<parameter>user_data</parameter> is
1035<parameter>data</parameter>. <parameter>func</parameter> returns
1036<literal>True</literal> if the row is a separator. A common way to implement
1037<parameter>func</parameter> is to have a boolean column in
1038<parameter>model</parameter>, that indicates if the row is a
1039separator.</para>
1040
1041    </refsect2>
1042
1043    <refsect2 id="method-gtkcombobox--get-add-tearoffs">
1044      <title>gtk.ComboBox.get_add_tearoffs</title>
1045
1046      <programlisting><methodsynopsis language="python">
1047          <methodname>get_add_tearoffs</methodname>
1048          <methodparam></methodparam>
1049        </methodsynopsis></programlisting>
1050      <variablelist>
1051        <varlistentry>
1052          <term><emphasis>Returns</emphasis>&nbsp;:</term>
1053          <listitem><simpara><literal>True</literal> if menus should have a
1054tearoff menuitem.</simpara></listitem>
1055        </varlistentry>
1056      </variablelist>
1057
1058      <note>
1059        <para>This method is available in PyGTK 2.6 and above.</para>
1060      </note>
1061
1062      <para>The <methodname>get_add_tearoffs</methodname>() method returns the
1063value of the "add-tearoffs" property.</para>
1064
1065    </refsect2>
1066
1067    <refsect2 id="method-gtkcombobox--set-add-tearoffs">
1068      <title>gtk.ComboBox.set_add_tearoffs</title>
1069
1070      <programlisting><methodsynopsis language="python">
1071          <methodname>set_add_tearoffs</methodname>
1072          <methodparam><parameter role="keyword">add_tearoffs</parameter></methodparam>
1073        </methodsynopsis></programlisting>
1074      <variablelist>
1075        <varlistentry>
1076          <term><parameter role="keyword">add_tearoffs</parameter>&nbsp;:</term>
1077          <listitem><simpara>if <literal>True</literal> add tearoff menu items</simpara></listitem>
1078        </varlistentry>
1079      </variablelist>
1080
1081      <note>
1082        <para>This method is available in PyGTK 2.6 and above.</para>
1083      </note>
1084
1085      <para>The <methodname>set_add_tearoffs</methodname>() method sets the
1086"add-tearoffs" property to the value of
1087<parameter>add_tearoffs</parameter>. If <parameter>add_tearoffs</parameter>
1088is <literal>True</literal>, the popup menu should have a tearoff menu
1089item.</para>
1090
1091    </refsect2>
1092
1093    <refsect2 id="method-gtkcombobox--get-focus-on-click">
1094      <title>gtk.ComboBox.get_focus_on_click</title>
1095
1096      <programlisting><methodsynopsis language="python">
1097          <methodname>get_focus_on_click</methodname>
1098          <methodparam></methodparam>
1099        </methodsynopsis></programlisting>
1100      <variablelist>
1101        <varlistentry>
1102          <term><emphasis>Returns</emphasis>&nbsp;:</term>
1103          <listitem><simpara><literal>True</literal> if the combo box grabs
1104focus when it is clicked with the mouse.</simpara></listitem>
1105        </varlistentry>
1106      </variablelist>
1107
1108      <note>
1109        <para>This method is available in PyGTK 2.6 and above.</para>
1110      </note>
1111
1112      <para>The <methodname>get_focus_on_click</methodname>() method returns
1113the value of the "focus-on-click" property.</para>
1114
1115    </refsect2>
1116
1117    <refsect2 id="method-gtkcombobox--set-focus-on-click">
1118      <title>gtk.ComboBox.set_focus_on_click</title>
1119
1120      <programlisting><methodsynopsis language="python">
1121          <methodname>set_focus_on_click</methodname>
1122          <methodparam><parameter role="keyword">focus_on_click</parameter></methodparam>
1123        </methodsynopsis></programlisting>
1124      <variablelist>
1125        <varlistentry>
1126          <term><parameter role="keyword">focus_on_click</parameter>&nbsp;:</term>
1127          <listitem><simpara>if <literal>True</literal> the combo box grabs
1128focus when clicked with the mouse.</simpara></listitem>
1129        </varlistentry>
1130      </variablelist>
1131
1132      <note>
1133        <para>This method is available in PyGTK 2.6 and above.</para>
1134      </note>
1135
1136      <para>The <methodname>set_focus_on_click</methodname>() method sets the
1137value of the "focus-on-click" property to the value of
1138<parameter>focus_on_click</parameter>. If
1139<parameter>focus_on_click</parameter> is <literal>True</literal> the combo
1140box grabs focus when clicked with the mouse.</para>
1141
1142    </refsect2>
1143
1144    <refsect2 id="method-gtkcombobox--get-title">
1145      <title>gtk.ComboBox.get_title</title>
1146
1147      <programlisting><methodsynopsis language="python">
1148        <methodname>get_title</methodname>
1149        <methodparam></methodparam>
1150      </methodsynopsis></programlisting>
1151
1152      <variablelist>
1153        <varlistentry>
1154          <term><emphasis>Returns</emphasis>&nbsp;:</term>
1155          <listitem><simpara>the menu's title in tearoff
1156          mode..</simpara></listitem>
1157        </varlistentry>
1158      </variablelist>
1159
1160      <note>
1161        <para>This method is available in PyGTK 2.10 and above.</para>
1162      </note>
1163
1164      <para>The <methodname>get_title</methodname>() method returns the
1165      value of the "tearoff-title" property that contains the current title
1166      of the menu in tearoff mode. See the <link
1167      linkend="method-gtkcombobox--set-add-tearoffs"><methodname>set_add_tearoffs()</methodname></link>
1168      method for more information.</para>
1169
1170    </refsect2>
1171
1172    <refsect2 id="method-gtkcombobox--set-title">
1173      <title>gtk.ComboBox.set_title</title>
1174
1175      <programlisting><methodsynopsis language="python">
1176        <methodname>set_title</methodname>
1177        <methodparam><parameter role="keyword">title</parameter></methodparam>
1178      </methodsynopsis></programlisting>
1179
1180      <variablelist>
1181        <varlistentry>
1182          <term><parameter role="keyword">title</parameter>&nbsp;:</term>
1183          <listitem><simpara>a title for the menu in tearoff
1184          mode.</simpara></listitem>
1185        </varlistentry>
1186      </variablelist>
1187
1188      <note>
1189        <para>This method is available in PyGTK 2.10 and above.</para>
1190      </note>
1191
1192      <para>The <methodname>set_title</methodname>() method sets the
1193      "tearoff-title" property to the value of
1194      <parameter>title</parameter>. The "tearoff-title" property contains
1195      the menu's title in tearoff mode.</para>
1196
1197    </refsect2>
1198
1199  </refsect1>
1200
1201  <refsect1>
1202    <title>Functions</title>
1203
1204    <refsect2 id="function-gtk--combo-box-new-text">
1205      <title>gtk.combo_box_new_text</title>
1206
1207      <programlisting><methodsynopsis language="python">
1208          <methodname>gtk.combo_box_new_text</methodname>
1209          <methodparam></methodparam>
1210        </methodsynopsis></programlisting>
1211      <variablelist>
1212        <varlistentry>
1213        <term><emphasis>Returns</emphasis>&nbsp;:</term>
1214          <listitem><simpara>A new <link
1215          linkend="class-gtkcombobox"><classname>gtk.ComboBox</classname></link>
1216          for text items.</simpara></listitem>
1217        </varlistentry>
1218      </variablelist>
1219
1220      <note>
1221        <para>This function is available in PyGTK 2.4 and above.</para>
1222      </note>
1223
1224      <para>The <function>gtk.combo_box_new_text</function>() function is a
1225convenience function that constructs a new text combo box, which is a <link
1226linkend="class-gtkcombobox"><classname>gtk.ComboBox</classname></link> just
1227displaying strings. If you use this function to create a text combo box, you
1228should only manipulate its data source with the following convenience
1229methods: <link
1230linkend="method-gtkcombobox--append-text"><methodname>append_text</methodname>()</link>,
1231<link
1232linkend="method-gtkcombobox--insert-text"><methodname>insert_text</methodname>()</link>,
1233<link
1234linkend="method-gtkcombobox--prepend-text"><methodname>prepend_text</methodname>()</link>
1235and <link
1236linkend="method-gtkcombobox--remove-text"><methodname>remove_text</methodname>()</link>.</para>
1237
1238    </refsect2>
1239
1240  </refsect1>
1241
1242  <refsect1>
1243    <title>Signals</title>
1244
1245    <refsect2 id="signal-gtkcombobox--changed">
1246      <title>The "changed" gtk.ComboBox Signal</title>
1247
1248      <programlisting><methodsynopsis language="python">
1249          <methodname>callback</methodname>
1250          <methodparam><parameter>combobox</parameter></methodparam>
1251          <methodparam><parameter>user_param1</parameter></methodparam>
1252          <methodparam><parameter>...</parameter></methodparam>
1253        </methodsynopsis></programlisting>
1254
1255      <variablelist>
1256        <varlistentry>
1257          <term><parameter>combobox</parameter>&nbsp;:</term>
1258          <listitem><simpara>the combo box that received the
1259signal</simpara></listitem>
1260        </varlistentry>
1261        <varlistentry>
1262          <term><parameter>user_param1</parameter>&nbsp;:</term>
1263          <listitem><simpara>the first user parameter (if any) specified
1264with the <link
1265linkend="method-gobject--connect"><methodname>connect</methodname>()</link>
1266method</simpara></listitem>
1267        </varlistentry>
1268        <varlistentry>
1269          <term><parameter>...</parameter>&nbsp;:</term>
1270          <listitem><simpara>additional user parameters (if
1271any)</simpara></listitem>
1272        </varlistentry>
1273      </variablelist>
1274
1275      <note>
1276        <para>This signal is available in PyGTK 2.4 and above.</para>
1277      </note>
1278
1279      <para>The "changed" signal is emitted when a new item in the combo box
1280is selected.</para>
1281
1282    </refsect2>
1283
1284  </refsect1>
1285
1286</refentry>
Note: See TracBrowser for help on using the repository browser.