就业培训     下载中心     Wiki     联络 登录   注册
  1. 首页
  2. Qt 6.2.1
  3. Qt Widgets
  4. C++ 类
  5. QListWidget

内容

QListWidget 类

QListWidget 类提供基于项的列表 Widget。 更多...

头： #include <QListWidget>
CMake: find_package(Qt6 COMPONENTS Widgets REQUIRED)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake: QT += widgets
继承： QListView

特性

公共函数

  QListWidget (QWidget * parent = nullptr)
virtual ~QListWidget ()
void addItem (const QString & label )
void addItem (QListWidgetItem * item )
void addItems (const QStringList & labels )
void closePersistentEditor (QListWidgetItem * item )
int count () const
QListWidgetItem * currentItem () const
int currentRow () const
void editItem (QListWidgetItem * item )
QList<QListWidgetItem *> findItems (const QString & text , Qt::MatchFlags flags ) const
QModelIndex indexFromItem (const QListWidgetItem * item ) const
void insertItem (int row , QListWidgetItem * item )
void insertItem (int row , const QString & label )
void insertItems (int row , const QStringList & labels )
bool isPersistentEditorOpen (QListWidgetItem * item ) const
bool isSortingEnabled () const
QListWidgetItem * item (int row ) const
QListWidgetItem * itemAt (const QPoint & p ) const
QListWidgetItem * itemAt (int x , int y ) const
QListWidgetItem * itemFromIndex (const QModelIndex & index ) const
QWidget * itemWidget (QListWidgetItem * item ) const
QList<QListWidgetItem *> 项 (const QMimeData * data ) const
void openPersistentEditor (QListWidgetItem * item )
void removeItemWidget (QListWidgetItem * item )
int row (const QListWidgetItem * item ) const
QList<QListWidgetItem *> selectedItems () const
void setCurrentItem (QListWidgetItem * item )
void setCurrentItem (QListWidgetItem * item , QItemSelectionModel::SelectionFlags 命令 )
void setCurrentRow (int row )
void setCurrentRow (int row , QItemSelectionModel::SelectionFlags 命令 )
void setItemWidget (QListWidgetItem * item , QWidget * widget )
void setSortingEnabled (bool enable )
void sortItems (Qt::SortOrder order = Qt::AscendingOrder)
QListWidgetItem * takeItem (int row )
QRect visualItemRect (const QListWidgetItem * item ) const

重实现公共函数

virtual void setSelectionModel (QItemSelectionModel * selectionModel ) override

公共槽

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

信号

void currentItemChanged (QListWidgetItem * current , QListWidgetItem * previous )
void currentRowChanged (int currentRow )
void currentTextChanged (const QString & currentText )
void itemActivated (QListWidgetItem * item )
void itemChanged (QListWidgetItem * item )
void itemClicked (QListWidgetItem * item )
void itemDoubleClicked (QListWidgetItem * item )
void itemEntered (QListWidgetItem * item )
void itemPressed (QListWidgetItem * item )
void itemSelectionChanged ()

保护函数

virtual bool dropMimeData (int index , const QMimeData * data , Qt::DropAction action )
virtual QMimeData * mimeData (const QList<QListWidgetItem *> & 项 ) const
virtual QStringList mimeTypes () const
virtual Qt::DropActions supportedDropActions () const

重实现保护函数

virtual void dropEvent (QDropEvent * event ) override
virtual bool event (QEvent * e ) override

详细描述

QListWidget 是提供列表视图的方便类，类似供给通过 QListView ，但具有用于添加和移除项的基于项的经典接口。QListWidget 使用内部模型来管理每个 QListWidgetItem 在列表中。

对于更灵活列表视图 Widget，使用 QListView 类采用标准模型。

列表 Widget 的构造方式如同其它小部件： 

    QListWidget *listWidget = new QListWidget(this);

selectionMode () 对于列表 Widget 确定可以同时选择列表中多少项，及是否可以创建复杂项选定。这可以设置采用 setSelectionMode () 函数。

将项添加到列表有 2 种方式：可以采用列表 Widget 作为其父级小部件来构造它们，或可以不采用父级小部件构造它们和稍后添加到列表。若列表 Widget 已存在当构造项时，第一种方法更易于使用： 

    new QListWidgetItem(tr("Oak"), listWidget);
    new QListWidgetItem(tr("Fir"), listWidget);
    new QListWidgetItem(tr("Pine"), listWidget);

若需要将新的项插入列表特定位置，则它应不采用父级 Widget 被构造。 insertItem () 函数然后应该用于将其放置在列表中。列表 Widget 将拥有项的所有权。 

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

对于多个项， insertItems () 可以使用，取而代之。可以找到列表中的项数采用 count () 函数。要从列表移除项，使用 takeItem ().

可以找到列表中的当前项采用 currentItem ()，和改变采用 setCurrentItem ()。用户还可以采用键盘导航或点击不同项，改变当前项。当当前项改变时， currentItemChanged () 信号被发射采用新的当前项和先前是当前的项。

另请参阅 QListWidgetItem , QListView , QTreeView , 模型/视图编程 ，和 选项卡对话框范例 .

特性文档编制

[read-only] count : const int

此特性保持列表中的项数，包括任何隐藏项。

访问函数：

int count () const

currentRow : int

此特性保持当前项的行。

从属当前选定模式，行也可以被选中。

访问函数：

int currentRow () const
void setCurrentRow (int row )
void setCurrentRow (int row , QItemSelectionModel::SelectionFlags 命令 )

通知程序信号：

void currentRowChanged (int currentRow )

sortingEnabled : bool

此特性保持是否启用排序

若此特性为 true ，为列表启用排序；若特性为 False，不启用排序。

默认值为 false。

访问函数：

bool isSortingEnabled () const
void setSortingEnabled (bool enable )

成员函数文档编制

QListWidget:: QListWidget ( QWidget * parent = nullptr)

构造空的 QListWidget 采用给定 parent .

[slot] void QListWidget:: clear ()

移除视图中的所有项和选定。

警告： 所有项会被永久删除。

[signal] void QListWidget:: currentItemChanged ( QListWidgetItem * current , QListWidgetItem * previous )

此信号被发射每当当前项改变时。

previous 是先前有聚焦的项； current 是新的当前项。

[signal] void QListWidget:: currentRowChanged ( int currentRow )

此信号被发射每当当前项改变时。

currentRow 是当前项的行。若没有当前项， currentRow 为 -1。

注意： 通知程序信号对于特性 currentRow .

[signal] void QListWidget:: currentTextChanged (const QString & currentText )

此信号被发射每当当前项改变时。

currentText 是当前项的文本数据。若没有当前项， currentText 无效。

[signal] void QListWidget:: itemActivated ( QListWidgetItem * item )

此信号被发射当 item 被激活。 item 被激活当用户点击或双击它时，从属系统配置。它也被激活当用户按下激活键时 (在 Windows 和 X11 这是 Return 键，在 Mac OS X 它是 Command+O ).

[signal] void QListWidget:: itemChanged ( QListWidgetItem * item )

此信号被发射每当数据对于 item 已改变。

[signal] void QListWidget:: itemClicked ( QListWidgetItem * item )

此信号被发射采用指定 item 当在 Widget 项上点击鼠标按钮时。

另请参阅 itemPressed () 和 itemDoubleClicked ().

[signal] void QListWidget:: itemDoubleClicked ( QListWidgetItem * item )

此信号被发射采用指定 item 当在 Widget 项上双击鼠标按钮时。

另请参阅 itemClicked () 和 itemPressed ().

[signal] void QListWidget:: itemEntered ( QListWidgetItem * item )

此信号被发射当鼠标光标进入项时。 item 是进入项。此信号才被发射当 mouseTracking 被打开时或当移入项时按下鼠标按钮。

另请参阅 QWidget::setMouseTracking ().

[signal] void QListWidget:: itemPressed ( QListWidgetItem * item )

此信号被发射采用指定 item 当在 Widget 项上按下鼠标按钮时。

另请参阅 itemClicked () 和 itemDoubleClicked ().

[signal] void QListWidget:: itemSelectionChanged ()

此信号被发射每当选定改变时。

另请参阅 selectedItems (), QListWidgetItem::isSelected ()，和 currentItemChanged ().

[slot] void QListWidget:: scrollToItem (const QListWidgetItem * item , QAbstractItemView::ScrollHint hint = EnsureVisible)

卷动视图若有必要以确保 item 可见。

hint 指定哪里 item 应该被定位在操作后。

[虚拟] QListWidget:: ~QListWidget ()

销毁列表 Widget 及其所有项。

void QListWidget:: addItem (const QString & label )

插入项采用文本 label 在列表 Widget 末尾。

void QListWidget:: addItem ( QListWidgetItem * item )

插入 item 在列表 Widget 末尾。

警告： QListWidgetItem 只可以被添加到 QListWidget 一次。添加相同 QListWidgetItem 多次到 QListWidget 将产生未定义行为。

另请参阅 insertItem ().

void QListWidget:: addItems (const QStringList & labels )

插入项采用文本 labels 在列表 Widget 末尾。

另请参阅 insertItems ().

void QListWidget:: closePersistentEditor ( QListWidgetItem * item )

关闭持久编辑器为给定 item .

另请参阅 openPersistentEditor () 和 isPersistentEditorOpen ().

QListWidgetItem *QListWidget:: currentItem () const

返回当前项。

另请参阅 setCurrentItem ().

[override virtual protected] void QListWidget:: dropEvent ( QDropEvent * event )

重实现： QListView::dropEvent (QDropEvent *event).

[virtual protected] bool QListWidget:: dropMimeData ( int index , const QMimeData * data , Qt::DropAction action )

处理 data 的提供通过外部拖放操作，结束采用给定 action 以给定 index 。返回 true if data and action 可以由模型处理；否则返回 false .

另请参阅 supportedDropActions ().

void QListWidget:: editItem ( QListWidgetItem * item )

开始编辑 item 若它可编辑。

[override virtual protected] bool QListWidget:: event ( QEvent * e )

重实现： QListView::event (QEvent *e).

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

查找项具有的文本匹配字符串 text 使用给定 flags .

QModelIndex QListWidget:: indexFromItem (const QListWidgetItem * item ) const

返回 QModelIndex 关联给定 item .

注意： 在 Qt 5.10 之前，此函数接受非 const item .

void QListWidget:: insertItem ( int row , QListWidgetItem * item )

插入 item 在列表中的位置给出通过 row .

另请参阅 addItem ().

void QListWidget:: insertItem ( int row , const QString & label )

插入项采用文本 label 在列表 Widget 中于给定位置通过 row .

另请参阅 addItem ().

void QListWidget:: insertItems ( int row , const QStringList & labels )

插入项从列表 labels 进列表，开始于给定 row .

另请参阅 insertItem () 和 addItem ().

[since 5.10] bool QListWidget:: isPersistentEditorOpen ( QListWidgetItem * item ) const

返回是否打开持久编辑器为项 item .

该函数在 Qt 5.10 引入。

另请参阅 openPersistentEditor () 和 closePersistentEditor ().

QListWidgetItem *QListWidget:: item ( int row ) const

返回项占据给定 row 在列表若有设置；否则返回 nullptr .

另请参阅 row ().

QListWidgetItem *QListWidget:: itemAt (const QPoint & p ) const

返回指针指向项在坐标 p 。坐标相对列表小部件 viewport() .

QListWidgetItem *QListWidget:: itemAt ( int x , int y ) const

这是重载函数。

返回指针指向项在坐标 ( x , y )。坐标相对列表小部件 viewport() .

QListWidgetItem *QListWidget:: itemFromIndex (const QModelIndex & index ) const

返回指针指向 QListWidgetItem 关联给定 index .

QWidget *QListWidget:: itemWidget ( QListWidgetItem * item ) const

返回 Widget 显示在给定 item .

另请参阅 setItemWidget () 和 removeItemWidget ().

QList < QListWidgetItem *> QListWidget:: 项 (const QMimeData * data ) const

返回的指针列表项包含在 data 对象。若未创建对象通过 QListWidget 在同一过程中，列表为空。

[virtual protected] QMimeData *QListWidget:: mimeData (const QList < QListWidgetItem *> & 项 ) const

返回的对象包含序列化描述为指定 项 。用于描述项的格式获取自 mimeTypes () 函数。

若项列表为空， nullptr 被返回而不是序列化空列表。

[virtual protected] QStringList QListWidget:: mimeTypes () const

返回可以用于描述列表 Widget 项列表的 MIME 类型列表。

另请参阅 mimeData ().

void QListWidget:: openPersistentEditor ( QListWidgetItem * item )

打开编辑器为给定 item 。编辑器仍然打开在编辑之后。

另请参阅 closePersistentEditor () 和 isPersistentEditorOpen ().

void QListWidget:: removeItemWidget ( QListWidgetItem * item )

移除设置 Widget 在给定 item .

要从列表完全移除项 (行)，删除项或使用 takeItem ().

另请参阅 itemWidget () 和 setItemWidget ().

int QListWidget:: row (const QListWidgetItem * item ) const

返回行包含给定 item .

另请参阅 item ().

QList < QListWidgetItem *> QListWidget:: selectedItems () const

返回列表 Widget 中所有选中项的列表。

void QListWidget:: setCurrentItem ( QListWidgetItem * item )

将当前项设为 item .

除非选定模式为 NoSelection ，项还被选中。

另请参阅 currentItem ().

void QListWidget:: setCurrentItem ( QListWidgetItem * item , QItemSelectionModel::SelectionFlags 命令 )

将当前项设为 item ，使用给定 命令 .

void QListWidget:: setCurrentRow ( int row , QItemSelectionModel::SelectionFlags 命令 )

把当前行设为给定 row ，使用给定 命令 ,

注意： setter 函数对于特性 currentRow .

void QListWidget:: setItemWidget ( QListWidgetItem * item , QWidget * widget )

设置 widget 以显示在给定 item .

此函数只应用于在列表 Widget 项位置显示静态内容。若想要显示自定义动态内容或实现自定义编辑器 Widget，使用 QListView 和子类 QStyledItemDelegate 代替。

另请参阅 itemWidget (), removeItemWidget ()，和 委托类 .

[override virtual] void QListWidget:: setSelectionModel ( QItemSelectionModel * selectionModel )

重实现： QAbstractItemView::setSelectionModel (QItemSelectionModel *selectionModel).

void QListWidget:: sortItems ( Qt::SortOrder order = Qt::AscendingOrder)

排序列表 Widget 中的所有项根据指定 order .

[virtual protected] Qt::DropActions QListWidget:: supportedDropActions () const

返回由此视图所支持的掉落动作。

另请参阅 Qt::DropActions .

QListWidgetItem *QListWidget:: takeItem ( int row )

移除并返回项从给定 row 在列表 Widget 中；否则返回 nullptr .

从列表 Widget 移除的项未由 Qt 管理，且需要手动删除。

另请参阅 insertItem () 和 addItem ().

QRect QListWidget:: visualItemRect (const QListWidgetItem * item ) const

返回项所占据的视口矩形为 item .