Qt Quick中的项目视图

Item Views in Qt Quick

Qt Quick中的项目视图

September 09, 2022 by Richard Moe Gustavsen | Comments

2022年09月09日 由理查德·莫伊·古斯塔夫森

Introduction

介绍

A substantial amount of work has gone into improving TableView and TreeView in Qt 6.3 and 6.4, and more is also in the works. In this post I’ll give a quick overview over what has been done so far.

​Qt 6.3和6.4中的TableView和TreeView的改进已经投入了大量的工作，还有更多的工作正在进行中。在这篇文章中，我将简要介绍迄今为止所做的工作。

TreeView

TreeView was finally added to Qt Quick in Qt 6.3, after a short stay in Marketplace which caused some negative buzz. Understandably, most see it as an essential item view that naturally belongs together with the others, such as ListView, TableView and GridView. If nothing else, that delay gave us some time to revise the API, before the final version landed in Qt Quick.

TreeView最终在Qt 6.3中添加到Qt Quick中，在市场上短暂停留后，引起了一些负面影响。可以理解的是，大多数人将它视为一个基本项视图，它自然地和其他视图（如ListView、TableView和GridView）一起属于。如果没有其他原因的话，在最终版本登陆Qt Quick之前，延迟给了我们一些时间来修改API。

And the API changed quite a bit. While TreeView in Marketplace is an independent component with its own styling API, the version in Qt Quick is integrated with the styling API in Qt Quick Controls. It’s therefore split in two: the TreeView itself, which lives in Qt Quick together with the other item views, and a TreeViewDelegate, which lives in Qt Quick Controls. TreeView contains the API and the logic, but the drawing is outsourced to the TreeViewDelegate (or your own custom delegate, if you wish), and follows the application style.

​API也发生了很大的变化。虽然市场上的TreeView是一个独立组件，具有自己的样式API，但Qt Quick中的版本与Qt QuickControl中的样式API集成。因此，它分为两部分：TreeView本身，它与其他项目视图一起生活在Qt Quick中；TreeViewDelegate，它生活在QtQuick控件中。TreeView包含API和逻辑，但图形外包给TreeViewDelegate（或您自己的自定义委托，如果您愿意），并遵循应用程序样式。

TreeView inherits TableView. This means that anything you can do with a TableView, you can do with a TreeView (including e.g selection support and cell navigation - more on that below).
TreeView basically flattens the tree model into a table model internally, and offers an API that lets you map between table cells and tree model indices, or expand and collapse nodes. In Qt 6.4, support for expanding and collapsing nodes recursively has also been added.

​TreeView继承TableView。这意味着任何你可以用TableView做的事情，你都可以用TreeView做（包括例如选择支持和单元格导航-更多信息见下文）。
TreeView基本上在内部将树模型扁平化为表模型，并提供了一个API，允许您在表单元格和树模型索引之间进行映射，或者展开和折叠节点。在Qt 6.4中，还添加了对递归扩展和折叠节点的支持。

Selection support

选择支持

One of the long-missing features in TableView, that got implemented in Qt 6.3, was support for selecting cells. This means that you can now assign an ItemSelectionModel to TableView, which contains an API for creating and manipulating selections programmatically. Quick Controls has a styled SelectionRectangle, which lets you do standard mouse-drag selection, or alternatively, press-and-hold with selection handles on touch-based platforms. As of Qt 6.4, you can also set the selectionBehavior, to control whether the user should select individual cells, rows or columns.

​在Qt6.3中实现的TableView中长期缺少的一个特性是支持选择单元格。这意味着您现在可以将ItemSelectionModel分配给TableView，其中包含一个API，用于以编程方式创建和操作选择。Quick Controls有一个样式化的SelectionRectangle，它允许您进行标准的鼠标拖动选择，或者在基于触摸的平台上使用选择手柄按住。从Qt 6.4开始，您还可以设置selectionBehavior，以控制用户是否应选择单个单元格、行或列。

New in Qt 6.4 is also the possibility to move the currentIndex around, and select cells with the keyboard. A couple of new properties have been added, keyNavigationEnabled and pointerNavigationEnabled, in case your application needs to disable or override the default navigation behavior from QML.

​Qt 6.4中的新功能还可以移动当前索引，并使用键盘选择单元格。添加了两个新属性：keyNavigationEnabled和pointerNavigationEnabled，以防应用程序需要禁用或覆盖QML中的默认导航行为。

The rendering of a selection, as well as showing a cell as current, is left to the delegate. To know if a delegate is selected or current, you can simply add the properties selected and current to it, which TableView will then keep in sync with the ItemSelectionModel. Putting it all together, a QML snippet that lets you select cells could end up like this:

选择的渲染以及将单元格显示为当前单元格都留给委托。要知道委托是选定的还是当前的，您可以简单地向其添加属性selected和current，然后TableView将与ItemSelectionModel保持同步。将所有这些放在一起，可以选择单元格的QML片段可能会这样结束：

TableView {
    id: tableView
    selectionBehavior: TableView.SelectRows
    delegate: Rectangle {
        required property bool selected
        required property bool current
        color: selected || current ? “lightblue” : “white”
        Text { text: row + “, “ + column }
    }
}

SelectionRectangle { target: tableView }

Several other selection-related properties have also been added in Qt 6.4, like currentRow, currentColumn, and alternatingRows.

​Qt 6.4中还添加了其他一些与选择相关的属性，如currentRow、currentColumn和alternatingRows。

Positioning

定位

TableView has a function positionViewAtCell(point cell, PositionMode mode, point offset, rect subRect). It flicks the content item so that a specific cell becomes visible, based on the bounding rectangle of the whole cell. New in Qt 6.4 is that you can now also specify a fourth argument: subRect. This rect can be used to describe an area inside the cell that should be used, rather than its bounding rectangle. This is useful if you operate with really large cells, where a cell might be larger than the view itself, and you want to make sure that a specific part of the cell is shown inside the view. In PdfMultiPageView, for example, a page in the document gets rendered into a single cell in a TableView. And when you jump to a specific heading in the document, a subRect is used to make sure that the heading, rather than the whole page, ends up being aligned to the top of the view.

​TableView有一个函数positionViewAtCell（点单元格、位置模式、点偏移、矩形子矩形）。它轻拂内容项，以便根据整个单元格的边框显示特定单元格。Qt 6.4中的新功能是，现在还可以指定第四个参数：subRect。此矩形可用于描述单元格内应使用的区域，而不是其边界矩形。如果您使用非常大的单元进行操作，其中单元可能比视图本身大，并且您希望确保在视图中显示单元的特定部分，则这非常有用。例如，在PdfMultiPageView中，文档中的页面被呈现到表视图中的单个单元格中。当您跳转到文档中的特定标题时，子矩形用于确保标题而不是整个页面最终与视图顶部对齐。

In addition to the fourth argument, two new enum values have been added to PositionMode: Visible and Contain. Those can be used to flick the content item so that the cell ends up fully inside the view, if the cell is not considered to be inside already. The difference is when they consider a cell to be inside. With Visible, it’s enough that just a pixel of the cell is visible in the viewport. With Contain, the whole bounding rectangle must overlap. And only if the cell is not considered to be inside, will the content item be flicked.

除了第四个参数之外，还向PositionMode添加了两个新的枚举值：Visible和Contain。如果单元格不被认为已经在视图中，则可以使用它们来轻拂内容项，以使单元格完全在视图中结束。不同的是当他们认为一个细胞在里面时。使用“可见”，仅在视口中显示单元的一个像素就足够了。使用“包含”，整个边界矩形必须重叠。只有当单元格被认为不在内部时，才会轻拂内容项。

If you also specify a subRect, that rectangle will be used instead of the bounding rectangle, both to decide whether the cell is inside, and to flick so that only the sub rectangle will end up fully visible, and not necessarily the whole cell.

如果还指定了子矩形，则将使用该矩形而不是边界矩形，以确定单元格是否在内部，并轻弹以使只有子矩形最终完全可见，而不一定是整个单元格。

Further work

更进一步的工作

There is still quite some work left with item views in QML, to reach feature parity with widgets and completeness for desktop-centric UIs. The next task that we hope to have ready for Qt 6.5 is to implement support for resizing and reordering rows and columns by dragging on the cells in a HeaderView. We also hope to implement improved support for editing table cells, by offering an edit delegate property in TableView. And lastly, we aim to fix some minor issues in DelegateChooser, and move it out of Qt.labs into QtQuick.

 ​QML中的项目视图还有相当多的工作要做，以实现与widgets的功能对等性和以桌面为中心的UI的完整性。我们希望为Qt6.5准备的下一个任务是通过拖动HeaderView中的单元格来实现对行和列的大小调整和重新排序的支持。我们还希望通过在TableView中提供编辑委托属性来实现对编辑表单元格的改进支持。最后，我们的目标是修复DelegateChooser中的一些小问题，并将其移出Qt.labs到QtQuick中。