CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-pyqt-fluent-widgets

A fluent design widgets library based on PyQt5 providing modern Windows 11-style UI components

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

list-view-widgets.mddocs/

List and View Widgets

Advanced list, table, and tree components with custom delegates, smooth scrolling, and fluent design integration. These widgets provide modern data presentation with theme support and smooth interactions.

Capabilities

List Widgets

Enhanced list components with fluent design styling and smooth scrolling capabilities.

class ListWidget(QListWidget):
    def __init__(self, parent=None): ...
    def setItemDelegate(self, delegate: QAbstractItemDelegate): ...
    def setBorderVisible(self, visible: bool): ...
    def scrollToBottom(self): ...

class ListView(QListView):
    def __init__(self, parent=None): ...
    def setBorderVisible(self, visible: bool): ...
    def setItemDelegate(self, delegate: QAbstractItemDelegate): ...

class CycleListWidget(QListWidget):
    def __init__(self, parent=None): ...
    def setCurrentIndex(self, index: int): ...
    def currentIndex(self) -> int: ...

Usage Example:

from qfluentwidgets import ListWidget, ListView, CycleListWidget

# Basic list widget
list_widget = ListWidget(self)
list_widget.setBorderVisible(False)

# Add items
items = ["Item 1", "Item 2", "Item 3", "Item 4"]
for item in items:
    list_widget.addItem(item)

# Handle selection
list_widget.itemClicked.connect(self.on_item_clicked)

# Cycling list for navigation
cycle_list = CycleListWidget(self)
cycle_list.addItems(["Option A", "Option B", "Option C"])
cycle_list.setCurrentIndex(0)

Table Widgets

Enhanced table components with fluent design styling and custom delegates.

class TableWidget(QTableWidget):
    def __init__(self, parent=None): ...
    def __init__(self, rows: int, columns: int, parent=None): ...
    def setBorderVisible(self, visible: bool): ...
    def setBorderRadius(self, radius: int): ...
    def setWordWrap(self, wrap: bool): ...
    def setRowCount(self, rows: int): ...
    def setColumnCount(self, columns: int): ...

class TableView(QTableView):
    def __init__(self, parent=None): ...
    def setBorderVisible(self, visible: bool): ...
    def setBorderRadius(self, radius: int): ...

Usage Example:

from qfluentwidgets import TableWidget, TableView
from PyQt5.QtCore import QAbstractTableModel

# Basic table widget
table = TableWidget(self)
table.setRowCount(5)
table.setColumnCount(3)
table.setBorderVisible(True)
table.setBorderRadius(8)

# Set headers
table.setHorizontalHeaderLabels(["Name", "Age", "City"])

# Add data
data = [
    ("John", "25", "New York"),
    ("Alice", "30", "London"),
    ("Bob", "28", "Paris")
]

for row, (name, age, city) in enumerate(data):
    table.setItem(row, 0, QTableWidgetItem(name))
    table.setItem(row, 1, QTableWidgetItem(age))
    table.setItem(row, 2, QTableWidgetItem(city))

# Model-based table view
model = CustomTableModel(data)
table_view = TableView(self)
table_view.setModel(model)

Tree Widgets

Hierarchical data display with fluent design styling and smooth animations.

class TreeWidget(QTreeWidget):
    def __init__(self, parent=None): ...
    def setBorderVisible(self, visible: bool): ...
    def setBorderRadius(self, radius: int): ...
    def setHeaderHidden(self, hidden: bool): ...

class TreeView(QTreeView):
    def __init__(self, parent=None): ...
    def setBorderVisible(self, visible: bool): ...
    def setBorderRadius(self, radius: int): ...

Usage Example:

from qfluentwidgets import TreeWidget, TreeView
from PyQt5.QtWidgets import QTreeWidgetItem

# Tree widget with hierarchical data
tree = TreeWidget(self)
tree.setHeaderLabels(["Name", "Type", "Size"])
tree.setBorderVisible(True)

# Create tree structure
root = QTreeWidgetItem(tree, ["Documents", "Folder", ""])
child1 = QTreeWidgetItem(root, ["Report.pdf", "PDF", "2.5 MB"])
child2 = QTreeWidgetItem(root, ["Data.xlsx", "Excel", "1.2 MB"])

# Expand items
tree.expandAll()

# Handle item clicks
tree.itemClicked.connect(self.on_tree_item_clicked)

# Model-based tree view
tree_view = TreeView(self)
tree_model = CustomTreeModel()
tree_view.setModel(tree_model)

Flip View Widgets

Image gallery and content browsing widgets with smooth transitions.

class FlipView(QWidget):
    def __init__(self, parent=None): ...
    def addItem(self, item: Union[str, QPixmap, QWidget]): ...
    def setCurrentIndex(self, index: int): ...
    def currentIndex(self) -> int: ...
    def next(self): ...
    def previous(self): ...

class HorizontalFlipView(FlipView): ...
class VerticalFlipView(FlipView): ...

Usage Example:

from qfluentwidgets import FlipView, HorizontalFlipView

# Image flip view
flip_view = HorizontalFlipView(self)
flip_view.setFixedSize(400, 300)

# Add images
images = ["image1.jpg", "image2.jpg", "image3.jpg"]
for image_path in images:
    flip_view.addItem(image_path)

# Navigation controls
def next_image():
    flip_view.next()
    
def prev_image():
    flip_view.previous()

# Connect to buttons
next_btn.clicked.connect(next_image)
prev_btn.clicked.connect(prev_image)

Custom Item Delegates

Specialized item delegates for enhanced rendering and editing in list/table/tree widgets.

class ListItemDelegate(QStyledItemDelegate):
    def __init__(self, parent=None): ...
    def paint(self, painter: QPainter, option: QStyleOptionViewItem, index: QModelIndex): ...
    def sizeHint(self, option: QStyleOptionViewItem, index: QModelIndex) -> QSize: ...

class TableItemDelegate(QStyledItemDelegate):
    def __init__(self, parent=None): ...
    def paint(self, painter: QPainter, option: QStyleOptionViewItem, index: QModelIndex): ...

class TreeItemDelegate(QStyledItemDelegate):
    def __init__(self, parent=None): ...
    def paint(self, painter: QPainter, option: QStyleOptionViewItem, index: QModelIndex): ...

Usage Example:

from qfluentwidgets import ListItemDelegate, TableItemDelegate

# Custom list delegate
class CustomListDelegate(ListItemDelegate):
    def paint(self, painter, option, index):
        # Custom painting logic
        super().paint(painter, option, index)
        
    def sizeHint(self, option, index):
        return QSize(200, 40)  # Custom item size

# Apply delegate
list_widget = ListWidget(self)
custom_delegate = CustomListDelegate()
list_widget.setItemDelegate(custom_delegate)

# Table delegate
table_delegate = TableItemDelegate()
table_widget.setItemDelegate(table_delegate)

Advanced Features

Smooth Scrolling Integration

from qfluentwidgets import SmoothScrollArea, SmoothMode

# Smooth scrolling for list widgets
scroll_area = SmoothScrollArea(self)
scroll_area.setWidget(list_widget)
scroll_area.setWidgetResizable(True)
scroll_area.setSmoothMode(SmoothMode.COSINE)

Custom Selection Models

from PyQt5.QtCore import QItemSelectionModel

# Custom selection handling
selection_model = list_widget.selectionModel()
selection_model.selectionChanged.connect(self.on_selection_changed)

def on_selection_changed(self, selected, deselected):
    selected_items = selected.indexes()
    print(f"Selected {len(selected_items)} items")

Data Model Integration

from PyQt5.QtCore import QAbstractItemModel

class CustomListModel(QAbstractItemModel):
    def __init__(self, data):
        super().__init__()
        self.data = data
        
    def rowCount(self, parent=QModelIndex()):
        return len(self.data)
        
    def data(self, index, role=Qt.DisplayRole):
        if role == Qt.DisplayRole:
            return self.data[index.row()]
        return None

# Use with view widgets
model = CustomListModel(["Item 1", "Item 2", "Item 3"])
list_view = ListView(self)
list_view.setModel(model)

Styling and Themes

List and view widgets automatically adapt to the current theme:

from qfluentwidgets import FluentStyleSheet, isDarkTheme

# Apply fluent styling
FluentStyleSheet.LIST_WIDGET.apply(list_widget)
FluentStyleSheet.TABLE_WIDGET.apply(table_widget)
FluentStyleSheet.TREE_WIDGET.apply(tree_widget)

# Custom styling based on theme
if isDarkTheme():
    custom_style = """
        QListWidget {
            background-color: #2b2b2b;
            border: 1px solid #3c3c3c;
        }
        QListWidget::item:selected {
            background-color: #0078d4;
        }
    """
else:
    custom_style = """
        QListWidget {
            background-color: white;
            border: 1px solid #e0e0e0;
        }
        QListWidget::item:selected {
            background-color: #0078d4;
        }
    """

list_widget.setStyleSheet(custom_style)

Performance Optimization

Virtual Views for Large Datasets

# Use model-based views for large datasets
large_model = CustomListModel(large_dataset)
list_view = ListView(self)
list_view.setModel(large_model)

# Enable uniform item sizes for performance
list_view.setUniformItemSizes(True)

Lazy Loading

class LazyLoadModel(QAbstractItemModel):
    def __init__(self):
        super().__init__()
        self.cached_data = {}
        
    def data(self, index, role=Qt.DisplayRole):
        # Load data on demand
        if index.row() not in self.cached_data:
            self.cached_data[index.row()] = self.load_item(index.row())
        return self.cached_data[index.row()]

Install with Tessl CLI

npx tessl i tessl/pypi-pyqt-fluent-widgets

docs

buttons.md

dialog-notification.md

display-widgets.md

index.md

input-controls.md

layout-animation.md

list-view-widgets.md

material-effects.md

menu-command.md

multimedia.md

settings-config.md

theme-styling.md

window-navigation.md

tile.json