pyqt4文档阅读(8):QComboBox

本系列文章长期更新修改.

QComboBox,中文翻译是组合框?就是一个提供下拉菜单的选值框.

属性:

Types

enum InsertPolicy { NoInsert, InsertAtTop, InsertAtCurrent, InsertAtBottom, ..., InsertAlphabetically }
enum SizeAdjustPolicy { AdjustToContents, AdjustToContentsOnFirstShow, AdjustToMinimumContentsLength, AdjustToMinimumContentsLengthWithIcon }

Methods

__init__ (self, QWidget parent = None)
addItem (self, QString atext, QVariant auserData = QVariant())
addItem (self, QIcon aicon, QString atext, QVariant auserData = QVariant())
addItems (self, QStringList texts)
bool autoCompletion (self)
Qt.CaseSensitivity autoCompletionCaseSensitivity (self)
changeEvent (self, QEvent e)
clear (self)
clearEditText (self)
QCompleter completer (self)
contextMenuEvent (self, QContextMenuEvent e)
int count (self)
int currentIndex (self)
QString currentText (self)
bool duplicatesEnabled (self)
bool event (self, QEvent event)
int findData (self, QVariant data, int role = Qt.UserRole, Qt.MatchFlags flags = Qt.MatchExactly | Qt.MatchCaseSensitive)
int findText (self, QString text, Qt.MatchFlags flags = Qt.MatchExactly | Qt.MatchCaseSensitive)
focusInEvent (self, QFocusEvent e)
focusOutEvent (self, QFocusEvent e)
bool hasFrame (self)
hideEvent (self, QHideEvent e)
hidePopup (self)
QSize iconSize (self)
initStyleOption (self, QStyleOptionComboBox option)
inputMethodEvent (self, QInputMethodEvent)
QVariant inputMethodQuery (self, Qt.InputMethodQuery)
insertItem (self, int aindex, QString atext, QVariant auserData = QVariant())
insertItem (self, int index, QIcon icon, QString text, QVariant userData = QVariant())
insertItems (self, int index, QStringList texts)
InsertPolicy insertPolicy (self)
insertSeparator (self, int index)
bool isEditable (self)
QVariant itemData (self, int index, int role = Qt.UserRole)
QAbstractItemDelegate itemDelegate (self)
QIcon itemIcon (self, int index)
QString itemText (self, int index)
keyPressEvent (self, QKeyEvent e)
keyReleaseEvent (self, QKeyEvent e)
QLineEdit lineEdit (self)
int maxCount (self)
int maxVisibleItems (self)
int minimumContentsLength (self)
QSize minimumSizeHint (self)
QAbstractItemModel model (self)
int modelColumn (self)
mousePressEvent (self, QMouseEvent e)
mouseReleaseEvent (self, QMouseEvent e)
paintEvent (self, QPaintEvent e)
removeItem (self, int index)
resizeEvent (self, QResizeEvent e)
QModelIndex rootModelIndex (self)
setAutoCompletion (self, bool enable)
setAutoCompletionCaseSensitivity (self, Qt.CaseSensitivity sensitivity)
setCompleter (self, QCompleter c)
setCurrentIndex (self, int index)
setDuplicatesEnabled (self, bool enable)
setEditable (self, bool editable)
setEditText (self, QString text)
setFrame (self, bool)
setIconSize (self, QSize size)
setInsertPolicy (self, InsertPolicy policy)
setItemData (self, int index, QVariant value, int role = Qt.UserRole)
setItemDelegate (self, QAbstractItemDelegate delegate)
setItemIcon (self, int index, QIcon icon)
setItemText (self, int index, QString text)
setLineEdit (self, QLineEdit edit)
setMaxCount (self, int max)
setMaxVisibleItems (self, int maxItems)
setMinimumContentsLength (self, int characters)
setModel (self, QAbstractItemModel model)
setModelColumn (self, int visibleColumn)
setRootModelIndex (self, QModelIndex index)
setSizeAdjustPolicy (self, SizeAdjustPolicy policy)
setValidator (self, QValidator v)
setView (self, QAbstractItemView itemView)
showEvent (self, QShowEvent e)
showPopup (self)
SizeAdjustPolicy sizeAdjustPolicy (self)
QSize sizeHint (self)
QValidator validator (self)
QAbstractItemView view (self)
wheelEvent (self, QWheelEvent e)

Qt Signals

void activated (int)
void activated (const QString&)
void currentIndexChanged (int)
void currentIndexChanged (const QString&)
void editTextChanged (const QString&)
void highlighted (int)
void highlighted (const QString&)

详细分析:

1.可编辑QComboBox

QComboBox有一个很重要的属性editable,如果editable为false,则QComboBox就是开篇那张图片的样子.

如果editable为true,那么QComboBox就会摇身一变,变成一个QLineEdit+下拉菜单的控件,这时候我们称这个QComboBox是可编辑的.

bool isEditable (self)
setEditable (self, bool editable)
在下面的许多分析里,都要基于editable的值进行分类讨论.

2.选项操作和属性设置

QComboBox最重要的操作就是选项的操作和属性设置,一个选项包括一个字符串和一个icon,还有一个比较少用的用户数据.

用户数据的含义和用法暂时忽略.

添加到末尾
addItem (self, QString atext, QVariant auserData = QVariant())
addItem (self, QIcon aicon, QString atext, QVariant auserData = QVariant())
addItems (self, QStringList texts)

插入
insertItem (self, int aindex, QString atext, QVariant auserData = QVariant())
insertItem (self, int index, QIcon icon, QString text, QVariant userData = QVariant())
insertItems (self, int index, QStringList texts)

插入分割线
insertSeparator (self, int index)

删除
removeItem (self, int index)
clear (self)

文本属性
QString itemText (self, int index)

setItemText (self, int index, QString text)

icon属性
QIcon itemIcon (self, int index)
setItemIcon (self, int index, QIcon icon)

用户数据属性
QVariant itemData (self, int index, int role = Qt.UserRole)
setItemData (self, int index, QVariant value, int role = Qt.UserRole)

icon尺寸
QSize iconSize (self)
setIconSize (self, QSize size)

注意,QComboBox的index按照下拉菜单里项目的上下顺序,和添加的时间顺序无关,并且包含分割线.

3.当前选项

在运行时,可以通过下列函数获取和设置当前所选的选项:

int currentIndex (self)
QString currentText (self)
setCurrentIndex (self, int index)
当QComboBox可编辑,并且被编辑过时,currentIndex是最后一次被选择的项目下标,currentText则是当前文本框的内容.

4.文本操作

可编辑的QComboBox本身就有一个QLineEdit控件,我们可以获取这个控件,并使用它的函数,以及QComboBox提供的少量函数,对文本框进行各项操作.

QLineEdit lineEdit (self)
setLineEdit (self, QLineEdit edit)
setEditText (self, QString text)
clearEditText (self)

5.插入策略

可编辑的QComboBox中,如果用户编辑了原本不存在的选项,在键入回车后,Qt会根据设置好的策略把这个新选项插入到下拉菜单中去.

InsertPolicy insertPolicy (self)
setInsertPolicy (self, InsertPolicy policy)
这些策略隶属于枚举集QComboBox.InsertPolicy,默认值是3,插入到最末端.

枚举量	值	描述
NoInsert	0	不插入
InsertAtTop	1	插入到最顶端
InsertAtCurrent	2	当前选项被替换
InsertAtBottom	3	插入到最末端
InsertAfterCurrent	4	插入到当前选项之后
InsertBeforeCurrent	5	插入到当前选项之前
InsertAlphabetically	6	根据字典序插入

伴随着插入,还有一个问题,每当键入回车的时候,如果发现是新选项,则会执行上面策略.

但如果发现是旧选项,Qt也可能会把它重复插入到下拉菜单中去.这与一个是否可重复的属性有关,它默认是false,即不能重复插入.

bool duplicatesEnabled (self)
setDuplicatesEnabled (self, bool enable)

6.信号

QComboBox有以下特有信号,并且这些信号几乎都有两个版本,差别在于参数

信号	激活条件	备注
void activated (int) void activated (const QString&)	选项被点击 按下回车键	无论当前选项是否改变
void currentIndexChanged (int) void currentIndexChanged (const QString&)	当前选项改变	若当前选项非法时,参数为-1 可编辑可插入状态时会激活两次,参数分别是插入后原选项和新选项
void editTextChanged (const QString&)	输入框文本改变	包括用户的点击选项或编辑文本,和用程序改变 只能在可编辑状态时激活
void highlighted (int) void highlighted (const QString&)	下拉菜单高亮改变	即当下拉菜单被展示时,用鼠标或键盘移动,造成高亮改变

7.自动补全和输入检测

可编辑的QComboBox可以通过下列函数设置在编辑时的自动补全和输入检测服务:

QCompleter completer (self)
setCompleter (self, QCompleter c)
QValidator validator (self)
setValidator (self, QValidator v)
其实即使不手动设置自动补全,QComboBox会自动生成一个QCompleter对象,它包含的词汇就是所有选项里的文字.

因此,QComboBox有一个是否启用自动补全的属性,默认启动.

还加了一个大小写是否敏感的属性设置,默认不敏感.

bool autoCompletion (self)
setAutoCompletion (self, bool enable)
Qt.CaseSensitivity autoCompletionCaseSensitivity (self)
setAutoCompletionCaseSensitivity (self, Qt.CaseSensitivity sensitivity)

8.数字属性

函数	含义	备注
int count (self)	当前选项数目	包含分割线
int maxCount (self) setMaxCount (self, int max)	允许最大选项数目	当选项数等于它时,即使是可编辑可插入状态下也无法插入 默认值是int32_max
int maxVisibleItems (self) setMaxVisibleItems (self, int maxItems)	最大访问项目数	即下拉菜单一次显示的选项数 如果选项数大于它时,下拉菜单会出现滚动条 默认值是10
int minimumContentsLength (self) setMinimumContentsLength (self, int characters)	最少字符数	这个值与编辑时字符串数量无关. Qt会调整尺寸来会确保屏幕一次能显示这个数量的字符. 默认值是0

9.内容匹配

QComboBox提供匹配函数,根据内容或用户数据,来寻找选项

int findData (self, QVariant data, int role = Qt.UserRole, Qt.MatchFlags flags = Qt.MatchExactly | Qt.MatchCaseSensitive)
int findText (self, QString text, Qt.MatchFlags flags = Qt.MatchExactly | Qt.MatchCaseSensitive)
其中Qt.MatchFlags是匹配策略,默认是精确匹配+大小写敏感

10.下拉菜单

在运行过程中,可以通过下列函数进行下拉菜单的隐藏或展示:

hidePopup (self)
showPopup (self)
注意的是,如果QComboBox未被画出来,而调用showPopup(),弹出的菜单位置和大小会异常.

11.外边框

QComboBox可以设置是否需要外边框,默认是有.

bool hasFrame (self)
setFrame (self, bool)

不可编辑状态下,设置不需要基本无效,并且使得文字对齐十分奇怪.

可编辑状态下,设置不需要能让文本框的框消失,但小三角形的边框会部分保留,也很奇怪.

因此,通常不会设置这个属性.

12.待续

enum SizeAdjustPolicy { AdjustToContents, AdjustToContentsOnFirstShow, AdjustToMinimumContentsLength, AdjustToMinimumContentsLengthWithIcon }

SizeAdjustPolicy sizeAdjustPolicy (self)

setSizeAdjustPolicy (self, SizeAdjustPolicy policy)

QAbstractItemDelegate itemDelegate (self)

setItemDelegate (self, QAbstractItemDelegate delegate)

QAbstractItemModel model (self)

int modelColumn (self)

QModelIndex rootModelIndex (self)

setModel (self, QAbstractItemModel model)

setModelColumn (self, int visibleColumn)

setRootModelIndex (self, QModelIndex index)

QAbstractItemView view (self)

setView (self, QAbstractItemView itemView)