DListView 一个用于展示一列数据的控件. 更多...

类 Dtk::Widget::DListView 继承关系图:

Public 槽
bool	addItem (const QVariant &data)
	在列表底部新增一个item

bool	addItems (const QVariantList &datas)
	一次性在列表底部新增多个item

bool	insertItem (int index, const QVariant &data)
	在指定行处新增一个item

bool	insertItems (int index, const QVariantList &datas)
	在指定行处新增多个item

bool	removeItem (int index)
	移除指定位置的item

bool	removeItems (int index, int count)
	一次移除多个item

int	addHeaderWidget (QWidget *widget)
	此函数用于添加顶部小控件. 与 DListView::getHeaderWidget 类似，但返回要移除的顶部控件的对象.

void	removeHeaderWidget (int index)
	此函数用于移除头部控件小控件.

QWidget *	takeHeaderWidget (int index)
	此函数用于移除头部小控件并返回该控件.

int	addFooterWidget (QWidget *widget)
	此函数用于添加底层页脚小控件.

void	removeFooterWidget (int index)
	此函数用于移除底层页脚控件.

QWidget *	takeFooterWidget (int index)
	移除底层页脚控件并返回该控件.

void	setOrientation (QListView::Flow flow, bool wrapping)
	此函数用于设置 DListView 的方向.

void	edit (const QModelIndex &index)
	开始编辑一个item.

void	setBackgroundType (DStyledItemDelegate::BackgroundType backgroundType)
	设定item的背景色类型.

void	setItemMargins (const QMargins &itemMargins)
	设定item的内容margin.

void	setItemSize (QSize itemSize)
	设定item的尺寸.

void	setItemSpacing (int spacing)
	设定item的间距大小.

void	setItemRadius (int radius)
	设定item的圆角大小.

信号
void	rowCountChanged ()

void	orientationChanged (Qt::Orientation orientation)

void	currentChanged (const QModelIndex &previous)
	这个信号当当前item发生改变时被调用

void	triggerEdit (const QModelIndex &index)
	这个信号当有新的item被编辑时被调用

Public 成员函数
	DListView (QWidget *parent=0)
	获取一个 DListView 实例

State	state () const
	获取控件当前的状态控件可以有正在被拖拽，正在被编辑，正在播放动画等状态，详细可以查阅：QAbstractItemView::State

QWidget *	getHeaderWidget (int index) const
	获取一个顶部控件

QWidget *	getFooterWidget (int index) const
	获取一个底部控件

bool	isActiveRect (const QRect &rect) const
	return true if rect intersects contentsVisualRect+qMax(cacheBuffer,cacheCount)

bool	isVisualRect (const QRect &rect) const
	与 DListView::isVisualRect 相同

int	count () const

Qt::Orientation	orientation () const

void	setModel (QAbstractItemModel *model) Q_DECL_OVERRIDE
	设置 DListView 要使用的模型

QSize	minimumSizeHint () const Q_DECL_OVERRIDE

DStyledItemDelegate::BackgroundType	backgroundType () const

QMargins	itemMargins () const

QSize	itemSize () const

Protected 成员函数
void	setViewportMargins (int left, int top, int right, int bottom)

void	setViewportMargins (const QMargins &margins)

QMargins	viewportMargins () const

void	resizeEvent (QResizeEvent *event) Q_DECL_OVERRIDE

void	currentChanged (const QModelIndex &current, const QModelIndex &previous) Q_DECL_OVERRIDE

bool	edit (const QModelIndex &index, EditTrigger trigger, QEvent *event) Q_DECL_OVERRIDE

void	initViewItemOption (QStyleOptionViewItem *option) const override

virtual QModelIndex	moveCursor (CursorAction cursorAction, Qt::KeyboardModifiers modifiers) override

QSize	viewportSizeHint () const override

int	horizontalOffset () const override

属性
int	count
	item count.

Qt::Orientation	orientation
	list layout orientation

DStyledItemDelegate::BackgroundType	backgroundType

QMargins	itemMargins

QSize	itemSize

详细描述

DListView 一个用于展示一列数据的控件.

DListView 类似与 QListView 属于 Qt's model/view framework 的一个类，常被用来展示一列数据，当数据较多时可以滚动控件以显示跟多内容。但与 QListView 也有不同之处，DListView 提供了顶部控件和底部控件，它们始终显示在listview中，不会因为滚动而不可见，另外还提供了方便编辑数据的方法，如：addItem , addItems , insertItem , takeItem , removeItem , 以及一些开发中常用的信号。

DListView 示例

通过简单的示例来学习如何使用 DListView

CMakeLists.txt

cmake_minimum_required(VERSION 3.1.0) # 指定cmake最低版本
 
project(example1 VERSION 1.0.0 LANGUAGES CXX) # 指定项目名称, 版本, 语言 cxx就是c++
 
set(CMAKE_CXX_STANDARD 11) # 指定c++标准
set(CMAKE_CXX_STANDARD_REQUIRED ON) # 指定c++标准要求,至少为11以上
set(target example1) # 指定目标名称
 
set(CMAKE_AUTOMOC ON) # support qt moc # 支持qt moc
set(CMAKE_AUTORCC ON) # support qt resource file # 支持qt资源文件
set(CMAKE_AUTOUIC ON) # support qt ui file # 支持qt ui文件(非必须)
 
set(CMAKE_EXPORT_COMPILE_COMMANDS ON) # support clangd 支持 clangd
 
if (CMAKE_VERSION VERSION_LESS "3.7.0") # 如果cmake版本小于3.7.0
    set(CMAKE_INCLUDE_CURRENT_DIR ON) # 设置包含当前目录
endif()
 
find_package(Qt5 COMPONENTS Widgets REQUIRED) # 寻找Qt5组件Widgets
find_package(Qt5 COMPONENTS Gui  REQUIRED) # 寻找Qt5组件Gui
find_package(Dtk COMPONENTS Widget REQUIRED) # 寻找Dtk组件Widget
find_package(Dtk COMPONENTS Core REQUIRED) # 寻找Dtk组件Core
find_package(Dtk COMPONENTS Gui) # 寻找Dtk组件Gui
 
add_executable(example1     # 添加可执行文件
        main.cpp
)
 
target_link_libraries(example1 PRIVATE
    Qt5::Widgets
    Qt5::Gui
    ${DtkGui_LIBRARIES}
    ${DtkCore_LIBRARIES}
    ${DtkWidget_LIBRARIES}
) # 链接库

main.cpp

#include <DApplication>
#include <DListView>
#include <DMainWindow>
#include <DWidget>
#include <DStyle>
#include <DHeaderView>
#include <QStyle>
#include <QLabel>
 
DWIDGET_USE_NAMESPACE
 
int main(int argc, char *argv[]){
    DApplication app(argc, argv);
    DMainWindow win;
 
    //新建一个标准模型
    QStandardItemModel *model = new QStandardItemModel();
 
    //写一个函数，函数的功能是新建显示在窗口中的条目，条目内容，设置不可编辑以及将条目添加到model中
    auto AddItems = [&win, &model](QIcon icon, QString name){
        DStandardItem *item = new DStandardItem(icon, name); //条目包含图标和名称
        item->setEditable(false); //设置条目不可被编辑
        model->appendRow(item); //将条目添加到model中
        return item;
    };
 
    //调用函数新建四个条目
    auto item0 = AddItems(win.style()->standardIcon(DStyle::SP_ComputerIcon), "电脑");
    auto item1 = AddItems(win.style()->standardIcon(DStyle::SP_DirIcon), "文件");
    auto item2 = AddItems(win.style()->standardIcon(DStyle::SP_DriveCDIcon), "媒体");
    auto item3 = AddItems(win.style()->standardIcon(DStyle::SP_TrashIcon), "回收站");
 
    //增加一个条目中的action， 可用作标识、与其他条目区别开，设置位置、大小、是否可点击
    DViewItemAction *action = new DViewItemAction(Qt::AlignCenter, QSize(), QSize(), true);
    //将QStyle转为DStyle
    DStyle *style = qobject_cast<DStyle *>(win.style());
    //给action设置图标
    action->setIcon(style->standardIcon(DStyle::SP_IndicatorChecked));
    //设置显示到哪个条目上，这里设置到item1
    item1->setActionList(Qt::Edge::RightEdge, {action});
 
    //新建一个 dlistview
    DListView *listview = new DListView();
    //将上面设置好的模型加载到listview中
    listview->setModel(model);
    //设置 listview 背景颜色的样式
    listview->setBackgroundType(DStyledItemDelegate::BackgroundType::RoundedBackground);
 
    //新建一个header模型
    QStandardItemModel *hmodel = new QStandardItemModel();
    //设置header内容
    hmodel->setHorizontalHeaderLabels({"功能", "最后打开时间"});
    //新建一个headerview
    DHeaderView *headerview = new DHeaderView(Qt::Horizontal);
    //将模型加载到headerview
    headerview->setModel(hmodel);
    //设置headerview高度最大值
    headerview->setMaximumHeight(36);
    //设置 headerview 调整尺寸方式，此处设为随窗口尺寸变化
    headerview->setSectionResizeMode(DHeaderView::Stretch);
    //将headerview添加到listview
    listview->addHeaderWidget(headerview);
 
    //为footer设置一个标签
    QLabel *label = new QLabel("共四项内容"); 
    //设置标签居中显示
    label->setAlignment(Qt::AlignCenter);
    //将标签添加到footer
    listview->addFooterWidget(label);
 
    //将 listview 放入主窗口
    win.setCentralWidget(listview);
 
    win.resize(500,350);
    win.show();
    return app.exec();
}

上述代码中 setBackgroundType 中的参数为枚举类型，其他的枚举值为 BackgroundType_Mask, ClipCornerBackground, NoBackground, NoNormalState, 可以更改代码中枚举值查看效果

依次使用如下命令编译和运行程序

cmake -B build
cmake --build build
./build/example1

程序运行效果如下：

dlistview_example

构造及析构函数说明

◆ DListView()

DListView::DListView ( QWidget * parent = 0 )

explicit

获取一个 DListView 实例

参数

[in] parent 被用来作为 DListView 实例的父控件

成员函数说明

◆ addFooterWidget

int DListView::addFooterWidget ( QWidget * widget )

slot

此函数用于添加底层页脚小控件.

参数

[in] widget 底层页脚控件实例.

返回: 成功添加返回对应的索引值，如果已存在，则返回对应的索引值。

参见: DListView::getFooterWidget

◆ addHeaderWidget

int DListView::addHeaderWidget ( QWidget * widget )

slot

此函数用于添加顶部小控件. 与 DListView::getHeaderWidget 类似，但返回要移除的顶部控件的对象.

参数

[in] widget 头部控件实例.

返回: 成功添加返回添加进 DListView 的索引值，已存在返回对应控件的索引值.

参见: DListView::getHeaderWidget

◆ addItem

bool DListView::addItem ( const QVariant & data )

slot

在列表底部新增一个item

参数

[in] data 要新增的数据

返回: 返回是否新增成功

◆ addItems

bool DListView::addItems ( const QVariantList & datas )

slot

一次性在列表底部新增多个item

参数

[in] datas 要新增的数据组成的列表

返回: 是否新增成功

◆ currentChanged

void DListView::currentChanged ( const QModelIndex & previous )

signal

这个信号当当前item发生改变时被调用

listview会有一个始终表示当前item索引的 QModelIndex 对象，当这个 QModelIndex 对象表示的位置发生改变时这个信号才会被调用，而不是当前item的内容发生改变时。当鼠标单机某一个item或者使用键盘切换item时，

参数

[in] previous 为之前的item的索引对象

参见: QModelIndex QListView::currentChanged

◆ edit

void DListView::edit ( const QModelIndex & index )

slot

开始编辑一个item.

参数

[in] index 指定要编辑的item的位置

◆ getFooterWidget()

QWidget * DListView::getFooterWidget ( int index ) const

获取一个底部控件

参数

[in] index 指定要获取的底部控件的索引

返回: 返回在指定索引处的底部控件对象

参见: DListView::getHeaderWidget

◆ getHeaderWidget()

QWidget * DListView::getHeaderWidget ( int index ) const

获取一个顶部控件

顶部控件与item一样都会在listview中被显示出来，而且顶部控件会始终在所有item之上，也就是说顶部控件与item不同的地方在于顶部控件始终显示在布局中，而不会因为鼠标滚动不可见。另外顶部控件可以有多个，它们的布局方式(方向)与item的布局方向相同

参数

[in] index 指定要获取的顶部控件的索引

返回: 返回在指定索引处的顶部控件对象

注解: 注意顶部控件并不是像 GridLayout 的表头，表头是始终在水平方向上布局的

参见: DListView::getFooterWidget DListView::addHeaderWidget DListView::removeHeaderWidget DListView::takeHeaderWidget

◆ initViewItemOption()

void Dtk::Widget::DListView::initViewItemOption ( QStyleOptionViewItem * option ) const

overrideprotected

\reimp

◆ insertItem

bool DListView::insertItem	(	int	index,
		const QVariant &	data
	)

slot

在指定行处新增一个item

参数

[in]	index	要增加item的行号
[in]	data	要增加的item的数据

返回: 是否新增成功

◆ insertItems

bool DListView::insertItems	(	int	index,
		const QVariantList &	datas
	)

slot

在指定行处新增多个item

参数

[in]	index	要增加item的行号
[in]	datas	要增加的items的数据组成的列表

返回: 是否新增成功

◆ isActiveRect()

bool DListView::isActiveRect ( const QRect & rect ) const

return true if rect intersects contentsVisualRect+qMax(cacheBuffer,cacheCount)

判断给定的 QRect 是否与 listview 的item可显示区域有重叠

listview 的item可显示区域即为 listview 的 viewport ， items只能在 viewport 显示，超出这一区域的 item 将不可见。

参数

[in] rect 要对比的 QRect

返回: 返回两个矩形是否有重叠区域

参见: DListView::isVisualRect

◆ isVisualRect()

bool DListView::isVisualRect ( const QRect & rect ) const

与 DListView::isVisualRect 相同

参数

[in] rect 用于判断的位置矩形.

返回: 成功包含矩形返回 true，否则返回 false.

参见: DListView::isVisualRect

◆ orientationChanged

void DListView::orientationChanged ( Qt::Orientation orientation )

signal

参数

[in] orientation 改变的方向值.

参见: DListView::orientation

◆ removeFooterWidget

void DListView::removeFooterWidget ( int index )

slot

此函数用于移除底层页脚控件.

参数

[in] index 添加进 DListView 中底层页脚控件的索引值，是 DListView::addFooterWidget 的返回值.

参见: DListView::addFooterWidget

◆ removeHeaderWidget

void DListView::removeHeaderWidget ( int index )

slot

此函数用于移除头部控件小控件.

参数

[in] index 添加进 DListView 中头部小控件的索引值，是 DListView::addHeaderWidget 的返回值.

参见: DListView::addFooterWidget

◆ removeItem

bool DListView::removeItem ( int index )

slot

移除指定位置的item

参数

[in] index 要移除的item的行号

返回: 是否移除成功

◆ removeItems

bool DListView::removeItems	(	int	index,
		int	count
	)

slot

一次移除多个item

参数

[in]	index	开始移除item的行号
[in]	count	移除从 index 指定的行号开始，移除 count 个item

返回: 返回是否移除成功

◆ rowCountChanged

void DListView::rowCountChanged ( )

signal

参见: DListView::count

◆ setBackgroundType

void DListView::setBackgroundType ( DStyledItemDelegate::BackgroundType backgroundType )

slot

设定item的背景色类型.

参数

[in] backgroundType 背景色类型

◆ setItemMargins

void DListView::setItemMargins ( const QMargins & itemMargins )

slot

设定item的内容margin.

参数

[in] itemMargins margin值

◆ setItemRadius

void DListView::setItemRadius ( int radius )

slot

设定item的圆角大小.

参数

[in] radius 圆角大小值

◆ setItemSize

void DListView::setItemSize ( QSize itemSize )

slot

设定item的尺寸.

参数

[in] itemSize 尺寸的大小

◆ setItemSpacing

void DListView::setItemSpacing ( int spacing )

slot

设定item的间距大小.

参数

[in] spacing　间距大小值

◆ setModel()

void DListView::setModel ( QAbstractItemModel * model )

设置 DListView 要使用的模型

模型用来为 listview 提供数据，以实现数据层与界面层分离的结构, 详细请查阅 Qt's model/view framework

参数

[in] model 模型对象

参见: QListView::setModel

◆ setOrientation

void DListView::setOrientation	(	QListView::Flow	flow,
		bool	wrapping
	)

slot

此函数用于设置 DListView 的方向.

参数

[in]	flow	为 DListView 的方向，有 QListView::Flow::LeftToRight 和 QListView::Flow::TopToBottom 两个值。
[in]	wrapping	用于控制项布局是否自动换行，true 表示自动换行，false 表示非自动换行。

参见: DListView::orientation

◆ state()

QAbstractItemView::State DListView::state ( ) const

获取控件当前的状态控件可以有正在被拖拽，正在被编辑，正在播放动画等状态，详细可以查阅：QAbstractItemView::State

返回: 控件当前的状态

参见: QAbstractItemView::State

◆ takeFooterWidget

QWidget * DListView::takeFooterWidget ( int index )

slot

移除底层页脚控件并返回该控件.

参数

[in] index 添加进 DListView 中底层页脚控件的索引值，是 DListView::addFooterWidget 的返回值.

参见: DListView::getFooterWidget DListView::takeHeaderWidget

◆ takeHeaderWidget

QWidget * DListView::takeHeaderWidget ( int index )

slot

此函数用于移除头部小控件并返回该控件.

与 DListView::getHeaderWidget 类似，但返回要移除的顶部控件的对象

参数

[in] index 添加进 DListView 中头部小控件的索引值，是 DListView::addHeaderWidget 的返回值.

返回: 成功移除返回获取到的头部小控件，否则返回 nullptr .

参见: DListView::getHeaderWidget

◆ triggerEdit

void DListView::triggerEdit ( const QModelIndex & index )

signal

这个信号当有新的item被编辑时被调用

参数

[in] index 为正在编辑的item的索引对象

参见: QModelIndex QAbstractItemView::EditTrigger

属性说明

◆ count

DListView::count

read

item count.

这个属性保存共有多少行数据

Getter: DListView::count , Signal: DListView::rowCountChanged

◆ orientation

DListView::orientation

read

list layout orientation

这个属性保存listview中item的布局方式

Getter: DListView::orientation , Setter: DListView::setOrientation , Signal: DListView::orientationChanged

参见: Qt::Orientation

该类的文档由以下文件生成:

include/widgets/dlistview.h
src/widgets/dlistview.cpp
docs/widgets/dlistview.zh_CN.dox

Public 槽

信号

Public 成员函数

Protected 成员函数

属性

详细描述

DListView 示例

CMakeLists.txt

main.cpp

构造及析构函数说明

◆ DListView()

成员函数说明

◆ addFooterWidget

◆ addHeaderWidget

◆ addItem

◆ addItems

◆ currentChanged

◆ edit

◆ getFooterWidget()

◆ getHeaderWidget()

◆ initViewItemOption()

◆ insertItem

◆ insertItems

◆ isActiveRect()

◆ isVisualRect()

◆ orientationChanged

◆ removeFooterWidget

◆ removeHeaderWidget

◆ removeItem

◆ removeItems

◆ rowCountChanged

◆ setBackgroundType

◆ setItemMargins

◆ setItemRadius

◆ setItemSize

◆ setItemSpacing

◆ setModel()

◆ setOrientation

◆ state()

◆ takeFooterWidget

◆ takeHeaderWidget

◆ triggerEdit

属性说明

◆ count

◆ orientation