第15.26节 PyQt(Python+Qt)入门学习:Model/View架构中的便利类QListWidget详解

时间:2024-09-01 13:34:20

一、概述

列表部件(List Widget)对应类QListWidget,是从QListView派生的类,用于显示一些数据的列表,不支持多层级数据的显示。QListWidget显示的数据项都通过QListWidgetItem构建。

QListWidget是一个便利类,它提供了一个类似于QListView提供的列表视图,具有一个用于添加和删除项的接口。QListWidget使用一个内部模型来管理列表中的每个QListWidgetItem项。如果应用需要更灵活的列表视图控件,建议使用标准模型和QListView类而不是QListWidget来开发。

二、QListWidgetItem项

2.1、概述

QListWidgetItem类为QListWidget类提供构成QListWidget列表部件的项,每个列表部件的项都是一个QListWidgetItem对象。每个项可以保存多条信息,如显示文字、图标、toolTip、what’sThis、对齐方式、复选框等,并根据这些信息在列表部件中显示出来。

2.1、QListWidgetItem构造方法

QListWidgetItem对象专门用于作为QListWidget对象的一个项。

QListWidgetItem有四个构造方法,分别如下:

  • QListWidgetItem(parent: QListWidget = None, type: int = QListWidgetItem.Type)

    构建一个用于QListWidget对象的项,如果指定了parent(一个QListWidget对象),则该项被插入到该参数对应的QListWidget列表部件中,否则只能在创建后调用QListWidget列表部件的insertItem方法插入。

    参数type类型为枚举类型QListWidgetItem.ItemType,其缺省值为QListWidgetItem.Type(对应值为0),否则为QListWidget派生类中使用的一个大于等于QListWidgetItem.UserType(对应值为1000)的整数值,使用单独的type值用于在派生类中对象进行特殊的处理,如排序。
  • QListWidgetItem(str, parent: QListWidget = None, type: int = QListWidgetItem.Type)

    构建一个项,项显示的文本由str字符串参数指定,其余两个参数与第一个构造方法相同。
  • QListWidgetItem(QIcon, str, parent: QListWidget = None, type: int = QListWidgetItem.Type)

    构建一个项,项显示的文本由str字符串参数指定,项对应图标由QIcon指定,其余两个参数与第一个构造方法相同。
  • QListWidgetItem(QListWidgetItem other)

    构建一个项,项的内容从参数指定项other拷贝,但type 和parent不拷贝。

在使用以上构造方法的前三种时,如果构建列表部件的项时指定了parent参数对应的列表部件对象,则构建的项会自动插入到列表部件中,如果没有指定该参数或者是用第四种构造方法,项创建后需要调用列表部件的addItem(QListWidgetItem item)方法或insertItem(int row, QListWidgetItem item)方法将构建的项插入到列表部件的列表中。

2.2、QListWidgetItem其他重要方法

2.2.1、checkState和setCheckState方法

这两个方法用于访问或设置项的复选状态,调用语法分别如下:

2.2.2、icon和setIcon方法

这两个方法用于访问或设置项的图标,调用语法分别如下:

  • QListWidgetItem.setIcon(QIcon icon)
  • QIcon QListWidgetItem.icon()。

2.2.3、isHidden和setHidden方法

这两个方法用于访问或设置项的选中状态,调用语法分别如下:

  • QListWidgetItem.setSelected(bool select)
  • bool QListWidgetItem.isSelected()

2.2.4、text和setText方法

这两个方法用于访问或设置项的显示和编辑文本,调用语法分别如下:

  • QListWidgetItem.setText(str)
  • str QListWidgetItem.text()

2.2.5、flags和setFlags方法

这两个方法用于访问或设置项的标志,调用语法分别如下:

2.2.6、其他方法

其他方法包括用于访问状态提示的setStatusTip、statusTip方法,用于访问工具栏提示的 setToolTip、toolTip方法,用于访问WhatsThis提示的setWhatsThis、whatsThis方法,用于设置项对齐方式的setTextAlignment、textAlignment方法(关于对齐标记取值的含义请参考《PyQt(Python+Qt)学习随笔:formLayout的layoutLabelAlignment 属性》)以及访问项类型的type方法。

三、QListWidget类

3.1、QListWidget类的属性

3.1.1、属性概述

QListWidget类的属性除了从父类QListView、QAbstractItemView、QAbstractScrollArea、QFrame、QWidget、QObject继承的属性外,自身的属性有三个,分别是:count、currentRow和sortingEnabled,这三个属性中,currentRow和sortingEnabled是可以在Qt Designer中进行设置的属性。

3.1.2、count属性

count属性保存QListWidget列表部件对象中项的个数,这个个数包含了隐藏未显示的项。可以通过方法count()获取该属性的值。

3.1.3、currentRow属性

QListWidget的currentRow属性保存当前项的位置,为整型,从0开始计数,在某些选择模式下,当前项可能也是选中项。

currentRow属性可以通过方法currentRow()、setCurrentRow(int row)、setCurrentRow(int row, QItemSelectionModel.SelectionFlags command)进行访问和设置。

关于QItemSelectionModel.SelectionFlags的取值请参考《PyQt(Python+Qt)学习随笔:Mode/View中的枚举类 QItemSelectionModel.SelectionFlag取值及含义》。

当当前项发生变化时,QListWidget会发射信号currentRowChanged(int currentRow)。

3.1.4、sortingEnabled属性

QListWidget的sortingEnabled属性用于控制列表部件中的项是否可以排序,如果为True则可以排序,否则不能排序。

可以通过方法isSortingEnabled() 和setSortingEnabled(bool enable)访问或设置该属性。

3.2、QListWidget类的重要方法

3.2.1、构造方法

QListWidget类的构造方法很简单,语法如下:

QListWidget(QWidget parent = None)

parent一般是谁创建QListWidget对象就指定为谁,实际上在Python中,使用上述方式定义一个对象时,真正执行的构造方法是__init__

3.2.2、增加单个项的方法addItem

在QListWidget对象中,增加一个项的方法是调用addItem方法,addItem方法有2种重载方式,分别语法如下:

  • addItem(str )

    该方法直接在列表部件QListWidget对象的列表尾部增加一个文本内容为参数指定值的对象,不用单独构建QListWidgetItem对象。
  • addItem(QListWidgetItem )

    该方法需要先构建一个QListWidgetItem项,再将该项追加到列表部件QListWidget对象的列表尾部。

3.2.3、增加多个项的方法addItems

除了上面的方法addItem能增加项外,QListWidget支持一次增加多个项,对应的方法就是addItems方法,对应语法如下:

addItems(Iterable[str])

其参数为一个可迭代的类型,其中的元素为字符串。

案例:

 items = ['item1','item2','item3']
self.listWidget.addItems(items)

这样一次就可以增加三个项,不用先构建项,使用起来方便。

3.2.4、访问当前项的currentItem和setCurrentItem方法

currentItem方法返回列表部件当前选择的项,setCurrentItem方法用于设置当前项。语法如下:

  • QListWidgetItem currentItem()
  • setCurrentItem(QListWidgetItem item)
  • setCurrentItem(QListWidgetItem item, QItemSelectionModel.SelectionFlags command)

关于SelectionFlags 请参考《PyQt(Python+Qt)学习随笔:Mode/View中的枚举类 QItemSelectionModel.SelectionFlag取值及含义》,带SelectionFlags 参数时除了设置当前项外,还会影响对列表部件的项的选中数据变化,具体变化由参数command指定。

setCurrentItem使用时注意2点:
  • 除非选择模式设置为NoSelection,否则setCurrentItem设置项当前项后,对应项也会被选中
  • setCurrentItem没有返回值,无法判断是否成功识别,如果对应item在列表部件中不存在也不会有异常出现

3.2.5、查找项的findItems方法

findItems方法用于查找列表部件是否有满足条件的项,调用语法如下:

list findItems( str label, Qt.MatchFlags flag)

findItems用于列表部件中查找文本内容与label参数匹配的项,查找过程的匹配模式由flag参数指定,返回值为一个满足条件的Qt.MatchExactly项的列表。枚举类Qt.MatchFlags的取值及含义请参考《PyQt(Python+Qt)学习随笔:Model/View中的枚举类 Qt.MatchFlag的取值及含义》。

3.2.5、插入单个项的insertItem方法

在QListWidget对象中,插入一个项的方法是调用insertItem方法,insertItem方法有2种重载方式,分别语法如下:

  • insertItem(int row,str label )

    该方法直接在列表部件QListWidget对象的列表指定位置插入一个文本内容为参数指定值的项,不用单独构建QListWidgetItem对象。
  • insertItem(int row,QListWidgetItem item)

    该方法需要先构建一个QListWidgetItem项,再将该项插入到列表部件指定位置。

3.2.6、插入多个项的insertItems方法

除了上面的方法insertItem能插入项外,QListWidget支持一次插入多个项,对应的方法就是insertItems方法,对应语法如下:

insertItems(int row,Iterable[str])

row指定插入项的开始位置,另一个参数为一个可迭代的类型,其中的元素为字符串。

3.2.7、获取指定行对应项的item方法

在列表部件中,可以通过item方法获取指定行对应的项,语法如下:

QListWidgetItem item(int row)

注意

row从0开始计数,如果对应位置不存在项,则返回None。

3.2.8、获取指定位置对应项的itemAt方法

itemAt方法根据参数给定位置返回列表部件中的项。对应语法如下:

QListWidgetItem itemAt(QPoint p)
QListWidgetItem itemAt(int x, int y)

注意:位置对应坐标是相对列表部件的视口的,关于视口请参考《PyQt(Python+Qt)学习随笔:QAbstractScrollArea的viewPort(视口)理解》。

3.2.9、获取指定项对应行的row方法

QListWidget的row方法通过项作为参数,获取到对应项所在行的行号,语法如下:

int row(QListWidgetItem item)

如果对应项在列表部件中不存在,则返回-1。

3.2.10、获取当前选中项的selectedItems方法

QListWidget的selectedItems方法返回列表部件中所有选中项的一个列表,调用语法如下:

list selectedItems()

返回列表中的每个元素就是一个QListWidgetItem对象,如果没有选中项,则返回空列表。

3.2.11、当前选择模式selectionMode操作方法

列表部件的selectionMode决定了列表中有多少项可以同时选择,以及是否可以使用复杂的项选择操作。selectionMode可以通过selectionMode()获取,通过setSelectionMode(QItemSelectionModel )函数设置。

关于QItemSelectionModel 请参考

PyQt(Python+Qt)学习随笔:Mode/View中的枚举类 QItemSelectionModel.SelectionFlag取值及含义》。

3.2.12、对项进行排序的sortItems方法

QListWidget的sortItems方法用于对列表部件中所有项按参数进行排序,相关调用语法如下:

sortItems(Qt.SortOrder order = Qt.AscendingOrder)

枚举类型Qt.SortOrder用于指定排序是按升序排序还是降序排序,取值及含义如下:

  • AscendingOrder:值为0,表示升序排序
  • DescendingOrder:值为1,表示降序排序

3.2.13、删除项的takeItem方法

takeItem方法从QListWidget列表部件的项中删除指定项,并返回对应项对象。调用语法如下:

QListWidgetItem takeItem(int row)

如果对应row没有项,则返回None。

在此介绍了一些QListWidget的常用方法,还有些其他方法老猿在此就不再详细介绍了,感兴趣的同学可以自己查阅资料。

四、小结

QListWidget便利类是在QListView的基础上提供的一个便利类,可以在界面上展示一个只有一列的列表,适合快速开发一个简单的列表视图,但如果涉及大数据量及复杂的视图,还是需要使用QListView。本节详细介绍了 Model/View便利类列表部件QListWidget的主要属性、方法,但怎么使用和应用密切相关。

广告

老猿关于PyQt的付费专栏《使用PyQt开发图形界面Python应用》只需要9.9元,该部分与第十五章的内容基本对应,但同样内容在付费专栏上总体来说更详细、案例更多。本节内容对应付费专栏的《第二十一章、 Model/View便利类列表部件QListWidget详解》。如果有兴趣也愿意支持老猿的读者,欢迎购买付费专栏。

第15.26节 PyQt(Python+Qt)入门学习:Model/View架构中的便利类QListWidget详解

老猿Python,跟老猿学Python!