QComboBox¶
The QComboBox widget is a combined button and popup list. More…

Inherited by: QFontComboBox
Synopsis¶
Functions¶
def
activated
(index)def
addItem
(icon, text[, userData=None])def
addItem
(text[, userData=None])def
addItems
(texts)def
clear
()def
clearEditText
()def
completer
()def
count
()def
currentData
([role=Qt.UserRole])def
currentIndex
()def
currentIndexChanged
(index)def
currentText
()def
currentTextChanged
(arg__1)def
duplicatesEnabled
()def
editTextChanged
(arg__1)def
findData
(data[, role=Qt.UserRole[, flags=static_cast<Qt.MatchFlags>(Qt.MatchExactly|Qt.MatchCaseSensitive)]])def
findText
(text[, flags=static_cast<Qt.MatchFlags>(Qt.MatchExactly|Qt.MatchCaseSensitive)])def
hasFrame
()def
highlighted
(index)def
iconSize
()def
inputMethodQuery
(query, argument)def
insertItem
(index, icon, text[, userData=None])def
insertItem
(index, text[, userData=None])def
insertItems
(index, texts)def
insertPolicy
()def
insertSeparator
(index)def
isEditable
()def
itemData
(index[, role=Qt.UserRole])def
itemDelegate
()def
itemIcon
(index)def
itemText
(index)def
lineEdit
()def
maxCount
()def
maxVisibleItems
()def
minimumContentsLength
()def
model
()def
modelColumn
()def
placeholderText
()def
removeItem
(index)def
rootModelIndex
()def
setCompleter
(c)def
setCurrentIndex
(index)def
setCurrentText
(text)def
setDuplicatesEnabled
(enable)def
setEditText
(text)def
setEditable
(editable)def
setFrame
(arg__1)def
setIconSize
(size)def
setInsertPolicy
(policy)def
setItemData
(index, value[, role=Qt.UserRole])def
setItemDelegate
(delegate)def
setItemIcon
(index, icon)def
setItemText
(index, text)def
setLineEdit
(edit)def
setMaxCount
(max)def
setMaxVisibleItems
(maxItems)def
setMinimumContentsLength
(characters)def
setModelColumn
(visibleColumn)def
setPlaceholderText
(placeholderText)def
setRootModelIndex
(index)def
setSizeAdjustPolicy
(policy)def
setValidator
(v)def
setView
(itemView)def
sizeAdjustPolicy
()def
textActivated
(arg__1)def
textHighlighted
(arg__1)def
validator
()def
view
()
Virtual functions¶
def
hidePopup
()def
initStyleOption
(option)def
setModel
(model)def
showPopup
()
Detailed Description¶
A QComboBox provides a means of presenting a list of options to the user in a way that takes up the minimum amount of screen space.
A combobox is a selection widget that displays the current item, and can pop up a list of selectable items. A combobox may be editable, allowing the user to modify each item in the list.
Comboboxes can contain pixmaps as well as strings; the insertItem()
and setItemText()
functions are suitably overloaded. For editable comboboxes, the function clearEditText()
is provided, to clear the displayed string without changing the combobox’s contents.
There are three signals emitted if the current item of a combobox changes, currentIndexChanged()
, currentTextChanged()
and . currentIndexChanged()
and currentTextChanged()
are always emitted regardless if the change was done programmatically or by user interaction, while is only emitted when the change is caused by user interaction. The signal is emitted when the user highlights an item in the combobox popup list. All three signals exist in two versions, one with a QString
argument and one with an int
argument. If the user selects or highlights a pixmap, only the int
signals are emitted. Whenever the text of an editable combobox is changed the signal is emitted.
When the user enters a new string in an editable combobox, the widget may or may not insert it, and it can insert it in several locations. The default policy is InsertAtBottom
but you can change this using setInsertPolicy()
.
It is possible to constrain the input to an editable combobox using QValidator
; see . By default, any input is accepted.
A combobox can be populated using the insert functions, insertItem()
and insertItems()
for example. Items can be changed with setItemText()
. An item can be removed with removeItem()
and all items can be removed with clear()
. The text of the current item is returned by currentText()
, and the text of a numbered item is returned with text(). The current item can be set with setCurrentIndex()
. The number of items in the combobox is returned by count()
; the maximum number of items can be set with setMaxCount()
. You can allow editing using . For editable comboboxes you can set auto-completion using and whether or not the user can add duplicates is set with setDuplicatesEnabled()
.
QComboBox uses the model/view framework for its popup list and to store its items. By default a QStandardItemModel
stores the items and a QListView
subclass displays the popuplist. You can access the model and view directly (with model()
and view()
), but QComboBox also provides functions to set and get item data (e.g., setItemData()
and itemText()
). You can also set a new model and view (with setModel()
and setView()
). For the text and icon in the combobox label, the data in the model that has the DisplayRole
and DecorationRole
is used. Note that you cannot alter the SelectionMode
of the view()
, e.g., by using setSelectionMode()
.
-
class
PySide6.QtWidgets.
QComboBox
([parent=None])¶ - Parameters
parent –
PySide6.QtWidgets.QWidget
Constructs a combobox with the given parent
, using the default model QStandardItemModel
.
-
PySide6.QtWidgets.QComboBox.
InsertPolicy
¶
This enum specifies what the QComboBox should do when a new string is entered by the user.
Constant
Description
QComboBox.NoInsert
The string will not be inserted into the combobox.
QComboBox.InsertAtTop
The string will be inserted as the first item in the combobox.
QComboBox.InsertAtCurrent
The current item will be replaced by the string.
QComboBox.InsertAtBottom
The string will be inserted after the last item in the combobox.
QComboBox.InsertAfterCurrent
The string is inserted after the current item in the combobox.
QComboBox.InsertBeforeCurrent
The string is inserted before the current item in the combobox.
QComboBox.InsertAlphabetically
The string is inserted in the alphabetic order in the combobox.
-
PySide6.QtWidgets.QComboBox.
SizeAdjustPolicy
¶
This enum specifies how the size hint of the QComboBox should adjust when new content is added or content changes.
Constant
Description
QComboBox.AdjustToContents
The combobox will always adjust to the contents
QComboBox.AdjustToContentsOnFirstShow
The combobox will adjust to its contents the first time it is shown.
QComboBox.AdjustToMinimumContentsLengthWithIcon
The combobox will adjust to
minimumContentsLength
plus space for an icon. For performance reasons use this policy on large models.
-
PySide6.QtWidgets.QComboBox.
activated
(index)¶ - Parameters
index – int
-
PySide6.QtWidgets.QComboBox.
addItem
(icon, text[, userData=None])¶ - Parameters
icon –
PySide6.QtGui.QIcon
text – str
userData – object
-
PySide6.QtWidgets.QComboBox.
addItem
(text[, userData=None]) - Parameters
text – str
userData – object
-
PySide6.QtWidgets.QComboBox.
addItems
(texts)¶ - Parameters
texts – list of strings
-
PySide6.QtWidgets.QComboBox.
clear
()¶
Clears the combobox, removing all items.
Note: If you have set an external model on the combobox this model will still be cleared when calling this function.
-
PySide6.QtWidgets.QComboBox.
clearEditText
()¶
Clears the contents of the line edit used for editing in the combobox.
-
PySide6.QtWidgets.QComboBox.
completer
()¶ - Return type
Returns the completer that is used to auto complete text input for the combobox.
See also
editable
-
PySide6.QtWidgets.QComboBox.
count
()¶ - Return type
int
-
PySide6.QtWidgets.QComboBox.
currentData
([role=Qt.UserRole])¶ - Parameters
role – int
- Return type
object
-
PySide6.QtWidgets.QComboBox.
currentIndex
()¶ - Return type
int
See also
-
PySide6.QtWidgets.QComboBox.
currentIndexChanged
(index)¶ - Parameters
index – int
-
PySide6.QtWidgets.QComboBox.
currentText
()¶ - Return type
str
See also
-
PySide6.QtWidgets.QComboBox.
currentTextChanged
(arg__1)¶ - Parameters
arg__1 – str
-
PySide6.QtWidgets.QComboBox.
duplicatesEnabled
()¶ - Return type
bool
See also
-
PySide6.QtWidgets.QComboBox.
editTextChanged
(arg__1)¶ - Parameters
arg__1 – str
-
PySide6.QtWidgets.QComboBox.
findData
(data[, role=Qt.UserRole[, flags=static_cast<Qt.MatchFlags>(Qt.MatchExactly|Qt.MatchCaseSensitive)]])¶ - Parameters
data – object
role – int
flags –
MatchFlags
- Return type
int
Returns the index of the item containing the given data
for the given role
; otherwise returns -1.
The flags
specify how the items in the combobox are searched.
-
PySide6.QtWidgets.QComboBox.
findText
(text[, flags=static_cast<Qt.MatchFlags>(Qt.MatchExactly|Qt.MatchCaseSensitive)])¶ - Parameters
text – str
flags –
MatchFlags
- Return type
int
-
PySide6.QtWidgets.QComboBox.
hasFrame
()¶ - Return type
bool
-
PySide6.QtWidgets.QComboBox.
hidePopup
()¶
Hides the list of items in the combobox if it is currently visible and resets the internal state, so that if the custom pop-up was shown inside the reimplemented showPopup()
, then you also need to reimplement the function to hide your custom pop-up and call the base class implementation to reset the internal state whenever your custom pop-up widget is hidden.
See also
-
PySide6.QtWidgets.QComboBox.
highlighted
(index)¶ - Parameters
index – int
-
PySide6.QtWidgets.QComboBox.
iconSize
()¶ - Return type
See also
-
PySide6.QtWidgets.QComboBox.
initStyleOption
(option)¶ - Parameters
Initialize option
with the values from this QComboBox . This method is useful for subclasses when they need a QStyleOptionComboBox
, but don’t want to fill in all the information themselves.
See also
-
PySide6.QtWidgets.QComboBox.
inputMethodQuery
(query, argument)¶ - Parameters
query –
InputMethodQuery
argument – object
- Return type
object
-
PySide6.QtWidgets.QComboBox.
insertItem
(index, icon, text[, userData=None])¶ - Parameters
index – int
icon –
PySide6.QtGui.QIcon
text – str
userData – object
Inserts the icon
, text
and userData
(stored in the UserRole
) into the combobox at the given index
.
If the index is equal to or higher than the total number of items, the new item is appended to the list of existing items. If the index is zero or negative, the new item is prepended to the list of existing items.
See also
-
PySide6.QtWidgets.QComboBox.
insertItem
(index, text[, userData=None]) - Parameters
index – int
text – str
userData – object
-
PySide6.QtWidgets.QComboBox.
insertItems
(index, texts)¶ - Parameters
index – int
texts – list of strings
Inserts the strings from the list
into the combobox as separate items, starting at the index
specified.
If the index is equal to or higher than the total number of items, the new items are appended to the list of existing items. If the index is zero or negative, the new items are prepended to the list of existing items.
See also
-
PySide6.QtWidgets.QComboBox.
insertPolicy
()¶ - Return type
See also
-
PySide6.QtWidgets.QComboBox.
insertSeparator
(index)¶ - Parameters
index – int
Inserts a separator item into the combobox at the given index
.
If the index is equal to or higher than the total number of items, the new item is appended to the list of existing items. If the index is zero or negative, the new item is prepended to the list of existing items.
See also
-
PySide6.QtWidgets.QComboBox.
isEditable
()¶ - Return type
bool
-
PySide6.QtWidgets.QComboBox.
itemData
(index[, role=Qt.UserRole])¶ - Parameters
index – int
role – int
- Return type
object
Returns the data for the given role
in the given index
in the combobox, or an invalid QVariant if there is no data for this role.
See also
-
PySide6.QtWidgets.QComboBox.
itemDelegate
()¶ - Return type
Returns the item delegate used by the popup list view.
See also
-
PySide6.QtWidgets.QComboBox.
itemIcon
(index)¶ - Parameters
index – int
- Return type
Returns the icon for the given index
in the combobox.
See also
-
PySide6.QtWidgets.QComboBox.
itemText
(index)¶ - Parameters
index – int
- Return type
str
Returns the text for the given index
in the combobox.
See also
-
PySide6.QtWidgets.QComboBox.
lineEdit
()¶ - Return type
Returns the line edit used to edit items in the combobox, or None
if there is no line edit.
Only editable combo boxes have a line edit.
See also
-
PySide6.QtWidgets.QComboBox.
maxCount
()¶ - Return type
int
See also
-
PySide6.QtWidgets.QComboBox.
maxVisibleItems
()¶ - Return type
int
See also
-
PySide6.QtWidgets.QComboBox.
minimumContentsLength
()¶ - Return type
int
See also
-
PySide6.QtWidgets.QComboBox.
model
()¶ - Return type
Returns the model used by the combobox.
See also
-
PySide6.QtWidgets.QComboBox.
modelColumn
()¶ - Return type
int
See also
-
PySide6.QtWidgets.QComboBox.
placeholderText
()¶ - Return type
str
See also
-
PySide6.QtWidgets.QComboBox.
removeItem
(index)¶ - Parameters
index – int
Removes the item at the given index
from the combobox. This will update the current index if the index is removed.
This function does nothing if index
is out of range.
-
PySide6.QtWidgets.QComboBox.
rootModelIndex
()¶ - Return type
Returns the root model item index for the items in the combobox.
See also
-
PySide6.QtWidgets.QComboBox.
setCompleter
(c)¶ - Parameters
See also
-
PySide6.QtWidgets.QComboBox.
setCurrentIndex
(index)¶ - Parameters
index – int
See also
-
PySide6.QtWidgets.QComboBox.
setCurrentText
(text)¶ - Parameters
text – str
See also
-
PySide6.QtWidgets.QComboBox.
setDuplicatesEnabled
(enable)¶ - Parameters
enable – bool
See also
-
PySide6.QtWidgets.QComboBox.
setEditText
(text)¶ - Parameters
text – str
Sets the text
in the combobox’s text edit.
-
PySide6.QtWidgets.QComboBox.
setEditable
(editable)¶ - Parameters
editable – bool
update the default delegate depending on the style’s SH_ComboBox_Popup hint, we use a different default delegate.
but we do not change the delegate is the combobox use a custom delegate, unless force
is set to true.
See also
-
PySide6.QtWidgets.QComboBox.
setFrame
(arg__1)¶ - Parameters
arg__1 – bool
See also
-
PySide6.QtWidgets.QComboBox.
setIconSize
(size)¶ - Parameters
size –
PySide6.QtCore.QSize
See also
-
PySide6.QtWidgets.QComboBox.
setInsertPolicy
(policy)¶ - Parameters
policy –
InsertPolicy
See also
-
PySide6.QtWidgets.QComboBox.
setItemData
(index, value[, role=Qt.UserRole])¶ - Parameters
index – int
value – object
role – int
Sets the data role
for the item on the given index
in the combobox to the specified value
.
See also
-
PySide6.QtWidgets.QComboBox.
setItemDelegate
(delegate)¶ - Parameters
delegate –
PySide6.QtWidgets.QAbstractItemDelegate
Sets the item delegate
for the popup list view. The combobox takes ownership of the delegate.
Any existing delegate will be removed, but not deleted. QComboBox does not take ownership of delegate
.
Warning
You should not share the same instance of a delegate between comboboxes, widget mappers or views. Doing so can cause incorrect or unintuitive editing behavior since each view connected to a given delegate may receive the closeEditor() signal, and attempt to access, modify or close an editor that has already been closed.
See also
-
PySide6.QtWidgets.QComboBox.
setItemIcon
(index, icon)¶ - Parameters
index – int
icon –
PySide6.QtGui.QIcon
Sets the icon
for the item on the given index
in the combobox.
See also
-
PySide6.QtWidgets.QComboBox.
setItemText
(index, text)¶ - Parameters
index – int
text – str
Sets the text
for the item on the given index
in the combobox.
See also
-
PySide6.QtWidgets.QComboBox.
setLineEdit
(edit)¶ - Parameters
edit –
PySide6.QtWidgets.QLineEdit
Sets the line edit
to use instead of the current line edit widget.
The combo box takes ownership of the line edit.
Note
Since the combobox’s line edit owns the QCompleter
, any previous call to will no longer have any effect.
See also
-
PySide6.QtWidgets.QComboBox.
setMaxCount
(max)¶ - Parameters
max – int
See also
-
PySide6.QtWidgets.QComboBox.
setMaxVisibleItems
(maxItems)¶ - Parameters
maxItems – int
See also
-
PySide6.QtWidgets.QComboBox.
setMinimumContentsLength
(characters)¶ - Parameters
characters – int
See also
-
PySide6.QtWidgets.QComboBox.
setModel
(model)¶ - Parameters
Sets the model to be model
. model
must not be None
. If you want to clear the contents of a model, call clear()
.
Note
If the combobox is editable, then the model
will also be set on the completer of the line edit.
See also
-
PySide6.QtWidgets.QComboBox.
setModelColumn
(visibleColumn)¶ - Parameters
visibleColumn – int
See also
-
PySide6.QtWidgets.QComboBox.
setPlaceholderText
(placeholderText)¶ - Parameters
placeholderText – str
See also
-
PySide6.QtWidgets.QComboBox.
setRootModelIndex
(index)¶ - Parameters
index –
PySide6.QtCore.QModelIndex
Sets the root model item index
for the items in the combobox.
See also
-
PySide6.QtWidgets.QComboBox.
setSizeAdjustPolicy
(policy)¶ - Parameters
policy –
SizeAdjustPolicy
See also
-
PySide6.QtWidgets.QComboBox.
setValidator
(v)¶ - Parameters
See also
-
PySide6.QtWidgets.QComboBox.
setView
(itemView)¶ - Parameters
itemView –
PySide6.QtWidgets.QAbstractItemView
Sets the view to be used in the combobox popup to the given itemView
. The combobox takes ownership of the view.
Note: If you want to use the convenience views (like QListWidget
, QTableWidget
or QTreeWidget
), make sure to call setModel()
on the combobox with the convenience widgets model before calling this function.
See also
-
PySide6.QtWidgets.QComboBox.
showPopup
()¶
Displays the list of items in the combobox. If the list is empty then no items will be shown.
If you reimplement this function to show a custom pop-up, make sure you call hidePopup()
to reset the internal state.
See also
-
PySide6.QtWidgets.QComboBox.
sizeAdjustPolicy
()¶ - Return type
See also
-
PySide6.QtWidgets.QComboBox.
textActivated
(arg__1)¶ - Parameters
arg__1 – str
-
PySide6.QtWidgets.QComboBox.
textHighlighted
(arg__1)¶ - Parameters
arg__1 – str
-
PySide6.QtWidgets.QComboBox.
validator
()¶ - Return type
Returns the validator that is used to constrain text input for the combobox.
See also
editable
-
PySide6.QtWidgets.QComboBox.
view
()¶ - Return type
Returns the list view used for the combobox popup.
See also
© 2021 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.