Qt模型视图框架：QListWidget

一、描述

QListWidget 是一个方便的类，它提供类似于 QListView 提供的列表视图，但具有用于添加和删除项目功能的界面。 QListWidget 使用内部模型来管理列表中的每个 QListWidgetItem。

有两种方法可以将项目添加到列表中：

• 可以使用列表小部件作为其父小部件来构建。

     QListWidget *listWidget = new QListWidget(this);
     new QListWidgetItem(tr("Oak"), listWidget);
     new QListWidgetItem(tr("Fir"), listWidget);
     new QListWidgetItem(tr("Pine"), listWidget);

• 可以在没有父小部件的情况下构建并稍后添加到列表中。

     QListWidgetItem *newItem = new QListWidgetItem;
     newItem->setText(itemText);
     QListWidget *listWidget = new QListWidget(this);
     listWidget->insertItem(row, newItem);

---

二、属性成员

1、count : const int

此属性保存列表中的项目数，包括任何隐藏项目。

2、currentRow : int 

此属性保存当前项目的行。

3、sortingEnabled : bool

此属性保存是否启用排序。默认值为false。 

---

三、成员函数

3.1、信号

1、void currentItemChanged(QListWidgetItem *current, QListWidgetItem *previous)

每当当前项目发生变化时都会发出此信号。

previous 是先前具有焦点的项目； current 是新的当前项目。

2、void currentRowChanged(int currentRow)

每当当前项目发生变化时都会发出此信号。currentRow 是当前项目的行。 如果没有当前项，则 currentRow 为 -1。

3、void currentTextChanged(const QString &currentText)

每当当前项目发生变化时都会发出此信号。currentText 是当前项中的文本数据。 如果没有当前项，则 currentText 无效。

4、void itemActivated(QListWidgetItem *item)

当项目被激活时发出这个信号。 当用户单击或双击它时，该项目将被激活，具体取决于系统配置。 当用户按下激活键时它也会被激活（在 Windows 和 X11 上这是返回键，在 Mac OS X 上是 Command+O）。

5、void itemChanged(QListWidgetItem *item)

每当 item 的数据发生变化时，就会发出此信号。

6、void itemClicked(QListWidgetItem *item)

当在小部件中的item上单击鼠标按钮时，此信号随指定item一起发出。

7、void itemDoubleClicked(QListWidgetItem *item)

当在小部件中的item上双击鼠标按钮时，此信号随指定item一起发出。

8、 void itemEntered(QListWidgetItem *item)

当鼠标光标进入一个item时发出这个信号。item是输入的项目。此信号仅在打开 mouseTracking（QWidget::setMouseTracking(true)）或在移动到item时按下鼠标时发出。

9、void itemPressed(QListWidgetItem *item) 

当在小部件中的item上按下鼠标按钮时，此信号随指定item一起发出。

 10、void itemSelectionChanged()

只要选择发生变化，就会发出该信号。

3.2、函数

1、void clear()

删除视图中的所有项目。

2、void scrollToItem(const QListWidgetItem *item, QAbstractItemView::ScrollHint hint = EnsureVisible)

如有必要，滚动视图以确保项目可见。hint 指定操作后项目应位于的位置。

3、void addItem(const QString &label) / void addItems(const QStringList &labels)

在列表小部件的末尾插入带有文本标签的项目。

4、void addItem(QListWidgetItem *item)

在列表小部件的末尾插入项目。

警告： QListWidgetItem 只能添加到 QListWidget 一次。 将相同的 QListWidgetItem 多次添加到 QListWidget 将导致未定义的行为。

5、void closePersistentEditor(QListWidgetItem *item)

关闭给定项目的持久编辑器。

6、QListWidgetItem * currentItem()

获取当前item。

7、void editItem(QListWidgetItem *item)

 如果item可编辑，则开始编辑item。

8、QList<QListWidgetItem *> findItems(const QString &text, Qt::MatchFlags flags)

使用flags查找具有与text匹配的文本的项目。

enum Qt::MatchFlag：此枚举描述了在模型中搜索项目时可以使用的匹配类型。

• Qt::MatchExactly：执行基于 QVariant 的匹配。
• Qt::MatchFixedString：执行基于字符串的匹配。除非还指定了 MatchCaseSensitive 标志，否则基于字符串的比较不区分大小写。
• Qt::MatchContains：搜索词包含在项目中。
• Qt::MatchStartsWith：搜索词匹配项的开头。
• Qt::MatchEndsWith：搜索词匹配项的结尾。
• Qt::MatchCaseSensitive：搜索区分大小写。
• Qt::MatchRegularExpression：使用正则表达式作为搜索词来执行基于字符串的匹配。使用 QRegularExpression。使用此标志时，可以将 QRegularExpression 对象作为参数传递，并将直接用于执行搜索。区分大小写标志将被忽略。
• Qt::MatchWildcard：使用带有通配符的字符串作为搜索词来执行基于字符串的匹配。
• Qt::MatchWrap：执行环绕搜索，这样当搜索到达模型中的最后一项时，它会再次从第一项开始，一直持续到检查完所有项为止。
• Qt::MatchRecursive：搜索整个层次结构。

注意：

• Qt::MatchExactly
• Qt::MatchContains
• Qt::MatchStartsWith
• Qt::MatchEndsWith
• Qt::MatchRegularExpression
• Qt::MatchWildcard
• Qt::MatchFixedString

是互斥的。通过在 Qt::MatchFlags 参数中设置其中几个实现的行为是未定义的。

9、QModelIndex indexFromItem(const QListWidgetItem *item)        【常用】

返回与给定项目关联的 QModelIndex。

10、QListWidgetItem * itemFromIndex(const QModelIndex &index)        【常用】

返回指向与给定索引关联的 QListWidgetItem 的指针。

11、void insertItem(int row, QListWidgetItem *item)

       void insertItem(int row, const QString &label)

       void insertItems(int row, const QStringList &labels)

在row给定的列表中的位置插入项目。

12、bool isPersistentEditorOpen(QListWidgetItem *item)

返回是否为项目项打开了持久编辑器。

13、QListWidgetItem * item(int row)

返回列表中给定行的项目。

14、QListWidgetItem * itemAt(const QPoint &p)

返回指向坐标 p 处的项目的指针。 坐标相对于列表小部件的viewport()（QWidget::viewport()）。

15、QWidget * itemWidget(QListWidgetItem *item)

       void  setItemWidget(QListWidgetItem *item, QWidget *widget)

返回给定项目中显示的小部件。/

设置要在给定项目中显示的小部件。此函数应该仅用于在列表小部件项的位置显示静态内容。 如果要显示自定义动态内容或实现自定义编辑器小部件，请改用 QListView 和子类 QStyledItemDelegate。

16、void removeItemWidget(QListWidgetItem *item)

删除在给定项目上设置的小部件。

17、QList<QListWidgetItem *>  items(const QMimeData *data)

返回指向包含data的项目的指针列表。

18、void openPersistentEditor(QListWidgetItem *item)

打开给定项目的编辑器。编辑器在编辑后保持打开状态。

19、int row(const QListWidgetItem *item)

返回包含给定item的行。

20、QList<QListWidgetItem *> selectedItems()

返回列表小部件中所有选定项目的列表。

21、void setCurrentItem(QListWidgetItem *item)

将当前项目设置为item。除非选择模式为 NoSelection，否则item也会被选中。

22、void setCurrentItem(QListWidgetItem *item, QItemSelectionModel::SelectionFlags command) 

       void setCurrentRow(int row, QItemSelectionModel::SelectionFlags command)

设置当前行。

23、void sortItems(Qt::SortOrder order = Qt::AscendingOrder)

根据指定的顺序对列表小部件中的所有项目进行排序。

24、QListWidgetItem * takeItem(int row) 

从列表小部件的给定行中删除并返回项目。

从列表小部件中删除的项目不会由 Qt 管理，需要手动删除。

25、QRect visualItemRect(const QListWidgetItem *item)

返回 item 处的 item 占据的视口上的矩形。