Collections

Timeline

Presents caller-owned model rows as a timeline with text, time labels and node states.

Example

Usage

Model-backed timeline

The application supplies text, time labels and node states. Click the button to see a state transition.

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

auto* timeline = new Timeline(this);
auto* model = new QStandardItemModel(3, 1, this);
for (int i = 0; i < 3; ++i) {
    model->setData(model->index(i, 0), QString("Node %1").arg(i + 1));
    model->setData(model->index(i, 0), "Optional supporting content supplied by the application.", Timeline::DescriptionRole);
    model->setData(model->index(i, 0), QString("Time label %1").arg(i + 1), Timeline::TimestampRole);
}
model->setData(model->index(1, 0), Timeline::Active, Timeline::StatusRole);
timeline->setModel(model);
connect(changeState, &Button::clicked, model, [model] {
    const auto index = model->index(1, 0);
    model->setData(index, model->data(index, Timeline::StatusRole).toInt() == Timeline::Active
        ? Timeline::Success : Timeline::Active, Timeline::StatusRole);
});

import fluentqt

from PySide6.QtGui import QStandardItemModel

timeline = fluentqt.Timeline()
roles = fluentqt.Timeline.DataRole
states = fluentqt.Timeline.Status
model = QStandardItemModel(3, 1, root)
detail = 'Optional supporting content supplied by the application.'
for i in range(3):
    index = model.index(i, 0)
    model.setData(index, f'Node {i + 1}')
    model.setData(index, detail, roles.DescriptionRole)
    model.setData(
        index,
        f'Time label {i + 1}',
        roles.TimestampRole
    )
model.setData(model.index(1, 0), states.Active, roles.StatusRole)
timeline.setModel(model)
change = fluentqt.Button('Change node state')
def change_state():
    index = model.index(1, 0)
    active = index.data(roles.StatusRole) == states.Active
    state = states.Success if active else states.Active
    model.setData(index, state, roles.StatusRole)
change.clicked.connect(change_state)

API

Declaration

`fluent::collections::Timeline`

Inherits ListView

Model-backed timeline with reusable Fluent scrolling, input and theme behavior.

Constructors

explicit Timeline(QWidget* parent = nullptr)

Properties

NodeAlignment nodeAlignment: Read nodeAlignment()Write setNodeAlignment()Notify nodeAlignmentChanged()
bool animationEnabled: Read isAnimationEnabled()Write setAnimationEnabled()Notify animationEnabledChanged()

Methods

void setModel(QAbstractItemModel* model) override: Borrows a model without changing its parent or data.
NodeAlignment nodeAlignment() const
void setNodeAlignment(NodeAlignment alignment)
bool isAnimationEnabled() const
void setAnimationEnabled(bool enabled)

Signals

void nodeAlignmentChanged(NodeAlignment alignment)
void animationEnabledChanged(bool enabled)

Enumerations

enum NodeAlignment: Logical placement of the timeline rail.
Leading
Trailing
Alternate
enum Status: Node presentation independent of selection.
Neutral
Active
Success
Warning
Error
enum DataRole: Optional description, timestamp label and status roles.
DescriptionRole = Qt::UserRole + 1
TimestampRole
StatusRole

Destructors

~Timeline() override

PySide6 additions

setItemDelegate(delegate)

Subclass interfaces

Methods

void dataChanged(const QModelIndex& topLeft, const QModelIndex& bottomRight, const QVector<int>& roles = QVector<int>()) override
void resizeEvent(QResizeEvent* event) override
void hideEvent(QHideEvent* event) override
void scrollContentsBy(int dx, int dy) override
void changeEvent(QEvent* event) 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)