1QComboBox(3qt) QComboBox(3qt)
2
6 QComboBox - Combined button and popup list
7
9 #include <qcombobox.h>
10 Inherits QWidget.
12 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 Public Slots
64 void clear ()
65 void clearValidator ()
66 void clearEdit ()
67 virtual void setEditText ( const QString & newText )
68 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 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
91 The QComboBox widget is a combined button and popup list.
92 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 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 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 QComboBox provides two different constructors. The simplest constructor
107 creates an "old-style" combobox in Motif (or Aqua) style:
108 QComboBox *c = new QComboBox( this, "read-only combobox" );
110 The other constructor creates a new-style combobox in Motif style, and
112 can create both read-only and editable comboboxes:
113 QComboBox *c1 = new QComboBox( FALSE, this, "read-only combobox" );
115 QComboBox *c2 = new QComboBox( TRUE, this, "editable combobox" );
116 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 The two constructors create identical-looking comboboxes in Windows
124 style.
125 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 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 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 It is possible to constrain the input to an editable combobox using
144 QValidator; see setValidator(). By default, any input is accepted.
145 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 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 [Image Omitted]
165 (Motif 1, read-only)
167 [Image Omitted]
168 (Motif 2, editable)
170 [Image Omitted]
171 (Motif 2, read-only)
173 [Image Omitted]
174 (Windows style)
176 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 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 Member Type Documentation
186 This enum specifies what the QComboBox should do when a new string is
187 entered by the user.
188 QComboBox::NoInsertion - the string will not be inserted into the
190 combobox.
191 QComboBox::AtTop - insert the string as the first item in the combobox.
193 QComboBox::AtCurrent - replace the previously selected item with the
195 string the user has entered.
196 QComboBox::AtBottom - insert the string as the last item in the
198 combobox.
199 QComboBox::AfterCurrent - insert the string after the previously
201 selected item.
202 QComboBox::BeforeCurrent - insert the string before the previously
204 selected item.
205 activated() is always emitted when the string is entered.
207 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
214 Constructs a combobox widget with parent parent called name.
215 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 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
224 Constructs a combobox with a maximum size and either Motif 2.0 or
225 Windows look and feel.
226 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 The parent and name arguments are passed on to the QWidget constructor.
231
233 Destroys the combobox.
234
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 This signal is not emitted if the item is changed programmatically,
240 e.g. using setCurrentItem().
241 Examples:
243
245 This is an overloaded member function, provided for convenience. It
246 behaves essentially like the above function.
247 This signal is emitted when a new item has been activated (selected).
249 string is the selected string.
250 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
256 Returns TRUE if auto-completion is enabled; otherwise returns FALSE.
257 See the "autoCompletion" property for details.
258
260 Returns TRUE if auto resize is enabled; otherwise returns FALSE. See
261 the "autoResize" property for details.
262
264 Replaces the item at position index with the text t.
265
267 This is an overloaded member function, provided for convenience. It
268 behaves essentially like the above function.
269 Replaces the item at position index with the pixmap im, unless the
271 combobox is editable.
272 See also insertItem().
274
276 )
277 This is an overloaded member function, provided for convenience. It
278 behaves essentially like the above function.
279 Replaces the item at position index with the pixmap im and the text t.
281 See also insertItem().
283
285 Removes all combobox items.
286
288 Clears the line edit without changing the combobox's contents. Does
289 nothing if the combobox isn't editable.
290 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 See also setEditText().
297
299 This slot is equivalent to setValidator( 0 ).
300
302 Returns the number of items in the combobox. See the "count" property
303 for details.
304
306 Returns the index of the current item in the combobox. See the
307 "currentItem" property for details.
308
310 Returns the text of the combobox's current item. See the "currentText"
311 property for details.
312
314 Returns TRUE if duplicates are allowed; otherwise returns FALSE. See
315 the "duplicatesEnabled" property for details.
316
318 Returns TRUE if the combobox is editable; otherwise returns FALSE. See
319 the "editable" property for details.
320
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 This signal is not emitted if the item is changed programmatically,
326 e.g. using setCurrentItem().
327
329 This is an overloaded member function, provided for convenience. It
330 behaves essentially like the above function.
331 This signal is emitted when a new item has been set to be the current
333 item. string is the item's text.
334 You can also use the highlighted(int) signal.
336
338 Inserts a text item with text t, at position index. The item will be
339 appended if index is negative.
340 Examples:
342
344 This is an overloaded member function, provided for convenience. It
345 behaves essentially like the above function.
346 Inserts a pixmap item at position index. The item will be appended if
348 index is negative.
349
351 index = -1 )
352 This is an overloaded member function, provided for convenience. It
353 behaves essentially like the above function.
354 Inserts a pixmap item with additional text text at position index. The
356 item will be appended if index is negative.
357
359 int index = -1 )
360 Inserts the array of char * strings at position index in the combobox.
361 The numStrings argument is the number of strings. If numStrings is -1
363 (default), the strings array must be terminated with 0.
364 Example:
366 static const char* items[] = { "red", "green", "blue", 0 };
368 combo->insertStrList( items );
369 See also insertStringList().
371 Example: qmag/qmag.cpp.
373
375 This is an overloaded member function, provided for convenience. It
376 behaves essentially like the above function.
377 Inserts the list of strings at position index in the combobox.
379 This is only for compatibility since it does not support Unicode
381 strings. See insertStringList().
382
384 This is an overloaded member function, provided for convenience. It
385 behaves essentially like the above function.
386 Inserts the list of strings at position index in the combobox.
388 This is only for compatibility since it does not support Unicode
390 strings. See insertStringList().
391
393 Inserts the list of strings at position index in the combobox.
394
396 Returns the position of the items inserted by the user. See the
397 "insertionPolicy" property for details.
398
400 Returns the line edit, or 0 if there is no line edit.
401 Only editable listboxes have a line editor.
403
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 See also setListBox().
410 Example: listboxcombo/listboxcombo.cpp.
412
414 Returns the maximum number of items allowed in the combobox. See the
415 "maxCount" property for details.
416
418 Returns the pixmap item at position index, or 0 if the item is not a
419 pixmap.
420
422 Pops up the combobox popup list.
423 If the list is empty, no items appear.
425
427 Removes the item at position index.
428
430 Sets whether auto-completion is enabled. See the "autoCompletion"
431 property for details.
432
434 Sets whether auto resize is enabled. See the "autoResize" property for
435 details.
436
438 Sets the index of the current item in the combobox to index. See the
439 "currentItem" property for details.
440
442 Sets the text of the combobox's current item. See the "currentText"
443 property for details.
444
446 Sets whether duplicates are allowed to enable. See the
447 "duplicatesEnabled" property for details.
448
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 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 See also clearEdit() and insertItem().
458
460 Sets whether the combobox is editable. See the "editable" property for
461 details.
462
464 Sets the font for both the combobox button and the combobox popup list
465 to font.
466 Reimplemented from QWidget.
468
470 Sets the position of the items inserted by the user to policy. See the
471 "insertionPolicy" property for details.
472
474 Sets the line edit to use edit instead of the current line edit.
475
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 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
486 Sets the maximum number of items allowed in the combobox. See the
487 "maxCount" property for details.
488
490 Sets the palette for both the combobox button and the combobox popup
491 list to palette.
492 Reimplemented from QWidget.
494
496 Sets the maximum on-screen size of the combobox. See the "sizeLimit"
497 property for details.
498
500 Applies the validator v to the combobox so that only text which is
501 valid according to v is accepted.
502 This function does nothing if the combobox is not editable.
504 See also validator(), clearValidator(), and QValidator.
506
508 Returns the maximum on-screen size of the combobox. See the "sizeLimit"
509 property for details.
510
512 Returns the text item at position index, or QString::null if the item
513 is not a string.
514 See also currentText.
516 Examples:
518
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
524 Returns the validator which constrains editing for this combobox if
525 there is one; otherwise returns 0.
526 See also setValidator(), clearValidator(), and QValidator.
528 Property Documentation
531 This property holds whether auto-completion is enabled.
532 This property can only be set for editable comboboxes, for non-editable
534 comboboxes it has no effect. It is FALSE by default.
535 Set this property's value with setAutoCompletion() and get this
537 property's value with autoCompletion().
538
540 This property holds whether the combobox is automatically masked.
541 See also QWidget::autoMask.
543
545 This property holds whether auto resize is enabled.
546 This property is obsolete. It is provided to keep old source working.
548 We strongly advise against using it in new code.
549 If this property is set to TRUE then the combobox will resize itself
551 whenever its contents change. The default is FALSE.
552 Set this property's value with setAutoResize() and get this property's
554 value with autoResize().
555
557 This property holds the number of items in the combobox.
558 Get this property's value with count().
560
562 This property holds the index of the current item in the combobox.
563 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 Set this property's value with setCurrentItem() and get this property's
569 value with currentItem().
570
572 This property holds the text of the combobox's current item.
573 Set this property's value with setCurrentText() and get this property's
575 value with currentText().
576
578 This property holds whether duplicates are allowed.
579 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 If the text is not already in the list, the text is inserted.
585 If the text is in the list and this property is TRUE (the default), the
587 text is inserted.
588 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 This property only affects user-interaction. You can use insertItem()
594 to insert duplicates if you wish regardless of this setting.
595 Set this property's value with setDuplicatesEnabled() and get this
597 property's value with duplicatesEnabled().
598
600 This property holds whether the combobox is editable.
601 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 Set this property's value with setEditable() and get this property's
610 value with editable().
611
613 This property holds the position of the items inserted by the user.
614 The default insertion policy is AtBottom. See Policy.
616 Set this property's value with setInsertionPolicy() and get this
618 property's value with insertionPolicy().
619
621 This property holds the maximum number of items allowed in the
622 combobox.
623 Set this property's value with setMaxCount() and get this property's
625 value with maxCount().
626
628 This property holds the maximum on-screen size of the combobox.
629 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 Set this property's value with setSizeLimit() and get this property's
636 value with sizeLimit().
637
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
649 Generated automatically from the source code.
650
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 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 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).
665Trolltech AS 2 February 2007 QComboBox(3qt)