Collections

FileListView

A model-backed file list with complete names, transfer progress, and recovery actions.

Example

Usage

Files and progress

Example transfer states. Remove a file, retry a failed transfer, or advance the progress.

#include <FluentQt/Collections.h>
using namespace fluent::collections;

auto* panel = new QWidget(this);
panel->setMaximumWidth(720);
auto* layout = new QVBoxLayout(panel);
layout->setContentsMargins(0, 0, 0, 0);
layout->setSpacing(16);
auto* model = new QStandardItemModel(panel);
auto addFile = [model](const QString& name, const QString& detail,
                       FileListView::Status state, qreal progress) {
    auto* item = new QStandardItem(name);
    item->setData(detail, FileListView::MetadataRole);
    item->setData(state, FileListView::StatusRole);
    item->setData(progress, FileListView::ProgressRole);
    item->setData(state == FileListView::Rejected, FileListView::RetryableRole);
    model->appendRow(item);
};
addFile("brand-guidelines.pdf", "2.4 MB · Ready to use", FileListView::Ready, 1.0);
addFile("product-shot.png", "3.6 / 5.8 MB · Uploading", FileListView::Uploading, 0.62);
addFile("research-notes-for-the-autumn-product-release-and-accessibility-review.pdf",
        "Connection lost · Retry when you are ready", FileListView::Rejected, 0.0);
auto* files = new FileListView(panel);
files->setObjectName("fileList");
files->setAccessibleName("Transfer examples");
files->setMinimumHeight(240);
files->setBackgroundVisible(false);
files->setBorderVisible(false);
files->setProperty("fluentPreserveParentSurface", true);
files->viewport()->setProperty("fluentPreserveParentSurface", true);
files->setModel(model);
layout->addWidget(files);
QObject::connect(files, &FileListView::removeRequested, panel,
                 [model](const QModelIndex& index) { model->removeRow(index.row()); });
QObject::connect(files, &FileListView::retryRequested, panel,
                 [model](const QModelIndex& index) {
    model->setData(index, FileListView::Uploading, FileListView::StatusRole);
    model->setData(index, false, FileListView::RetryableRole);
    model->setData(index, "Reconnected · Uploading", FileListView::MetadataRole);
    model->setData(index, 0.0, FileListView::ProgressRole);
});
auto* advance = new Button("Advance example transfers", panel);
advance->setObjectName("advanceTransfer");
advance->setFluentStyle(Button::Subtle);
QObject::connect(advance, &Button::clicked, panel, [model]() {
    for (int row = 0; row < model->rowCount(); ++row) {
        const QModelIndex index = model->index(row, 0);
        if (index.data(FileListView::StatusRole).toInt() != FileListView::Uploading)
            continue;
        const qreal progress = qMin(1.0, index.data(FileListView::ProgressRole).toReal() + 0.19);
        model->setData(index, progress, FileListView::ProgressRole);
        model->setData(index, progress >= 1.0 ? "Ready to use" : "Uploading",
                       FileListView::MetadataRole);
        if (progress >= 1.0)
            model->setData(index, FileListView::Ready, FileListView::StatusRole);
    }
});
layout->addWidget(advance, 0, Qt::AlignLeft);

import fluentqt

from PySide6.QtCore import Qt
from PySide6.QtGui import QStandardItem, QStandardItemModel
from PySide6.QtWidgets import QVBoxLayout, QWidget

panel = QWidget()
layout = QVBoxLayout(panel)
layout.setContentsMargins(0, 0, 0, 0)
layout.setSpacing(24)
model = QStandardItemModel(panel)
roles = fluentqt.FileListView.DataRole
states = fluentqt.FileListView.Status

def add_file(name, detail, state, progress):
    item = QStandardItem(name)
    item.setData(detail, roles.MetadataRole)
    item.setData(state, roles.StatusRole)
    item.setData(progress, roles.ProgressRole)
    model.appendRow(item)

add_file("brand-guidelines.pdf", "2.4 MB · Ready to use", states.Ready, 1.0)
add_file("product-shot.png", "3.6 / 5.8 MB · Uploading", states.Uploading, 0.62)
add_file(
    "research-notes-for-the-autumn-product-release-and-accessibility-review.pdf",
    "Connection lost · Retry when you are ready",
    states.Rejected,
    0.0
)
model.item(2).setData(True, roles.RetryableRole)

files = fluentqt.FileListView(panel)
files.setObjectName("selectedFiles")
files.setAccessibleName("Selected files")
files.setBackgroundVisible(False)
files.setBorderVisible(False)
files.setProperty("fluentPreserveParentSurface", True)
files.viewport().setProperty("fluentPreserveParentSurface", True)
files.setMinimumHeight(260)
files.setModel(model)
layout.addWidget(files)
files.removeRequested.connect(lambda index: model.removeRow(index.row()))

panel.setMaximumWidth(720)
layout.setSpacing(16)
files.setObjectName("fileList")
files.setAccessibleName("Transfer examples")
files.setMinimumHeight(240)

def retry(index):
    model.setData(index, states.Uploading, roles.StatusRole)
    model.setData(index, False, roles.RetryableRole)
    model.setData(
        index,
        "Reconnected · Uploading",
        roles.MetadataRole
    )
    model.setData(index, 0.0, roles.ProgressRole)

files.retryRequested.connect(retry)
advance = fluentqt.Button("Advance example transfers", panel)
advance.setObjectName("advanceTransfer")
advance.setFluentStyle(fluentqt.Button.ButtonStyle.Subtle)

def advance_transfers():
    for row in range(model.rowCount()):
        index = model.index(row, 0)
        if index.data(roles.StatusRole) != states.Uploading:
            continue
        progress = min(1.0, float(index.data(roles.ProgressRole)) + 0.19)
        model.setData(index, progress, roles.ProgressRole)
        model.setData(
            index,
            "Ready to use" if progress >= 1 else "Uploading",
            roles.MetadataRole
        )
        if progress >= 1:
            model.setData(index, states.Ready, roles.StatusRole)

advance.clicked.connect(advance_transfers)
layout.addWidget(advance, 0, Qt.AlignmentFlag.AlignLeft)

API

Declaration

`fluent::collections::FileListView`

Inherits ListView

Presents file names, transfer status, and commands from a caller-owned model.

Constructors

explicit FileListView(QWidget* parent = nullptr)

Properties

bool animationEnabled: Read isAnimationEnabled()Write setAnimationEnabled()Notify animationEnabledChanged()

Methods

void setModel(QAbstractItemModel* model) override: Borrows a model without reparenting or modifying it.
bool isAnimationEnabled() const
void setAnimationEnabled(bool enabled): Enables short hover and progress transitions, subject to MotionPolicy.

Signals

void animationEnabledChanged(bool enabled)
void removeRequested(const QModelIndex& index): Requests removal; the application decides whether to change its model.
void retryRequested(const QModelIndex& index): Requests retry without starting a transfer or changing file status.

Enumerations

enum Status: File presentation status; transfer work remains application-owned.
Ready = 0
Uploading = 1
Rejected = 2
enum DataRole: Model roles used by the file delegate, in addition to Qt::DisplayRole.
MetadataRole = Qt::UserRole + 1
StatusRole
ProgressRole
RemovableRole
RetryableRole

Destructors

~FileListView() override

Subclass interfaces

Methods

void dataChanged(const QModelIndex& topLeft, const QModelIndex& bottomRight, const QVector<int>& roles = QVector<int>()) override
void mousePressEvent(QMouseEvent* event) override
void mouseMoveEvent(QMouseEvent* event) override
void mouseReleaseEvent(QMouseEvent* event) override
void keyPressEvent(QKeyEvent* event) override
void leaveEvent(QEvent* event) override
void resizeEvent(QResizeEvent* event) override
void hideEvent(QHideEvent* event) override
bool event(QEvent* event) override
void scrollContentsBy(int dx, int dy) override
void onThemeUpdated() override

Inherited from fluent::collections::ListView

Properties

SelectionMode selectionMode: Selection mode used by the collection view.
Read selectionMode()Write setSelectionMode()Notify selectionModeChanged()
Typography::FontRole fontRole: Fluent typography role used for text rendering.
Read fontRole()Write setFontRole()Notify fontRoleChanged()
int trailingTextRole: Optional model role for trailing secondary text; -1 hides it.
Read trailingTextRole()Write setTrailingTextRole()Notify trailingTextRoleChanged()
bool viewportHovered: Whether the item-view viewport is currently hovered.
Read viewportHovered()Notify viewportHoveredChanged()
Flow flow: List flow direction used by the underlying item view.
Read flow()Write setFlow()Notify flowChanged()
qreal selectedIndicatorProgress: Animated progress for the selected-item indicator.
Read selectedIndicatorProgress()Notify selectedIndicatorProgressChanged()
IndicatorMotionDirection selectedIndicatorMotionDirection: Direction used by selected-indicator motion.
Read selectedIndicatorMotionDirection()Notify selectedIndicatorMotionDirectionChanged()
bool selectedIndicatorAnimationEnabled: Whether selected-indicator animation is enabled.
Read selectedIndicatorAnimationEnabled()Write setSelectedIndicatorAnimationEnabled()Notify selectedIndicatorAnimationEnabledChanged()
bool selectionIndicatorVisible: Whether the selected-item indicator is painted.
Read selectionIndicatorVisible()Write setSelectionIndicatorVisible()Notify selectionIndicatorVisibleChanged()
bool borderVisible: Whether the control frame border is painted.
Read borderVisible()Write setBorderVisible()Notify borderVisibleChanged()
bool backgroundVisible: Whether the control background is painted.
Read backgroundVisible()Write setBackgroundVisible()Notify backgroundVisibleChanged()
QWidget* header: Custom widget hosted in the ListView header area.
Read header()Write setHeader()Notify headerChanged()
QWidget* footer: Custom widget hosted in the ListView footer area.
Read footer()Write setFooter()Notify footerChanged()
QString headerText: Convenience text displayed in the header area.
Read headerText()Write setHeaderText()Notify headerTextChanged()
QString footerText: Convenience text displayed in the footer area.
Read footerText()Write setFooterText()Notify footerTextChanged()
QString placeholderText: Text shown when the model has no rows to present.
Read placeholderText()Write setPlaceholderText()Notify placeholderTextChanged()
bool canReorderItems: Whether drag reordering is enabled.
Read canReorderItems()Write setCanReorderItems()Notify canReorderItemsChanged()
bool scrollChainingEnabled: Whether boundary wheel input may continue to an enclosing scroller.
Read isScrollChainingEnabled()Write setScrollChainingEnabled()Notify scrollChainingEnabledChanged()
bool sectionEnabled: Whether section headers are enabled for grouped rows.
Read sectionEnabled()Write setSectionEnabled()Notify sectionEnabledChanged()

Methods

void setModel(QAbstractItemModel* model) override
void setSelectionModel(QItemSelectionModel* selectionModel) override
Flow flow() const: List flow direction used by the underlying item view.
void setFlow(Flow flow): List flow direction used by the underlying item view.
SelectionMode selectionMode() const: --- Selection ---
void setSelectionMode(SelectionMode mode): Selection mode used by the collection view.
Typography::FontRole fontRole() const: --- Appearance ---
void setFontRole(Typography::FontRole role): Fluent typography role used for text rendering.
int trailingTextRole() const: Optional model role for trailing secondary text; -1 hides it.
void setTrailingTextRole(int role): Sets the role used by the default delegate; custom delegates remain caller-owned.
bool borderVisible() const: Whether the control frame border is painted.
bool isBorderVisible() const
void setBorderVisible(bool visible): Whether the control frame border is painted.
bool backgroundVisible() const: Whether the control background is painted.
bool isBackgroundVisible() const
void setBackgroundVisible(bool visible): Whether the control background is painted.
QWidget* header() const: --- Header / Footer (custom widget API) ---
void setHeader(QWidget* widget): Custom widget hosted in the ListView header area.
QWidget* footer() const: Custom widget hosted in the ListView footer area.
void setFooter(QWidget* widget): Custom widget hosted in the ListView footer area.
QString headerText() const: --- Header / Footer (convenience text API) ---
void setHeaderText(const QString& text): Convenience text displayed in the header area.
QString footerText() const: Convenience text displayed in the footer area.
void setFooterText(const QString& text): Convenience text displayed in the footer area.
QString placeholderText() const: Text shown when the model has no rows to present.
void setPlaceholderText(const QString& text): Text shown when the model has no rows to present.
bool viewportHovered() const: Whether the item-view viewport is currently hovered.
bool isViewportHovered() const
bool canReorderItems() const: --- Drag reorder ---
void setCanReorderItems(bool enabled): Whether drag reordering is enabled.
bool isScrollChainingEnabled() const: Whether boundary wheel input may continue to an enclosing scroller.
void setScrollChainingEnabled(bool enabled): Whether boundary wheel input may continue to an enclosing scroller.
bool sectionEnabled() const: Whether section headers are enabled for grouped rows.
bool isSectionEnabled() const
void setSectionEnabled(bool enabled): Whether section headers are enabled for grouped rows.
void setSectionKeyFunction(SectionKeyFunc func): 设置分组 key 回调。相邻行返回相同 key 的归为一组，key 作为 section header 绘制。
int selectedIndex() const: --- Selection API ---
QList<int> selectedRows() const
void setSelectedIndex(int index)
qreal selectedIndicatorProgress() const: --- Selected indicator motion API ---
IndicatorMotionDirection selectedIndicatorMotionDirection() const: Direction used by selected-indicator motion.
bool selectedIndicatorAnimationEnabled() const: 控制 selected indicator 过渡动画；关闭后选择变更直接落到目标几何，便于确定性测试。
bool isSelectedIndicatorAnimationEnabled() const
void setSelectedIndicatorAnimationEnabled(bool enabled): Whether selected-indicator animation is enabled.
bool selectionIndicatorVisible() const: Returns whether the selected-item indicator is painted.
void setSelectionIndicatorVisible(bool visible): Shows or hides the indicator without changing selection semantics.
QRectF selectedIndicatorRect() const: 返回当前绘制用的 selected indicator viewport 几何；无可见选中项时为空。
QRectF selectedIndicatorRect(qreal progress) const: 返回指定归一化进度下的 selected indicator viewport 几何，供自动化测试验证过渡轨迹。
QRectF selectedIndicatorRectForRow(int row) const: 返回指定行的 selected indicator viewport 几何；多选模式用于验证每个选中项自己的 reveal 指示器。
QRectF selectedIndicatorRectForRow(int row, qreal progress) const
::fluent::scrolling::ScrollBar* verticalFluentScrollBar() const
::fluent::scrolling::ScrollBar* horizontalFluentScrollBar() const
void refreshFluentScrollChrome(): Suppresses the built-in scroll bars and refreshes the fluent ones.

Signals

void selectionModeChanged(): Selection mode used by the collection view.
void fontRoleChanged(): Fluent typography role used for text rendering.
void trailingTextRoleChanged(): Optional model role for trailing secondary text; -1 hides it.
void viewportHoveredChanged(): Whether the item-view viewport is currently hovered.
void flowChanged(): List flow direction used by the underlying item view.
void borderVisibleChanged(): Whether the control frame border is painted.
void backgroundVisibleChanged(): Whether the control background is painted.
void headerChanged(): Custom widget hosted in the ListView header area.
void footerChanged(): Custom widget hosted in the ListView footer area.
void headerTextChanged(): Convenience text displayed in the header area.
void footerTextChanged(): Convenience text displayed in the footer area.
void placeholderTextChanged(): Text shown when the model has no rows to present.
void canReorderItemsChanged(): Whether drag reordering is enabled.
void scrollChainingEnabledChanged(): Whether boundary wheel input may continue to an enclosing scroller.
void sectionEnabledChanged(): Whether section headers are enabled for grouped rows.
void selectedIndicatorProgressChanged(): Animated progress for the selected-item indicator.
void selectedIndicatorMotionDirectionChanged(): Direction used by selected-indicator motion.
void selectedIndicatorAnimationEnabledChanged(): Whether selected-indicator animation is enabled.
void selectionIndicatorVisibleChanged(): Whether the selected-item indicator is painted.
void itemClicked(int index): Emits the row once for the same pointer action as inherited clicked().
void itemReordered(int fromRow, int toRow)