1QComboBox(3qt)                                                  QComboBox(3qt)
2
3
4

NAME

6       QComboBox - Combined button and popup list
7

SYNOPSIS

9       #include <qcombobox.h>
10
11       Inherits QWidget.
12
13   Public Members
14       QComboBox ( QWidget * parent = 0, const char * name = 0 )
15       QComboBox ( bool rw, QWidget * parent = 0, const char * name = 0 )
16       ~QComboBox ()
17       int count () const
18       void insertStringList ( const QStringList & list, int index = -1 )
19       void insertStrList ( const QStrList & list, int index = -1 )
20       void insertStrList ( const QStrList * list, int index = -1 )
21       void insertStrList ( const char ** strings, int numStrings = -1, int
22           index = -1 )
23       void insertItem ( const QString & t, int index = -1 )
24       void insertItem ( const QPixmap & pixmap, int index = -1 )
25       void insertItem ( const QPixmap & pixmap, const QString & text, int
26           index = -1 )
27       void removeItem ( int index )
28       int currentItem () const
29       virtual void setCurrentItem ( int index )
30       QString currentText () const
31       virtual void setCurrentText ( const QString & )
32       QString text ( int index ) const
33       const QPixmap * pixmap ( int index ) const
34       void changeItem ( const QString & t, int index )
35       void changeItem ( const QPixmap & im, int index )
36       void changeItem ( const QPixmap & im, const QString & t, int index )
37       bool autoResize () const  (obsolete)
38       virtual void setAutoResize ( bool )  (obsolete)
39       virtual void setPalette ( const QPalette & palette )
40       virtual void setFont ( const QFont & font )
41       virtual void setSizeLimit ( int )
42       int sizeLimit () const
43       virtual void setMaxCount ( int )
44       int maxCount () const
45       enum Policy { NoInsertion, AtTop, AtCurrent, AtBottom, AfterCurrent,
46           BeforeCurrent }
47       virtual void setInsertionPolicy ( Policy policy )
48       Policy insertionPolicy () const
49       virtual void setValidator ( const QValidator * v )
50       const QValidator * validator () const
51       virtual void setListBox ( QListBox * newListBox )
52       QListBox * listBox () const
53       virtual void setLineEdit ( QLineEdit * edit )
54       QLineEdit * lineEdit () const
55       virtual void setAutoCompletion ( bool )
56       bool autoCompletion () const
57       void setDuplicatesEnabled ( bool enable )
58       bool duplicatesEnabled () const
59       bool editable () const
60       void setEditable ( bool )
61       virtual void popup ()
62
63   Public Slots
64       void clear ()
65       void clearValidator ()
66       void clearEdit ()
67       virtual void setEditText ( const QString & newText )
68
69   Signals
70       void activated ( int index )
71       void highlighted ( int index )
72       void activated ( const QString & string )
73       void highlighted ( const QString & string )
74       void textChanged ( const QString & string )
75
76   Properties
77       bool autoCompletion - whether auto-completion is enabled
78       bool autoMask - whether the combobox is automatically masked  (read
79           only)
80       bool autoResize - whether auto resize is enabled  (obsolete)
81       int count - the number of items in the combobox  (read only)
82       int currentItem - the index of the current item in the combobox
83       QString currentText - the text of the combobox's current item
84       bool duplicatesEnabled - whether duplicates are allowed
85       bool editable - whether the combobox is editable
86       Policy insertionPolicy - the position of the items inserted by the user
87       int maxCount - the maximum number of items allowed in the combobox
88       int sizeLimit - the maximum on-screen size of the combobox
89

DESCRIPTION

91       The QComboBox widget is a combined button and popup list.
92
93       A combobox is a selection widget which displays the current item and
94       can pop up a list of items. A combobox may be editable in which case
95       the user can enter arbitrary strings.
96
97       Comboboxes provide a means of showing the user's current choice out of
98       a list of options in a way that takes up the minimum amount of screen
99       space.
100
101       QComboBox supports three different display styles: Aqua/Motif 1.x,
102       Motif 2.0 and Windows. In Motif 1.x, a combobox was called
103       XmOptionMenu. In Motif 2.0, OSF introduced an improved combobox and
104       named that XmComboBox. QComboBox provides both.
105
106       QComboBox provides two different constructors. The simplest constructor
107       creates an "old-style" combobox in Motif (or Aqua) style:
108
109               QComboBox *c = new QComboBox( this, "read-only combobox" );
110
111       The other constructor creates a new-style combobox in Motif style, and
112       can create both read-only and editable comboboxes:
113
114               QComboBox *c1 = new QComboBox( FALSE, this, "read-only combobox" );
115               QComboBox *c2 = new QComboBox( TRUE, this, "editable combobox" );
116
117       New-style comboboxes use a list box in both Motif and Windows styles,
118       and both the content size and the on-screen size of the list box can be
119       limited with sizeLimit() and setMaxCount() respectively. Old-style
120       comboboxes use a popup in Aqua and Motif style, and that popup will
121       happily grow larger than the desktop if you put enough data into it.
122
123       The two constructors create identical-looking comboboxes in Windows
124       style.
125
126       Comboboxes can contain pixmaps as well as strings; the insertItem() and
127       changeItem() functions are suitably overloaded. For editable
128       comboboxes, the function clearEdit() is provided, to clear the
129       displayed string without changing the combobox's contents.
130
131       A combobox emits two signals, activated() and highlighted(), when a new
132       item has been activated (selected) or highlighted (made current). Both
133       signals exist in two versions, one with a QString argument and one with
134       an int argument. If the user highlights or activates a pixmap, only the
135       int signals are emitted. Whenever the text of an editable combobox is
136       changed the textChanged() signal is emitted.
137
138       When the user enters a new string in an editable combobox, the widget
139       may or may not insert it, and it can insert it in several locations.
140       The default policy is is AtBottom but you can change this using
141       setInsertionPolicy().
142
143       It is possible to constrain the input to an editable combobox using
144       QValidator; see setValidator(). By default, any input is accepted.
145
146       If the combobox is not editable then it has a default focusPolicy() of
147       TabFocus, i.e. it will not grab focus if clicked. This differs from
148       both Windows and Motif. If the combobox is editable then it has a
149       default focusPolicy() of StrongFocus, i.e. it will grab focus if
150       clicked.
151
152       A combobox can be populated using the insert functions,
153       insertStringList() and insertItem() for example. Items can be changed
154       with changeItem(). An item can be removed with removeItem() and all
155       items can be removed with clear(). The text of the current item is
156       returned by currentText(), and the text of a numbered item is returned
157       with text(). The current item can be set with setCurrentItem() or
158       setCurrentText(). The number of items in the combobox is returned by
159       count(); the maximum number of items can be set with setMaxCount(). You
160       can allow editing using setEditable(). For editable comboboxes you can
161       set auto-completion using setAutoCompletion() and whether or not the
162       user can add duplicates is set with setDuplicatesEnabled().
163
164                                   [Image Omitted]
165
166       (Motif 1, read-only)
167                                   [Image Omitted]
168
169       (Motif 2, editable)
170                                   [Image Omitted]
171
172       (Motif 2, read-only)
173                                   [Image Omitted]
174
175       (Windows style)
176
177       Depending on the style, QComboBox will use a QListBox or a QPopupMenu
178       to display the list of items. See setListBox() for more information.
179
180       See also QLineEdit, QListBox, QSpinBox, QRadioButton, QButtonGroup, GUI
181       Design Handbook: Combo Box, GUI Design Handbook: Drop-Down List Box,
182       and Basic Widgets.
183
184   Member Type Documentation

QComboBox::Policy

186       This enum specifies what the QComboBox should do when a new string is
187       entered by the user.
188
189       QComboBox::NoInsertion - the string will not be inserted into the
190       combobox.
191
192       QComboBox::AtTop - insert the string as the first item in the combobox.
193
194       QComboBox::AtCurrent - replace the previously selected item with the
195       string the user has entered.
196
197       QComboBox::AtBottom - insert the string as the last item in the
198       combobox.
199
200       QComboBox::AfterCurrent - insert the string after the previously
201       selected item.
202
203       QComboBox::BeforeCurrent - insert the string before the previously
204       selected item.
205
206       activated() is always emitted when the string is entered.
207
208       If inserting the new string would cause the combobox to breach its
209       content size limit, the item at the other end of the list is deleted.
210       The definition of "other end" is implementation-dependent.
211

MEMBER FUNCTION DOCUMENTATION

QComboBox::QComboBox ( QWidget * parent = 0, const char * name = 0 )

214       Constructs a combobox widget with parent parent called name.
215
216       This constructor creates a popup list if the program uses Motif (or
217       Aqua) look and feel; this is compatible with Motif 1.x and Aqua.
218
219       Note: If you use this constructor to create your QComboBox, then the
220       pixmap() function will always return 0. To workaround this, use the
221       other constructor.
222

QComboBox::QComboBox ( bool rw, QWidget * parent = 0, const char * name = 0 )

224       Constructs a combobox with a maximum size and either Motif 2.0 or
225       Windows look and feel.
226
227       The input field can be edited if rw is TRUE, otherwise the user may
228       only choose one of the items in the combobox.
229
230       The parent and name arguments are passed on to the QWidget constructor.
231

QComboBox::~QComboBox ()

233       Destroys the combobox.
234

void QComboBox::activated ( int index ) [signal]

236       This signal is emitted when a new item has been activated (selected).
237       The index is the position of the item in the combobox.
238
239       This signal is not emitted if the item is changed programmatically,
240       e.g. using setCurrentItem().
241
242       Examples:
243

void QComboBox::activated ( const QString & string ) [signal]

245       This is an overloaded member function, provided for convenience. It
246       behaves essentially like the above function.
247
248       This signal is emitted when a new item has been activated (selected).
249       string is the selected string.
250
251       You can also use the activated(int) signal, but be aware that its
252       argument is meaningful only for selected strings, not for user entered
253       strings.
254

bool QComboBox::autoCompletion () const

256       Returns TRUE if auto-completion is enabled; otherwise returns FALSE.
257       See the "autoCompletion" property for details.
258

bool QComboBox::autoResize () const

260       Returns TRUE if auto resize is enabled; otherwise returns FALSE. See
261       the "autoResize" property for details.
262

void QComboBox::changeItem ( const QString & t, int index )

264       Replaces the item at position index with the text t.
265

void QComboBox::changeItem ( const QPixmap & im, int index )

267       This is an overloaded member function, provided for convenience. It
268       behaves essentially like the above function.
269
270       Replaces the item at position index with the pixmap im, unless the
271       combobox is editable.
272
273       See also insertItem().
274

void QComboBox::changeItem ( const QPixmap & im, const QString & t, int index

276       )
277       This is an overloaded member function, provided for convenience. It
278       behaves essentially like the above function.
279
280       Replaces the item at position index with the pixmap im and the text t.
281
282       See also insertItem().
283

void QComboBox::clear () [slot]

285       Removes all combobox items.
286

void QComboBox::clearEdit () [slot]

288       Clears the line edit without changing the combobox's contents. Does
289       nothing if the combobox isn't editable.
290
291       This is particularly useful when using a combobox as a line edit with
292       history. For example you can connect the combobox's activated() signal
293       to clearEdit() in order to present the user with a new, empty line as
294       soon as Enter is pressed.
295
296       See also setEditText().
297

void QComboBox::clearValidator () [slot]

299       This slot is equivalent to setValidator( 0 ).
300

int QComboBox::count () const

302       Returns the number of items in the combobox. See the "count" property
303       for details.
304

int QComboBox::currentItem () const

306       Returns the index of the current item in the combobox. See the
307       "currentItem" property for details.
308

QString QComboBox::currentText () const

310       Returns the text of the combobox's current item. See the "currentText"
311       property for details.
312

bool QComboBox::duplicatesEnabled () const

314       Returns TRUE if duplicates are allowed; otherwise returns FALSE. See
315       the "duplicatesEnabled" property for details.
316

bool QComboBox::editable () const

318       Returns TRUE if the combobox is editable; otherwise returns FALSE. See
319       the "editable" property for details.
320

void QComboBox::highlighted ( int index ) [signal]

322       This signal is emitted when a new item has been set to be the current
323       item. The index is the position of the item in the combobox.
324
325       This signal is not emitted if the item is changed programmatically,
326       e.g. using setCurrentItem().
327

void QComboBox::highlighted ( const QString & string ) [signal]

329       This is an overloaded member function, provided for convenience. It
330       behaves essentially like the above function.
331
332       This signal is emitted when a new item has been set to be the current
333       item. string is the item's text.
334
335       You can also use the highlighted(int) signal.
336

void QComboBox::insertItem ( const QString & t, int index = -1 )

338       Inserts a text item with text t, at position index. The item will be
339       appended if index is negative.
340
341       Examples:
342

void QComboBox::insertItem ( const QPixmap & pixmap, int index = -1 )

344       This is an overloaded member function, provided for convenience. It
345       behaves essentially like the above function.
346
347       Inserts a pixmap item at position index. The item will be appended if
348       index is negative.
349

void QComboBox::insertItem ( const QPixmap & pixmap, const QString & text, int

351       index = -1 )
352       This is an overloaded member function, provided for convenience. It
353       behaves essentially like the above function.
354
355       Inserts a pixmap item with additional text text at position index. The
356       item will be appended if index is negative.
357

void QComboBox::insertStrList ( const char ** strings, int numStrings = -1,

359       int index = -1 )
360       Inserts the array of char * strings at position index in the combobox.
361
362       The numStrings argument is the number of strings. If numStrings is -1
363       (default), the strings array must be terminated with 0.
364
365       Example:
366
367               static const char* items[] = { "red", "green", "blue", 0 };
368               combo->insertStrList( items );
369
370       See also insertStringList().
371
372       Example: qmag/qmag.cpp.
373

void QComboBox::insertStrList ( const QStrList & list, int index = -1 )

375       This is an overloaded member function, provided for convenience. It
376       behaves essentially like the above function.
377
378       Inserts the list of strings at position index in the combobox.
379
380       This is only for compatibility since it does not support Unicode
381       strings. See insertStringList().
382

void QComboBox::insertStrList ( const QStrList * list, int index = -1 )

384       This is an overloaded member function, provided for convenience. It
385       behaves essentially like the above function.
386
387       Inserts the list of strings at position index in the combobox.
388
389       This is only for compatibility since it does not support Unicode
390       strings. See insertStringList().
391

void QComboBox::insertStringList ( const QStringList & list, int index = -1 )

393       Inserts the list of strings at position index in the combobox.
394

Policy QComboBox::insertionPolicy () const

396       Returns the position of the items inserted by the user. See the
397       "insertionPolicy" property for details.
398

QLineEdit * QComboBox::lineEdit () const

400       Returns the line edit, or 0 if there is no line edit.
401
402       Only editable listboxes have a line editor.
403

QListBox * QComboBox::listBox () const

405       Returns the current list box, or 0 if there is no list box. (QComboBox
406       can use QPopupMenu instead of QListBox.) Provided to match
407       setListBox().
408
409       See also setListBox().
410
411       Example: listboxcombo/listboxcombo.cpp.
412

int QComboBox::maxCount () const

414       Returns the maximum number of items allowed in the combobox. See the
415       "maxCount" property for details.
416

const QPixmap * QComboBox::pixmap ( int index ) const

418       Returns the pixmap item at position index, or 0 if the item is not a
419       pixmap.
420

void QComboBox::popup () [virtual]

422       Pops up the combobox popup list.
423
424       If the list is empty, no items appear.
425

void QComboBox::removeItem ( int index )

427       Removes the item at position index.
428

void QComboBox::setAutoCompletion ( bool ) [virtual]

430       Sets whether auto-completion is enabled. See the "autoCompletion"
431       property for details.
432

void QComboBox::setAutoResize ( bool ) [virtual]

434       Sets whether auto resize is enabled. See the "autoResize" property for
435       details.
436

void QComboBox::setCurrentItem ( int index ) [virtual]

438       Sets the index of the current item in the combobox to index. See the
439       "currentItem" property for details.
440

void QComboBox::setCurrentText ( const QString & ) [virtual]

442       Sets the text of the combobox's current item. See the "currentText"
443       property for details.
444

void QComboBox::setDuplicatesEnabled ( bool enable )

446       Sets whether duplicates are allowed to enable. See the
447       "duplicatesEnabled" property for details.
448

void QComboBox::setEditText ( const QString & newText ) [virtual slot]

450       Sets the text in the line edit to newText without changing the
451       combobox's contents. Does nothing if the combobox isn't editable.
452
453       This is useful e.g. for providing a good starting point for the user's
454       editing and entering the change in the combobox only when the user
455       presses Enter.
456
457       See also clearEdit() and insertItem().
458

void QComboBox::setEditable ( bool )

460       Sets whether the combobox is editable. See the "editable" property for
461       details.
462

void QComboBox::setFont ( const QFont & font ) [virtual]

464       Sets the font for both the combobox button and the combobox popup list
465       to font.
466
467       Reimplemented from QWidget.
468

void QComboBox::setInsertionPolicy ( Policy policy ) [virtual]

470       Sets the position of the items inserted by the user to policy. See the
471       "insertionPolicy" property for details.
472

void QComboBox::setLineEdit ( QLineEdit * edit ) [virtual]

474       Sets the line edit to use edit instead of the current line edit.
475

void QComboBox::setListBox ( QListBox * newListBox ) [virtual]

477       Sets the combobox to use newListBox instead of the current list box or
478       popup. As a side effect, it clears the combobox of its current
479       contents.
480
481       Warning: QComboBox assumes that newListBox->text(n) returns non-null
482       for 0 <= n < newListbox->count(). This assumption is necessary because
483       of the line edit in QComboBox.
484

void QComboBox::setMaxCount ( int ) [virtual]

486       Sets the maximum number of items allowed in the combobox. See the
487       "maxCount" property for details.
488

void QComboBox::setPalette ( const QPalette & palette ) [virtual]

490       Sets the palette for both the combobox button and the combobox popup
491       list to palette.
492
493       Reimplemented from QWidget.
494

void QComboBox::setSizeLimit ( int ) [virtual]

496       Sets the maximum on-screen size of the combobox. See the "sizeLimit"
497       property for details.
498

void QComboBox::setValidator ( const QValidator * v ) [virtual]

500       Applies the validator v to the combobox so that only text which is
501       valid according to v is accepted.
502
503       This function does nothing if the combobox is not editable.
504
505       See also validator(), clearValidator(), and QValidator.
506

int QComboBox::sizeLimit () const

508       Returns the maximum on-screen size of the combobox. See the "sizeLimit"
509       property for details.
510

QString QComboBox::text ( int index ) const

512       Returns the text item at position index, or QString::null if the item
513       is not a string.
514
515       See also currentText.
516
517       Examples:
518

void QComboBox::textChanged ( const QString & string ) [signal]

520       This signal is used for editable comboboxes. It is emitted whenever the
521       contents of the text entry field changes. string contains the new text.
522

const QValidator * QComboBox::validator () const

524       Returns the validator which constrains editing for this combobox if
525       there is one; otherwise returns 0.
526
527       See also setValidator(), clearValidator(), and QValidator.
528
529   Property Documentation

bool autoCompletion

531       This property holds whether auto-completion is enabled.
532
533       This property can only be set for editable comboboxes, for non-editable
534       comboboxes it has no effect. It is FALSE by default.
535
536       Set this property's value with setAutoCompletion() and get this
537       property's value with autoCompletion().
538

bool autoMask

540       This property holds whether the combobox is automatically masked.
541
542       See also QWidget::autoMask.
543

bool autoResize

545       This property holds whether auto resize is enabled.
546
547       This property is obsolete. It is provided to keep old source working.
548       We strongly advise against using it in new code.
549
550       If this property is set to TRUE then the combobox will resize itself
551       whenever its contents change. The default is FALSE.
552
553       Set this property's value with setAutoResize() and get this property's
554       value with autoResize().
555

int count

557       This property holds the number of items in the combobox.
558
559       Get this property's value with count().
560

int currentItem

562       This property holds the index of the current item in the combobox.
563
564       Note that the activated() and highlighted() signals are only emitted
565       when the user changes the current item, not when it is changed
566       programmatically.
567
568       Set this property's value with setCurrentItem() and get this property's
569       value with currentItem().
570

QString currentText

572       This property holds the text of the combobox's current item.
573
574       Set this property's value with setCurrentText() and get this property's
575       value with currentText().
576

bool duplicatesEnabled

578       This property holds whether duplicates are allowed.
579
580       If the combobox is editable and the user enters some text in the
581       combobox's lineedit and presses Enter (and the insertionPolicy() is not
582       NoInsertion), then what happens is this:
583
584       If the text is not already in the list, the text is inserted.
585
586       If the text is in the list and this property is TRUE (the default), the
587       text is inserted.
588
589       If the text is in the list and this property is FALSE, the text is not
590       inserted; instead the item which has matching text becomes the current
591       item.
592
593       This property only affects user-interaction. You can use insertItem()
594       to insert duplicates if you wish regardless of this setting.
595
596       Set this property's value with setDuplicatesEnabled() and get this
597       property's value with duplicatesEnabled().
598

bool editable

600       This property holds whether the combobox is editable.
601
602       This property's default is FALSE. Note that the combobox will be
603       cleared if this property is set to TRUE for a 1.x Motif style combobox.
604       To avoid this, use setEditable() before inserting any items. Also note
605       that the 1.x version of Motif didn't have any editable comboboxes, so
606       the combobox will change it's appearance to a 2.0 style Motif combobox
607       is it is set to be editable.
608
609       Set this property's value with setEditable() and get this property's
610       value with editable().
611

Policy insertionPolicy

613       This property holds the position of the items inserted by the user.
614
615       The default insertion policy is AtBottom. See Policy.
616
617       Set this property's value with setInsertionPolicy() and get this
618       property's value with insertionPolicy().
619

int maxCount

621       This property holds the maximum number of items allowed in the
622       combobox.
623
624       Set this property's value with setMaxCount() and get this property's
625       value with maxCount().
626

int sizeLimit

628       This property holds the maximum on-screen size of the combobox.
629
630       This property is ignored for both Motif 1.x style and non-editable
631       comboboxes in Mac style. The default limit is ten lines. If the number
632       of items in the combobox is or grows larger than lines, a scrollbar is
633       added.
634
635       Set this property's value with setSizeLimit() and get this property's
636       value with sizeLimit().
637
638

SEE ALSO

640       http://doc.trolltech.com/qcombobox.html
641       http://www.trolltech.com/faq/tech.html
642
644       Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com.  See the
645       license file included in the distribution for a complete license
646       statement.
647

AUTHOR

649       Generated automatically from the source code.
650

BUGS

652       If you find a bug in Qt, please report it as described in
653       http://doc.trolltech.com/bughowto.html.  Good bug reports help us to
654       help you. Thank you.
655
656       The definitive Qt documentation is provided in HTML format; it is
657       located at $QTDIR/doc/html and can be read using Qt Assistant or with a
658       web browser. This man page is provided as a convenience for those users
659       who prefer man pages, although this format is not officially supported
660       by Trolltech.
661
662       If you find errors in this manual page, please report them to qt-
663       bugs@trolltech.com.  Please include the name of the manual page
664       (qcombobox.3qt) and the Qt version (3.3.8).
665
666
667
668Trolltech AS                    2 February 2007                 QComboBox(3qt)
Impressum