source: trunk/doc/html/qcombobox.html

Last change on this file was 190, checked in by rudi, 14 years ago

reference documentation added
File size: 39.2 KB
RevLine 
[190]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/src/widgets/qcombobox.cpp:59 -->
3<html>
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
6<title>QComboBox Class</title>
7<style type="text/css"><!--
8fn { margin-left: 1cm; text-indent: -1cm; }
9a:link { color: #004faf; text-decoration: none }
10a:visited { color: #672967; text-decoration: none }
11body { background: #ffffff; color: black; }
12--></style>
13</head>
14<body>
15
16<table border="0" cellpadding="0" cellspacing="0" width="100%">
17<tr bgcolor="#E5E5E5">
18<td valign=center>
19 <a href="index.html">
20<font color="#004faf">Home</font></a>
21 | <a href="classes.html">
22<font color="#004faf">All&nbsp;Classes</font></a>
23 | <a href="mainclasses.html">
24<font color="#004faf">Main&nbsp;Classes</font></a>
25 | <a href="annotated.html">
26<font color="#004faf">Annotated</font></a>
27 | <a href="groups.html">
28<font color="#004faf">Grouped&nbsp;Classes</font></a>
29 | <a href="functions.html">
30<font color="#004faf">Functions</font></a>
31</td>
32<td align="right" valign="center"><img src="logo32.png" align="right" width="64" height="32" border="0"></td></tr></table><h1 align=center>QComboBox Class Reference</h1>
33
34<p>The QComboBox widget is a combined button and popup list.
35<a href="#details">More...</a>
36<p><tt>#include &lt;<a href="qcombobox-h.html">qcombobox.h</a>&gt;</tt>
37<p>Inherits <a href="qwidget.html">QWidget</a>.
38<p><a href="qcombobox-members.html">List of all member functions.</a>
39<h2>Public Members</h2>
40<ul>
41<li class=fn><a href="#QComboBox"><b>QComboBox</b></a> ( QWidget&nbsp;*&nbsp;parent = 0, const&nbsp;char&nbsp;*&nbsp;name = 0 )</li>
42<li class=fn><a href="#QComboBox-2"><b>QComboBox</b></a> ( bool&nbsp;rw, QWidget&nbsp;*&nbsp;parent = 0, const&nbsp;char&nbsp;*&nbsp;name = 0 )</li>
43<li class=fn><a href="#~QComboBox"><b>~QComboBox</b></a> ()</li>
44<li class=fn>int <a href="#count"><b>count</b></a> () const</li>
45<li class=fn>void <a href="#insertStringList"><b>insertStringList</b></a> ( const&nbsp;QStringList&nbsp;&amp;&nbsp;list, int&nbsp;index = -1 )</li>
46<li class=fn>void <a href="#insertStrList-2"><b>insertStrList</b></a> ( const&nbsp;QStrList&nbsp;&amp;&nbsp;list, int&nbsp;index = -1 )</li>
47<li class=fn>void <a href="#insertStrList-3"><b>insertStrList</b></a> ( const&nbsp;QStrList&nbsp;*&nbsp;list, int&nbsp;index = -1 )</li>
48<li class=fn>void <a href="#insertStrList"><b>insertStrList</b></a> ( const&nbsp;char&nbsp;**&nbsp;strings, int&nbsp;numStrings = -1, int&nbsp;index = -1 )</li>
49<li class=fn>void <a href="#insertItem"><b>insertItem</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;t, int&nbsp;index = -1 )</li>
50<li class=fn>void <a href="#insertItem-2"><b>insertItem</b></a> ( const&nbsp;QPixmap&nbsp;&amp;&nbsp;pixmap, int&nbsp;index = -1 )</li>
51<li class=fn>void <a href="#insertItem-3"><b>insertItem</b></a> ( const&nbsp;QPixmap&nbsp;&amp;&nbsp;pixmap, const&nbsp;QString&nbsp;&amp;&nbsp;text, int&nbsp;index = -1 )</li>
52<li class=fn>void <a href="#removeItem"><b>removeItem</b></a> ( int&nbsp;index )</li>
53<li class=fn>int <a href="#currentItem"><b>currentItem</b></a> () const</li>
54<li class=fn>virtual void <a href="#setCurrentItem"><b>setCurrentItem</b></a> ( int&nbsp;index )</li>
55<li class=fn>QString <a href="#currentText"><b>currentText</b></a> () const</li>
56<li class=fn>virtual void <a href="#setCurrentText"><b>setCurrentText</b></a> ( const QString &amp; )</li>
57<li class=fn>QString <a href="#text"><b>text</b></a> ( int&nbsp;index ) const</li>
58<li class=fn>const QPixmap * <a href="#pixmap"><b>pixmap</b></a> ( int&nbsp;index ) const</li>
59<li class=fn>void <a href="#changeItem"><b>changeItem</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;t, int&nbsp;index )</li>
60<li class=fn>void <a href="#changeItem-2"><b>changeItem</b></a> ( const&nbsp;QPixmap&nbsp;&amp;&nbsp;im, int&nbsp;index )</li>
61<li class=fn>void <a href="#changeItem-3"><b>changeItem</b></a> ( const&nbsp;QPixmap&nbsp;&amp;&nbsp;im, const&nbsp;QString&nbsp;&amp;&nbsp;t, int&nbsp;index )</li>
62<li class=fn>bool autoResize () const &nbsp;<em>(obsolete)</em></li>
63<li class=fn>virtual void setAutoResize ( bool ) &nbsp;<em>(obsolete)</em></li>
64<li class=fn>virtual void <a href="#setPalette"><b>setPalette</b></a> ( const&nbsp;QPalette&nbsp;&amp;&nbsp;palette )</li>
65<li class=fn>virtual void <a href="#setFont"><b>setFont</b></a> ( const&nbsp;QFont&nbsp;&amp;&nbsp;font )</li>
66<li class=fn>virtual void <a href="#setSizeLimit"><b>setSizeLimit</b></a> ( int )</li>
67<li class=fn>int <a href="#sizeLimit"><b>sizeLimit</b></a> () const</li>
68<li class=fn>virtual void <a href="#setMaxCount"><b>setMaxCount</b></a> ( int )</li>
69<li class=fn>int <a href="#maxCount"><b>maxCount</b></a> () const</li>
70<li class=fn>enum <a href="#Policy-enum"><b>Policy</b></a> { NoInsertion, AtTop, AtCurrent, AtBottom, AfterCurrent, BeforeCurrent }</li>
71<li class=fn>virtual void <a href="#setInsertionPolicy"><b>setInsertionPolicy</b></a> ( Policy&nbsp;policy )</li>
72<li class=fn>Policy <a href="#insertionPolicy"><b>insertionPolicy</b></a> () const</li>
73<li class=fn>virtual void <a href="#setValidator"><b>setValidator</b></a> ( const&nbsp;QValidator&nbsp;*&nbsp;v )</li>
74<li class=fn>const QValidator * <a href="#validator"><b>validator</b></a> () const</li>
75<li class=fn>virtual void <a href="#setListBox"><b>setListBox</b></a> ( QListBox&nbsp;*&nbsp;newListBox )</li>
76<li class=fn>QListBox * <a href="#listBox"><b>listBox</b></a> () const</li>
77<li class=fn>virtual void <a href="#setLineEdit"><b>setLineEdit</b></a> ( QLineEdit&nbsp;*&nbsp;edit )</li>
78<li class=fn>QLineEdit * <a href="#lineEdit"><b>lineEdit</b></a> () const</li>
79<li class=fn>virtual void <a href="#setAutoCompletion"><b>setAutoCompletion</b></a> ( bool )</li>
80<li class=fn>bool <a href="#autoCompletion"><b>autoCompletion</b></a> () const</li>
81<li class=fn>void <a href="#setDuplicatesEnabled"><b>setDuplicatesEnabled</b></a> ( bool&nbsp;enable )</li>
82<li class=fn>bool <a href="#duplicatesEnabled"><b>duplicatesEnabled</b></a> () const</li>
83<li class=fn>bool <a href="#editable"><b>editable</b></a> () const</li>
84<li class=fn>void <a href="#setEditable"><b>setEditable</b></a> ( bool )</li>
85<li class=fn>virtual void <a href="#popup"><b>popup</b></a> ()</li>
86</ul>
87<h2>Public Slots</h2>
88<ul>
89<li class=fn>void <a href="#clear"><b>clear</b></a> ()</li>
90<li class=fn>void <a href="#clearValidator"><b>clearValidator</b></a> ()</li>
91<li class=fn>void <a href="#clearEdit"><b>clearEdit</b></a> ()</li>
92<li class=fn>virtual void <a href="#setEditText"><b>setEditText</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;newText )</li>
93</ul>
94<h2>Signals</h2>
95<ul>
96<li class=fn>void <a href="#activated"><b>activated</b></a> ( int&nbsp;index )</li>
97<li class=fn>void <a href="#highlighted"><b>highlighted</b></a> ( int&nbsp;index )</li>
98<li class=fn>void <a href="#activated-2"><b>activated</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;string )</li>
99<li class=fn>void <a href="#highlighted-2"><b>highlighted</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;string )</li>
100<li class=fn>void <a href="#textChanged"><b>textChanged</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;string )</li>
101</ul>
102<h2>Properties</h2>
103<ul>
104<li class=fn>bool <a href="#autoCompletion-prop"><b>autoCompletion</b></a>&nbsp;- whether auto-completion is enabled</li>
105<li class=fn>bool <a href="#autoMask-prop"><b>autoMask</b></a>&nbsp;- whether the combobox is automatically masked &nbsp;<em>(read only)</em></li>
106<li class=fn>bool autoResize&nbsp;- whether auto resize is enabled &nbsp;<em>(obsolete)</em></li>
107<li class=fn>int <a href="#count-prop"><b>count</b></a>&nbsp;- the number of items in the combobox &nbsp;<em>(read only)</em></li>
108<li class=fn>int <a href="#currentItem-prop"><b>currentItem</b></a>&nbsp;- the index of the current item in the combobox</li>
109<li class=fn>QString <a href="#currentText-prop"><b>currentText</b></a>&nbsp;- the text of the combobox's current item</li>
110<li class=fn>bool <a href="#duplicatesEnabled-prop"><b>duplicatesEnabled</b></a>&nbsp;- whether duplicates are allowed</li>
111<li class=fn>bool <a href="#editable-prop"><b>editable</b></a>&nbsp;- whether the combobox is editable</li>
112<li class=fn>Policy <a href="#insertionPolicy-prop"><b>insertionPolicy</b></a>&nbsp;- the position of the items inserted by the user</li>
113<li class=fn>int <a href="#maxCount-prop"><b>maxCount</b></a>&nbsp;- the maximum number of items allowed in the combobox</li>
114<li class=fn>int <a href="#sizeLimit-prop"><b>sizeLimit</b></a>&nbsp;- the maximum on-screen size of the combobox</li>
115</ul>
116<hr><a name="details"></a><h2>Detailed Description</h2>
117
118
119The QComboBox widget is a combined button and popup list.
120<p>
121
122<p> A combobox is a selection widget which displays the current item
123and can pop up a list of items. A combobox may be editable in
124which case the user can enter arbitrary strings.
125<p> Comboboxes provide a means of showing the user's current choice
126out of a list of options in a way that takes up the minimum amount
127of screen space.
128<p> QComboBox supports three different display styles: Aqua/Motif 1.x,
129<a href="motif-extension.html#Motif">Motif</a> 2.0 and Windows. In Motif 1.x, a combobox was called
130XmOptionMenu. In Motif 2.0, OSF introduced an improved combobox
131and named that XmComboBox. QComboBox provides both.
132<p> QComboBox provides two different constructors. The simplest
133constructor creates an "old-style" combobox in Motif (or Aqua)
134style:
135<pre>
136 QComboBox *c = new QComboBox( this, "read-only combobox" );
137 </pre>
138
139<p> The other constructor creates a new-style combobox in Motif style,
140and can create both read-only and editable comboboxes:
141<pre>
142 QComboBox *c1 = new QComboBox( FALSE, this, "read-only combobox" );
143 QComboBox *c2 = new QComboBox( TRUE, this, "editable combobox" );
144 </pre>
145
146<p> New-style comboboxes use a list box in both Motif and Windows
147styles, and both the content size and the on-screen size of the
148list box can be limited with <a href="#sizeLimit">sizeLimit</a>() and <a href="#setMaxCount">setMaxCount</a>()
149respectively. Old-style comboboxes use a popup in Aqua and Motif
150style, and that popup will happily grow larger than the desktop if
151you put enough data into it.
152<p> The two constructors create identical-looking comboboxes in
153Windows style.
154<p> Comboboxes can contain pixmaps as well as strings; the
155<a href="#insertItem">insertItem</a>() and <a href="#changeItem">changeItem</a>() functions are suitably overloaded.
156For editable comboboxes, the function <a href="#clearEdit">clearEdit</a>() is provided,
157to clear the displayed string without changing the combobox's
158contents.
159<p> A combobox emits two signals, <a href="#activated">activated</a>() and <a href="#highlighted">highlighted</a>(), when
160a new item has been activated (selected) or highlighted (made
161current). Both signals exist in two versions, one with a <a href="qstring.html">QString</a> argument and one with an <tt>int</tt> argument. If the user
162highlights or activates a pixmap, only the <tt>int</tt> signals are
163emitted. Whenever the text of an editable combobox is changed the
164<a href="#textChanged">textChanged</a>() signal is emitted.
165<p> When the user enters a new string in an editable combobox, the
166widget may or may not insert it, and it can insert it in several
167locations. The default policy is is <a href="#Policy-enum">AtBottom</a> but you can change
168this using <a href="#setInsertionPolicy">setInsertionPolicy</a>().
169<p> It is possible to constrain the input to an editable combobox
170using <a href="qvalidator.html">QValidator</a>; see <a href="#setValidator">setValidator</a>(). By default, any input is
171accepted.
172<p> If the combobox is not editable then it has a default
173<a href="qwidget.html#focusPolicy">focusPolicy</a>() of <a href="qwidget.html#FocusPolicy-enum">TabFocus</a>, i.e. it will not grab focus if
174clicked. This differs from both Windows and Motif. If the combobox
175is editable then it has a default focusPolicy() of <a href="qwidget.html#FocusPolicy-enum">StrongFocus</a>,
176i.e. it will grab focus if clicked.
177<p> A combobox can be populated using the insert functions,
178<a href="#insertStringList">insertStringList</a>() and <a href="#insertItem">insertItem</a>() for example. Items can be
179changed with <a href="#changeItem">changeItem</a>(). An item can be removed with
180<a href="#removeItem">removeItem</a>() and all items can be removed with <a href="#clear">clear</a>(). The text
181of the current item is returned by <a href="#currentText">currentText</a>(), and the text of
182a numbered item is returned with <a href="#text">text</a>(). The current item can be
183set with <a href="#setCurrentItem">setCurrentItem</a>() or <a href="#setCurrentText">setCurrentText</a>(). The number of items
184in the combobox is returned by <a href="#count">count</a>(); the maximum number of
185items can be set with <a href="#setMaxCount">setMaxCount</a>(). You can allow editing using
186<a href="#setEditable">setEditable</a>(). For editable comboboxes you can set auto-completion
187using <a href="#setAutoCompletion">setAutoCompletion</a>() and whether or not the user can add
188duplicates is set with <a href="#setDuplicatesEnabled">setDuplicatesEnabled</a>().
189<p> <img src="qcombo1-m.png">(Motif 1, read-only)<br clear=all>
190<img src="qcombo2-m.png">(Motif 2, editable)<br clear=all>
191<img src="qcombo3-m.png">(Motif 2, read-only)<br clear=all>
192<img src="qcombo1-w.png">(Windows style)
193<p> Depending on the style, QComboBox will use a <a href="qlistbox.html">QListBox</a> or a
194<a href="qpopupmenu.html">QPopupMenu</a> to display the list of items. See <a href="#setListBox">setListBox</a>() for
195more information.
196<p> <p>See also <a href="qlineedit.html">QLineEdit</a>, <a href="qlistbox.html">QListBox</a>, <a href="qspinbox.html">QSpinBox</a>, <a href="qradiobutton.html">QRadioButton</a>, <a href="qbuttongroup.html">QButtonGroup</a>, <a href="guibooks.html#fowler">GUI Design Handbook: Combo Box</a>, <a href="guibooks.html#fowler">GUI Design Handbook: Drop-Down List Box</a>, and <a href="basic.html">Basic Widgets</a>.
197
198<hr><h2>Member Type Documentation</h2>
199<h3 class=fn><a name="Policy-enum"></a>QComboBox::Policy</h3>
200
201<p> This enum specifies what the QComboBox should do when a new string
202is entered by the user.
203<ul>
204<li><tt>QComboBox::NoInsertion</tt> - the string will not be inserted into the
205combobox.
206<li><tt>QComboBox::AtTop</tt> - insert the string as the first item in the combobox.
207<li><tt>QComboBox::AtCurrent</tt> - replace the previously selected item with the
208string the user has entered.
209<li><tt>QComboBox::AtBottom</tt> - insert the string as the last item in the
210combobox.
211<li><tt>QComboBox::AfterCurrent</tt> - insert the string after the previously
212selected item.
213<li><tt>QComboBox::BeforeCurrent</tt> - insert the string before the previously
214selected item.
215</ul><p> <a href="#activated">activated</a>() is always emitted when the string is entered.
216<p> If inserting the new string would cause the combobox to breach its
217content size limit, the item at the other end of the list is
218deleted. The definition of "other end" is
219implementation-dependent.
220
221<hr><h2>Member Function Documentation</h2>
222<h3 class=fn><a name="QComboBox"></a>QComboBox::QComboBox ( <a href="qwidget.html">QWidget</a>&nbsp;*&nbsp;parent = 0, const&nbsp;char&nbsp;*&nbsp;name = 0 )
223</h3>
224Constructs a combobox widget with parent <em>parent</em> called <em>name</em>.
225<p> This constructor creates a popup list if the program uses <a href="motif-extension.html#Motif">Motif</a>
226(or Aqua) look and feel; this is compatible with Motif 1.x and
227Aqua.
228<p> Note: If you use this constructor to create your QComboBox, then
229the <a href="#pixmap">pixmap</a>() function will always return 0. To workaround this,
230use the other constructor.
231<p>
232<h3 class=fn><a name="QComboBox-2"></a>QComboBox::QComboBox ( bool&nbsp;rw, <a href="qwidget.html">QWidget</a>&nbsp;*&nbsp;parent = 0, const&nbsp;char&nbsp;*&nbsp;name = 0 )
233</h3>
234Constructs a combobox with a maximum size and either <a href="motif-extension.html#Motif">Motif</a> 2.0 or
235Windows look and feel.
236<p> The input field can be edited if <em>rw</em> is TRUE, otherwise the user
237may only choose one of the items in the combobox.
238<p> The <em>parent</em> and <em>name</em> arguments are passed on to the <a href="qwidget.html">QWidget</a>
239constructor.
240
241<h3 class=fn><a name="~QComboBox"></a>QComboBox::~QComboBox ()
242</h3>
243Destroys the combobox.
244
245<h3 class=fn>void <a name="activated"></a>QComboBox::activated ( int&nbsp;index )<tt> [signal]</tt>
246</h3>
247
248<p> This signal is emitted when a new item has been activated
249(selected). The <em>index</em> is the position of the item in the
250combobox.
251<p> This signal is not emitted if the item is changed
252programmatically, e.g. using <a href="#setCurrentItem">setCurrentItem</a>().
253
254<p>Examples: <a href="fileiconview-example.html#x877">fileiconview/mainwindow.cpp</a>, <a href="helpviewer-example.html#x981">helpviewer/helpwindow.cpp</a>, <a href="lineedits-example.html#x170">lineedits/lineedits.cpp</a>, <a href="listboxcombo-example.html#x1398">listboxcombo/listboxcombo.cpp</a>, and <a href="qmag-example.html#x1772">qmag/qmag.cpp</a>.
255<h3 class=fn>void <a name="activated-2"></a>QComboBox::activated ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;string )<tt> [signal]</tt>
256</h3>
257This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
258<p> This signal is emitted when a new item has been activated
259(selected). <em>string</em> is the selected string.
260<p> You can also use the <a href="#activated">activated</a>(int) signal, but be aware that its
261argument is meaningful only for selected strings, not for user
262entered strings.
263
264<h3 class=fn>bool <a name="autoCompletion"></a>QComboBox::autoCompletion () const
265</h3><p>Returns TRUE if auto-completion is enabled; otherwise returns FALSE.
266See the <a href="qcombobox.html#autoCompletion-prop">"autoCompletion"</a> property for details.
267<h3 class=fn>bool <a name="autoResize"></a>QComboBox::autoResize () const
268</h3><p>Returns TRUE if auto resize is enabled; otherwise returns FALSE.
269See the <a href="qcombobox.html#autoResize-prop">"autoResize"</a> property for details.
270<h3 class=fn>void <a name="changeItem"></a>QComboBox::changeItem ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;t, int&nbsp;index )
271</h3>
272Replaces the item at position <em>index</em> with the text <em>t</em>.
273
274<h3 class=fn>void <a name="changeItem-2"></a>QComboBox::changeItem ( const&nbsp;<a href="qpixmap.html">QPixmap</a>&nbsp;&amp;&nbsp;im, int&nbsp;index )
275</h3>
276This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
277<p> Replaces the item at position <em>index</em> with the pixmap <em>im</em>,
278unless the combobox is editable.
279<p> <p>See also <a href="#insertItem">insertItem</a>().
280
281<h3 class=fn>void <a name="changeItem-3"></a>QComboBox::changeItem ( const&nbsp;<a href="qpixmap.html">QPixmap</a>&nbsp;&amp;&nbsp;im, const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;t, int&nbsp;index )
282</h3>
283This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
284<p> Replaces the item at position <em>index</em> with the pixmap <em>im</em> and
285the text <em>t</em>.
286<p> <p>See also <a href="#insertItem">insertItem</a>().
287
288<h3 class=fn>void <a name="clear"></a>QComboBox::clear ()<tt> [slot]</tt>
289</h3>
290Removes all combobox items.
291
292<h3 class=fn>void <a name="clearEdit"></a>QComboBox::clearEdit ()<tt> [slot]</tt>
293</h3>
294Clears the line edit without changing the combobox's contents.
295Does nothing if the combobox isn't editable.
296<p> This is particularly useful when using a combobox as a line edit
297with history. For example you can connect the combobox's
298<a href="#activated">activated</a>() signal to <a href="#clearEdit">clearEdit</a>() in order to present the user
299with a new, empty line as soon as Enter is pressed.
300<p> <p>See also <a href="#setEditText">setEditText</a>().
301
302<h3 class=fn>void <a name="clearValidator"></a>QComboBox::clearValidator ()<tt> [slot]</tt>
303</h3>
304This slot is equivalent to <a href="#setValidator">setValidator</a>( 0 ).
305
306<h3 class=fn>int <a name="count"></a>QComboBox::count () const
307</h3><p>Returns the number of items in the combobox.
308See the <a href="qcombobox.html#count-prop">"count"</a> property for details.
309<h3 class=fn>int <a name="currentItem"></a>QComboBox::currentItem () const
310</h3><p>Returns the index of the current item in the combobox.
311See the <a href="qcombobox.html#currentItem-prop">"currentItem"</a> property for details.
312<h3 class=fn><a href="qstring.html">QString</a> <a name="currentText"></a>QComboBox::currentText () const
313</h3><p>Returns the text of the combobox's current item.
314See the <a href="qcombobox.html#currentText-prop">"currentText"</a> property for details.
315<h3 class=fn>bool <a name="duplicatesEnabled"></a>QComboBox::duplicatesEnabled () const
316</h3><p>Returns TRUE if duplicates are allowed; otherwise returns FALSE.
317See the <a href="qcombobox.html#duplicatesEnabled-prop">"duplicatesEnabled"</a> property for details.
318<h3 class=fn>bool <a name="editable"></a>QComboBox::editable () const
319</h3><p>Returns TRUE if the combobox is editable; otherwise returns FALSE.
320See the <a href="qcombobox.html#editable-prop">"editable"</a> property for details.
321<h3 class=fn>void <a name="highlighted"></a>QComboBox::highlighted ( int&nbsp;index )<tt> [signal]</tt>
322</h3>
323
324<p> This signal is emitted when a new item has been set to be the
325current item. The <em>index</em> is the position of the item in the
326combobox.
327<p> This signal is not emitted if the item is changed
328programmatically, e.g. using <a href="#setCurrentItem">setCurrentItem</a>().
329
330<h3 class=fn>void <a name="highlighted-2"></a>QComboBox::highlighted ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;string )<tt> [signal]</tt>
331</h3>
332This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
333<p> This signal is emitted when a new item has been set to be the
334current item. <em>string</em> is the item's text.
335<p> You can also use the <a href="#highlighted">highlighted</a>(int) signal.
336
337<h3 class=fn>void <a name="insertItem"></a>QComboBox::insertItem ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;t, int&nbsp;index = -1 )
338</h3>
339Inserts a text item with text <em>t</em>, at position <em>index</em>. The item
340will be appended if <em>index</em> is negative.
341
342<p>Examples: <a href="tutorial2-09.html#x2633">chart/optionsform.cpp</a>, <a href="fileiconview-example.html#x879">fileiconview/mainwindow.cpp</a>, <a href="helpviewer-example.html#x983">helpviewer/helpwindow.cpp</a>, <a href="lineedits-example.html#x171">lineedits/lineedits.cpp</a>, <a href="listboxcombo-example.html#x1399">listboxcombo/listboxcombo.cpp</a>, <a href="regexptester-example.html#x2479">regexptester/regexptester.cpp</a>, and <a href="tictac-example.html#x23">tictac/tictac.cpp</a>.
343<h3 class=fn>void <a name="insertItem-2"></a>QComboBox::insertItem ( const&nbsp;<a href="qpixmap.html">QPixmap</a>&nbsp;&amp;&nbsp;pixmap, int&nbsp;index = -1 )
344</h3>
345This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
346<p> Inserts a <em>pixmap</em> item at position <em>index</em>. The item will be
347appended if <em>index</em> is negative.
348
349<h3 class=fn>void <a name="insertItem-3"></a>QComboBox::insertItem ( const&nbsp;<a href="qpixmap.html">QPixmap</a>&nbsp;&amp;&nbsp;pixmap, const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;text, int&nbsp;index = -1 )
350</h3>
351This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
352<p> Inserts a <em>pixmap</em> item with additional text <em>text</em> at position
353<em>index</em>. The item will be appended if <em>index</em> is negative.
354
355<h3 class=fn>void <a name="insertStrList"></a>QComboBox::insertStrList ( const&nbsp;char&nbsp;**&nbsp;strings, int&nbsp;numStrings = -1, int&nbsp;index = -1 )
356</h3>
357Inserts the array of char * <em>strings</em> at position <em>index</em> in the
358combobox.
359<p> The <em>numStrings</em> argument is the number of strings. If <em>numStrings</em> is -1 (default), the <em>strings</em> array must be
360terminated with 0.
361<p> Example:
362<pre>
363 static const char* items[] = { "red", "green", "blue", 0 };
364 combo-&gt;insertStrList( items );
365 </pre>
366
367<p> <p>See also <a href="#insertStringList">insertStringList</a>().
368
369<p>Example: <a href="qmag-example.html#x1773">qmag/qmag.cpp</a>.
370<h3 class=fn>void <a name="insertStrList-2"></a>QComboBox::insertStrList ( const&nbsp;<a href="qstrlist.html">QStrList</a>&nbsp;&amp;&nbsp;list, int&nbsp;index = -1 )
371</h3>
372This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
373<p> Inserts the <em>list</em> of strings at position <em>index</em> in the
374combobox.
375<p> This is only for compatibility since it does not support Unicode
376strings. See <a href="#insertStringList">insertStringList</a>().
377
378<h3 class=fn>void <a name="insertStrList-3"></a>QComboBox::insertStrList ( const&nbsp;<a href="qstrlist.html">QStrList</a>&nbsp;*&nbsp;list, int&nbsp;index = -1 )
379</h3>
380This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
381<p> Inserts the <em>list</em> of strings at position <em>index</em> in the
382combobox.
383<p> This is only for compatibility since it does not support Unicode
384strings. See <a href="#insertStringList">insertStringList</a>().
385
386<h3 class=fn>void <a name="insertStringList"></a>QComboBox::insertStringList ( const&nbsp;<a href="qstringlist.html">QStringList</a>&nbsp;&amp;&nbsp;list, int&nbsp;index = -1 )
387</h3>
388Inserts the <em>list</em> of strings at position <em>index</em> in the
389combobox.
390
391<h3 class=fn><a href="qcombobox.html#Policy-enum">Policy</a> <a name="insertionPolicy"></a>QComboBox::insertionPolicy () const
392</h3><p>Returns the position of the items inserted by the user.
393See the <a href="qcombobox.html#insertionPolicy-prop">"insertionPolicy"</a> property for details.
394<h3 class=fn><a href="qlineedit.html">QLineEdit</a>&nbsp;* <a name="lineEdit"></a>QComboBox::lineEdit () const
395</h3>
396Returns the line edit, or 0 if there is no line edit.
397<p> Only editable listboxes have a line editor.
398
399<h3 class=fn><a href="qlistbox.html">QListBox</a>&nbsp;* <a name="listBox"></a>QComboBox::listBox () const
400</h3>
401Returns the current list box, or 0 if there is no list box.
402(QComboBox can use <a href="qpopupmenu.html">QPopupMenu</a> instead of <a href="qlistbox.html">QListBox</a>.) Provided to
403match <a href="#setListBox">setListBox</a>().
404<p> <p>See also <a href="#setListBox">setListBox</a>().
405
406<p>Example: <a href="listboxcombo-example.html#x1400">listboxcombo/listboxcombo.cpp</a>.
407<h3 class=fn>int <a name="maxCount"></a>QComboBox::maxCount () const
408</h3><p>Returns the maximum number of items allowed in the combobox.
409See the <a href="qcombobox.html#maxCount-prop">"maxCount"</a> property for details.
410<h3 class=fn>const&nbsp;<a href="qpixmap.html">QPixmap</a>&nbsp;* <a name="pixmap"></a>QComboBox::pixmap ( int&nbsp;index ) const
411</h3>
412Returns the pixmap item at position <em>index</em>, or 0 if the item is
413not a pixmap.
414
415<h3 class=fn>void <a name="popup"></a>QComboBox::popup ()<tt> [virtual]</tt>
416</h3>
417Pops up the combobox popup list.
418<p> If the list is empty, no items appear.
419
420<h3 class=fn>void <a name="removeItem"></a>QComboBox::removeItem ( int&nbsp;index )
421</h3>
422Removes the item at position <em>index</em>.
423
424<h3 class=fn>void <a name="setAutoCompletion"></a>QComboBox::setAutoCompletion ( bool )<tt> [virtual]</tt>
425</h3><p>Sets whether auto-completion is enabled.
426See the <a href="qcombobox.html#autoCompletion-prop">"autoCompletion"</a> property for details.
427<h3 class=fn>void <a name="setAutoResize"></a>QComboBox::setAutoResize ( bool )<tt> [virtual]</tt>
428</h3><p>Sets whether auto resize is enabled.
429See the <a href="qcombobox.html#autoResize-prop">"autoResize"</a> property for details.
430<h3 class=fn>void <a name="setCurrentItem"></a>QComboBox::setCurrentItem ( int&nbsp;index )<tt> [virtual]</tt>
431</h3><p>Sets the index of the current item in the combobox to <em>index</em>.
432See the <a href="qcombobox.html#currentItem-prop">"currentItem"</a> property for details.
433<h3 class=fn>void <a name="setCurrentText"></a>QComboBox::setCurrentText ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp; )<tt> [virtual]</tt>
434</h3><p>Sets the text of the combobox's current item.
435See the <a href="qcombobox.html#currentText-prop">"currentText"</a> property for details.
436<h3 class=fn>void <a name="setDuplicatesEnabled"></a>QComboBox::setDuplicatesEnabled ( bool&nbsp;enable )
437</h3><p>Sets whether duplicates are allowed to <em>enable</em>.
438See the <a href="qcombobox.html#duplicatesEnabled-prop">"duplicatesEnabled"</a> property for details.
439<h3 class=fn>void <a name="setEditText"></a>QComboBox::setEditText ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;newText )<tt> [virtual slot]</tt>
440</h3>
441Sets the text in the line edit to <em>newText</em> without changing the
442combobox's contents. Does nothing if the combobox isn't editable.
443<p> This is useful e.g. for providing a good starting point for the
444user's editing and entering the change in the combobox only when
445the user presses Enter.
446<p> <p>See also <a href="#clearEdit">clearEdit</a>() and <a href="#insertItem">insertItem</a>().
447
448<h3 class=fn>void <a name="setEditable"></a>QComboBox::setEditable ( bool )
449</h3><p>Sets whether the combobox is editable.
450See the <a href="qcombobox.html#editable-prop">"editable"</a> property for details.
451<h3 class=fn>void <a name="setFont"></a>QComboBox::setFont ( const&nbsp;<a href="qfont.html">QFont</a>&nbsp;&amp;&nbsp;font )<tt> [virtual]</tt>
452</h3>
453Sets the font for both the combobox button and the combobox popup
454list to <em>font</em>.
455
456<p>Reimplemented from <a href="qwidget.html#setFont">QWidget</a>.
457<h3 class=fn>void <a name="setInsertionPolicy"></a>QComboBox::setInsertionPolicy ( <a href="qcombobox.html#Policy-enum">Policy</a>&nbsp;policy )<tt> [virtual]</tt>
458</h3><p>Sets the position of the items inserted by the user to <em>policy</em>.
459See the <a href="qcombobox.html#insertionPolicy-prop">"insertionPolicy"</a> property for details.
460<h3 class=fn>void <a name="setLineEdit"></a>QComboBox::setLineEdit ( <a href="qlineedit.html">QLineEdit</a>&nbsp;*&nbsp;edit )<tt> [virtual]</tt>
461</h3>
462Sets the line edit to use <em>edit</em> instead of the current line edit.
463
464<h3 class=fn>void <a name="setListBox"></a>QComboBox::setListBox ( <a href="qlistbox.html">QListBox</a>&nbsp;*&nbsp;newListBox )<tt> [virtual]</tt>
465</h3>
466Sets the combobox to use <em>newListBox</em> instead of the current list
467box or popup. As a side effect, it clears the combobox of its
468current contents.
469<p> <b>Warning:</b> QComboBox assumes that newListBox->text(n) returns
470non-null for 0 &lt;= n &lt; newListbox->count(). This assumption is
471necessary because of the line edit in QComboBox.
472
473<h3 class=fn>void <a name="setMaxCount"></a>QComboBox::setMaxCount ( int )<tt> [virtual]</tt>
474</h3><p>Sets the maximum number of items allowed in the combobox.
475See the <a href="qcombobox.html#maxCount-prop">"maxCount"</a> property for details.
476<h3 class=fn>void <a name="setPalette"></a>QComboBox::setPalette ( const&nbsp;<a href="qpalette.html">QPalette</a>&nbsp;&amp;&nbsp;palette )<tt> [virtual]</tt>
477</h3>
478Sets the palette for both the combobox button and the combobox
479popup list to <em>palette</em>.
480
481<p>Reimplemented from <a href="qwidget.html#setPalette">QWidget</a>.
482<h3 class=fn>void <a name="setSizeLimit"></a>QComboBox::setSizeLimit ( int )<tt> [virtual]</tt>
483</h3><p>Sets the maximum on-screen size of the combobox.
484See the <a href="qcombobox.html#sizeLimit-prop">"sizeLimit"</a> property for details.
485<h3 class=fn>void <a name="setValidator"></a>QComboBox::setValidator ( const&nbsp;<a href="qvalidator.html">QValidator</a>&nbsp;*&nbsp;v )<tt> [virtual]</tt>
486</h3>
487Applies the validator <em>v</em> to the combobox so that only text which
488is valid according to <em>v</em> is accepted.
489<p> This function does nothing if the combobox is not editable.
490<p> <p>See also <a href="#validator">validator</a>(), <a href="#clearValidator">clearValidator</a>(), and <a href="qvalidator.html">QValidator</a>.
491
492<h3 class=fn>int <a name="sizeLimit"></a>QComboBox::sizeLimit () const
493</h3><p>Returns the maximum on-screen size of the combobox.
494See the <a href="qcombobox.html#sizeLimit-prop">"sizeLimit"</a> property for details.
495<h3 class=fn><a href="qstring.html">QString</a> <a name="text"></a>QComboBox::text ( int&nbsp;index ) const
496</h3>
497Returns the text item at position <em>index</em>, or <a href="qstring.html#QString-null">QString::null</a> if
498the item is not a string.
499<p> <p>See also <a href="#currentText-prop">currentText</a>.
500
501<p>Examples: <a href="fileiconview-example.html#x882">fileiconview/mainwindow.cpp</a> and <a href="helpviewer-example.html#x985">helpviewer/helpwindow.cpp</a>.
502<h3 class=fn>void <a name="textChanged"></a>QComboBox::textChanged ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;string )<tt> [signal]</tt>
503</h3>
504
505<p> This signal is used for editable comboboxes. It is emitted
506whenever the contents of the text entry field changes. <em>string</em>
507contains the new text.
508
509<h3 class=fn>const&nbsp;<a href="qvalidator.html">QValidator</a>&nbsp;* <a name="validator"></a>QComboBox::validator () const
510</h3>
511Returns the validator which constrains editing for this combobox
512if there is one; otherwise returns 0.
513<p> <p>See also <a href="#setValidator">setValidator</a>(), <a href="#clearValidator">clearValidator</a>(), and <a href="qvalidator.html">QValidator</a>.
514
515<hr><h2>Property Documentation</h2>
516<h3 class=fn>bool <a name="autoCompletion-prop"></a>autoCompletion</h3>
517<p>This property holds whether auto-completion is enabled.
518<p>This property can only be set for editable comboboxes, for
519non-editable comboboxes it has no effect. It is FALSE by default.
520
521<p>Set this property's value with <a href="#setAutoCompletion">setAutoCompletion</a>() and get this property's value with <a href="#autoCompletion">autoCompletion</a>().
522<h3 class=fn>bool <a name="autoMask-prop"></a>autoMask</h3>
523<p>This property holds whether the combobox is automatically masked.
524<p><p><p>See also <a href="qwidget.html#autoMask-prop">QWidget::autoMask</a>.
525
526<h3 class=fn>bool <a name="autoResize-prop"></a>autoResize</h3> <p>This property holds whether auto resize is enabled.
527<p><b>This property is obsolete.</b> It is provided to keep old source working. We strongly advise against using it in new code.
528<p> If this property is set to TRUE then the combobox will resize itself
529whenever its contents change. The default is FALSE.
530
531<p>Set this property's value with <a href="#setAutoResize">setAutoResize</a>() and get this property's value with <a href="#autoResize">autoResize</a>().
532<h3 class=fn>int <a name="count-prop"></a>count</h3>
533<p>This property holds the number of items in the combobox.
534<p>
535<p>Get this property's value with <a href="#count">count</a>().
536<h3 class=fn>int <a name="currentItem-prop"></a>currentItem</h3>
537<p>This property holds the index of the current item in the combobox.
538<p>Note that the <a href="#activated">activated</a>() and <a href="#highlighted">highlighted</a>() signals are only
539emitted when the user changes the current item, not when it is
540changed programmatically.
541
542<p>Set this property's value with <a href="#setCurrentItem">setCurrentItem</a>() and get this property's value with <a href="#currentItem">currentItem</a>().
543<h3 class=fn><a href="qstring.html">QString</a> <a name="currentText-prop"></a>currentText</h3>
544<p>This property holds the text of the combobox's current item.
545<p>
546<p>Set this property's value with <a href="#setCurrentText">setCurrentText</a>() and get this property's value with <a href="#currentText">currentText</a>().
547<h3 class=fn>bool <a name="duplicatesEnabled-prop"></a>duplicatesEnabled</h3>
548<p>This property holds whether duplicates are allowed.
549<p>If the combobox is editable and the user enters some text in the
550combobox's lineedit and presses Enter (and the <a href="#insertionPolicy">insertionPolicy</a>()
551is not <a href="#Policy-enum">NoInsertion</a>), then what happens is this:
552<ul>
553<li> If the text is not already in the list, the text is inserted.
554<li> If the text is in the list and this property is TRUE (the
555default), the text is inserted.
556<li> If the text is in the list and this property is FALSE, the text
557is <em>not</em> inserted; instead the item which has matching text becomes
558the current item.
559</ul>
560<p> This property only affects user-interaction. You can use
561<a href="#insertItem">insertItem</a>() to insert duplicates if you wish regardless of this
562setting.
563
564<p>Set this property's value with <a href="#setDuplicatesEnabled">setDuplicatesEnabled</a>() and get this property's value with <a href="#duplicatesEnabled">duplicatesEnabled</a>().
565<h3 class=fn>bool <a name="editable-prop"></a>editable</h3>
566<p>This property holds whether the combobox is editable.
567<p>This property's default is FALSE. Note that the combobox will be
568cleared if this property is set to TRUE for a 1.x <a href="motif-extension.html#Motif">Motif</a> style
569combobox. To avoid this, use <a href="#setEditable">setEditable</a>() before inserting any
570items. Also note that the 1.x version of Motif didn't have any
571editable comboboxes, so the combobox will change it's appearance
572to a 2.0 style Motif combobox is it is set to be editable.
573
574<p>Set this property's value with <a href="#setEditable">setEditable</a>() and get this property's value with <a href="#editable">editable</a>().
575<h3 class=fn><a href="qcombobox.html#Policy-enum">Policy</a> <a name="insertionPolicy-prop"></a>insertionPolicy</h3>
576<p>This property holds the position of the items inserted by the user.
577<p>The default insertion policy is <a href="#Policy-enum">AtBottom</a>. See <a href="#Policy-enum">Policy</a>.
578
579<p>Set this property's value with <a href="#setInsertionPolicy">setInsertionPolicy</a>() and get this property's value with <a href="#insertionPolicy">insertionPolicy</a>().
580<h3 class=fn>int <a name="maxCount-prop"></a>maxCount</h3>
581<p>This property holds the maximum number of items allowed in the combobox.
582<p>
583<p>Set this property's value with <a href="#setMaxCount">setMaxCount</a>() and get this property's value with <a href="#maxCount">maxCount</a>().
584<h3 class=fn>int <a name="sizeLimit-prop"></a>sizeLimit</h3>
585<p>This property holds the maximum on-screen size of the combobox.
586<p>This property is ignored for both <a href="motif-extension.html#Motif">Motif</a> 1.x style and non-editable
587comboboxes in Mac style. The default limit is ten
588lines. If the number of items in the combobox is or grows larger
589than lines, a scrollbar is added.
590
591<p>Set this property's value with <a href="#setSizeLimit">setSizeLimit</a>() and get this property's value with <a href="#sizeLimit">sizeLimit</a>().
592<!-- eof -->
593<hr><p>
594This file is part of the <a href="index.html">Qt toolkit</a>.
595Copyright &copy; 1995-2007
596<a href="http://www.trolltech.com/">Trolltech</a>. All Rights Reserved.<p><address><hr><div align=center>
597<table width=100% cellspacing=0 border=0><tr>
598<td>Copyright &copy; 2007
599<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
600<td align=right><div align=right>Qt 3.3.8</div>
601</table></div></address></body>
602</html>
Note: See TracBrowser for help on using the repository browser.